@designsetgo/cli

Command-line tool for packaging and deploying DesignSetGo Apps bundles to WordPress, designed for vibe-coding from Claude Code, Cursor, or Codex.

Installation

npm install -g @designsetgo/cli
# or run without installing:
npx @designsetgo/cli apps init

Commands

designsetgo apps init [dir]

Scaffold a new app. Defaults to the minimal starter — a single index.html, no framework, no build step. Pass --astro for the multi-page Astro starter, or --template to scaffold from a private registry (Agency tier).

npx designsetgo apps init my-app                                                # minimal (default)
npx designsetgo apps init my-app --astro                                        # multi-page Astro starter
npx designsetgo apps init my-app --template booking-widget --registry acme
npx designsetgo apps init my-app --template [email protected] --registry acme
npx designsetgo apps init my-app --template booking-widget --registry https://acme.example/registry.json

Options:

• --id <id> — app id (lowercase, hyphenated; matches manifest id pattern)
• --name <name> — app display name
• --site <url> — site URL (writes .dsgorc.json so deploy and login default to this site)
• --astro — use the bundled Astro starter (multi-page, file-based routing, build step) instead of the minimal default
• --template <slug> — template slug (optionally with @version) from a private registry
• --registry <name|url> — registry alias (from apps registry list) or a full https:// URL

Template resolution order:

1. --registry <name> looks up the alias in ~/.config/designsetgo/registries.json.
2. --registry <https://...> fetches that URL directly.
3. If --registry is omitted but a default is configured, the default registry is used.
4. If --template is omitted and --astro is set, the bundled Astro starter is used.
5. If neither --template nor --astro is set, the bundled minimal starter is used.
6. If --template is supplied with no resolvable registry, the command fails (registry_alias_unknown).
7. --astro and --template cannot be combined; the command fails (astro_template_conflict).

Tarballs from a private registry are SHA-256 verified against the integrity field in registry.json and capped at 50 MB.

designsetgo apps registry (Agency tier)

Manage private template registries. Agencies host a registry.json index of starter bundles at any HTTPS URL they control; apps init scaffolds from those bundles instead of the bundled default.

designsetgo apps registry add <name> <url> [--token <token>] [--default] [--force]
designsetgo apps registry list
designsetgo apps registry remove <name>
designsetgo apps registry templates <name>

Config is stored at ~/.config/designsetgo/registries.json (mode 0600). The bearer token, if set, is sent as Authorization: Bearer ... on registry index and tarball requests.

See docs/superpowers/specs/2026-05-11-private-template-registry-design.md for the registry format.

designsetgo apps login [site]

Save WordPress Application Password credentials for a site. The site URL may be passed as a positional argument or via --site.

designsetgo apps login https://example.com
designsetgo apps login --site https://example.com

Options:

• --site <url> — site URL (alternative to the positional argument)
• --user <username> — WordPress username
• --app-password <password> — WordPress Application Password

Credentials are stored at ~/.config/designsetgo/credentials.json.

designsetgo apps logout [site]

Remove saved credentials for a site. The site URL may be passed as a positional argument or via --site.

designsetgo apps logout https://example.com
designsetgo apps logout --all

Options:

• --site <url> — site URL (alternative to the positional argument; defaults to the project site from .dsgorc.json)
• --all — remove all saved credentials

designsetgo apps dev [dir]

Start a local development server that hosts your app against a mocked or proxied bridge with hot reload. This is the recommended fast iteration loop for P2 developers. apps dev mock mode is free and requires no connected WP site.

npx designsetgo apps dev                                   # mock bridge, port 3838
npx designsetgo apps dev dist --port 4000                  # custom directory + port
npx designsetgo apps dev --bridge proxy --site https://example.com   # live bridge via direct WP proxy
npx designsetgo apps dev --bridge proxy --proxy-url https://proxy.example.com  # live bridge via hosted proxy
npx designsetgo apps dev --open                            # launch browser on start
npx designsetgo apps dev --no-watch                        # disable hot reload

Options:

• --port <n> — port to listen on (default 3838; auto-increments up to +10 on conflict)
• --bridge <mock|proxy> — bridge mode: mock (default, no WP site needed) or proxy (forwards every bridge call to a real site)
• --site <url> — WP site URL for proxy mode (required with --bridge proxy unless --proxy-url is set)
• --open — open the browser automatically on server start
• --no-watch — disable the chokidar file watcher and hot reload
• --proxy-url <url> — URL of a hosted @designsetgo/proxy instance (see below); takes precedence over --site in proxy mode
• --proxy-secret <secret> — bearer secret for the hosted proxy when --proxy-url is set

Bridge modes:

Mock mode (default) — serves plausible empty-state responses for every bridge method. dsgo.posts.list returns [], dsgo.storage.* is an in-memory map, dsgo.ai.prompt returns a placeholder. Override per-method by creating .dsgo/fixtures/{method}.json. dsgo.http.fetch is refused in mock mode to prevent accidental live API calls. No WP site required.

Proxy mode — forwards every bridge call to /wp-json/dsgo/v1/bridge-proxy on the configured WP site (Pro endpoint, same auth gate as CLI deploy). The dev shell never holds your Application Password; the CLI process carries it and attaches it per-call. Proxy mode is the correctness check before promote.

Bridge proxy server (@designsetgo/proxy):

For team workflows where multiple developers share a staging site, deploy the @designsetgo/proxy Node service so the WP Application Password lives server-side. Teammates pass --proxy-url instead of holding credentials locally:

# One-time: deploy the proxy
npx @designsetgo/proxy   # or Docker / Fly.io / Render — see proxy/README.md

# Each developer:
designsetgo apps dev --bridge proxy --proxy-url https://proxy.example.com --proxy-secret <secret>

In solo mode, the CLI auto-spawns a local proxy subprocess when --bridge proxy is used without --proxy-url. Set DSGO_DEV_AUTO_SPAWN_PROXY=0 to opt out and go direct to WP instead.

Hot reload: The dev shell subscribes to a Server-Sent Events stream (/__dsgo/events). On any file change in the watched directory, the iframe reloads within 500ms without reloading the parent shell. When dsgo-app.json changes, the manifest is re-validated before the reload fires; validation errors print to stderr.

designsetgo apps deploy [dir]

Bundle the current directory (or dir) and push it to the configured WordPress site — or to several sites in one run with --sites.

designsetgo apps deploy
designsetgo apps deploy dist --site https://example.com
designsetgo apps deploy dist --sites https://a.example.com,https://b.example.com

Options:

• --site <url> — site URL (overrides .dsgorc.json and DSGO_SITE)
• --sites <urls> — comma-separated site URLs to deploy to in a single run. The bundle is zipped once and pushed to each site in turn; a failure on one site does not abort the rest, and a per-site summary is printed at the end. Requires the Plus or Agency tier on every target site (the multi_site_cli preflight capability). Mutually exclusive with --site. Saved credentials are resolved per site (designsetgo apps login each one), or DSGO_USER + DSGO_APP_PASSWORD apply to all.
• --build — run npm run build before zipping
• --from-artifact <url> — deploy a Claude Artifact URL directly (no local files)
• --id <id> — manifest id (required with --from-artifact)
• --name <name> — manifest display name (defaults to --id when used with --from-artifact)
• --version <version> — manifest version (defaults to 0.1.0 with --from-artifact)
• --preview — upload as a time-boxed preview instead of installing the app (Pro). See --preview section below.
• --promote <id> — promote a preview to an installed app without re-uploading the bundle (Pro). See --promote section below.
• --password <pw> — set a cookie password on the preview (only valid with --preview or --promote)
• --require-login — require WP login to view the preview (only valid with --preview; mutually exclusive with --password)
• --ttl <days> — preview lifetime in days (default 7, max 30; only valid with --preview)
• --json — emit {"id": "...", "url": "...", "post_id": N} as a single line on stdout, suppressing the human-readable "Installed at …" message. Permission summary and preflight tips move to stderr so stdout is parseable. Useful for piping into jq or capturing into CI outputs. With --sites, emits a single {"multi_site": true, "results": [...]} summary line instead.

apps deploy --preview (Pro)

Upload a bundle as a time-boxed shareable preview on your WP site without promoting it to the installed-apps catalog. The preview renders at an unguessable token URL and expires after 7 days (configurable with --ttl). Use this to share apps with clients or stakeholders before going live.

npx designsetgo apps deploy --preview                      # basic preview, 7-day TTL
npx designsetgo apps deploy --preview --password swordfish # password-protected preview
npx designsetgo apps deploy --preview --require-login      # WP-login-gated preview
npx designsetgo apps deploy --preview --ttl 14             # 14-day preview

Output:

Preview deployed:
  URL:     https://mysite.com/dsgo-preview/booking-widget/a7c3f9e1/
  Expires: 2026-05-23 14:32 UTC (7 days)
  Promote: designsetgo apps deploy --promote prev_a7c3f9e1

Flag interactions:

• --preview is mutually exclusive with --from-artifact.
• --password and --require-login are mutually exclusive.
• --password, --require-login, and --ttl are only valid with --preview or --promote.

Preview limit: 10 active previews per user per site (filterable server-side via dsgo_max_active_previews_per_user). The CLI prints the list of your current previews if you hit the cap.

apps deploy --promote <id> (Pro)

Promote a preview to a real installed app without re-uploading the bundle. The preview URL remains valid until its original TTL expires.

npx designsetgo apps deploy --promote prev_a7c3f9e1

Output: Installed at https://mysite.com/apps/booking-widget; preview link remains valid until 2026-05-23 14:32 UTC.

designsetgo apps list [site]

List apps installed at the configured site. The site URL may be passed as a positional argument or via --site.

designsetgo apps list https://example.com
designsetgo apps list --json

Options:

• --site <url> — site URL (alternative to the positional argument)
• --json — output raw JSON instead of a table

designsetgo apps status [site] (alias whoami)

Show the resolved site, where it came from (positional, --site flag, DSGO_SITE, or .dsgorc.json), the active auth source (env vars vs. saved credentials), and a live reachable/authenticated check.

designsetgo apps status
designsetgo apps status https://example.com --json

Options:

• --site <url> — site URL (alternative to the positional argument)
• --json — emit a JSON report instead of a human-readable summary

Use this first when a deploy lands on the wrong site or auth fails unexpectedly.

designsetgo apps uninstall <id>

Remove an app from the configured site. Prompts for confirmation by default.

designsetgo apps uninstall my-app
designsetgo apps uninstall my-app --yes

Options:

• --site <url> — site URL
• --yes — skip the confirmation prompt (required in non-interactive contexts)

designsetgo apps open [id]

Open the site, a specific app, or the wp-admin apps page in the default browser.

designsetgo apps open                 # opens https://<site>/
designsetgo apps open my-app          # opens https://<site>/apps/my-app
designsetgo apps open --admin         # opens wp-admin/admin.php?page=designsetgo-apps
designsetgo apps open my-app --print  # prints the URL instead of launching

designsetgo apps logs <id>

Tail recent log entries for an installed app. Requires the designsetgo-apps plugin to expose /wp-json/dsgo/v1/apps/<id>/logs; older plugin versions return 404 with a helpful error.

designsetgo apps logs my-app
designsetgo apps logs my-app --limit 200 --json

Options:

• --site <url> — site URL
• --limit <n> — number of entries to fetch (1-1000, default 50)
• --json — output raw JSON

designsetgo apps preview (Pro)

Manage active previews on the configured site. All subcommands are Pro-gated.

designsetgo apps preview list                              # list your active previews
designsetgo apps preview delete <id>                      # delete a preview before its TTL
designsetgo apps preview extend <id> --ttl <days>         # extend a preview's TTL
designsetgo apps preview promote <id>                     # promote a preview to an installed app

apps preview list

List active previews for the current user on the configured site. Columns: id, slug, URL, expires at, password-protected flag, require-login flag.

Options:

• --site <url> — site URL
• --json — output raw JSON

apps preview delete <id>

Delete a preview before its TTL. Only the owner can delete their own previews.

Options:

• --site <url> — site URL
• --yes — skip the confirmation prompt

apps preview extend <id> --ttl <days>

Extend a preview's TTL. The server caps the new expiry at 30 days from the original creation time regardless of the requested value.

Options:

• --site <url> — site URL
• --ttl <days> — new lifetime in days from today (required)

apps preview promote <id>

Promote a preview to an installed app. Equivalent to apps deploy --promote <id> but works from preview list output without a local project directory. The preview URL remains valid until the original TTL.

Options:

• --site <url> — site URL

designsetgo apps doctor [site]

Run preflight checks before deploying: project config detected, site URL resolves, site reachable, designsetgo-apps plugin active, credentials valid, manifest parses.

designsetgo apps doctor
designsetgo apps doctor https://example.com --json

Options:

• --site <url> — site URL (alternative to the positional argument)
• --dir <dir> — bundle directory whose manifest to validate (defaults to cwd)
• --json — emit JSON instead of a checklist

designsetgo completion <shell>

Print a shell-completion script for bash, zsh, or fish. Source the output (or save it where your shell auto-loads completions).

designsetgo completion bash > ~/.local/share/bash-completion/completions/designsetgo
designsetgo completion zsh  > "${fpath[1]}/_designsetgo"
designsetgo completion fish > ~/.config/fish/completions/designsetgo.fish

Global flags

• --debug — print every HTTP request/response (with redacted auth) to stderr. Equivalent to setting DSGO_DEBUG=1. Useful for diagnosing CI failures or unexpected 4xx responses.

apps deploy --dry-run

deploy accepts --dry-run, which prints the resolved site, bundle directory, manifest summary, file list, and credentials source — then exits without uploading. Combine with --json for a parseable plan.

designsetgo apps deploy --dry-run
designsetgo apps deploy --dry-run --json | jq '.file_count'

Authentication

apps deploy, apps list, and apps logout all require credentials for the target site. The recommended approach for local development is apps login, which stores an Application Password in ~/.config/designsetgo/credentials.json.

For CI and scripted deploys, use environment variables instead (see below).

Environment variables

apps deploy honors three environment variables in addition to the saved-credentials file:

| Variable | Effect | |----------------------|-----------------------------------------------------------------------------------------------------| | DSGO_SITE | Default site URL when --site is not passed (existing behavior). | | DSGO_USER | WordPress username for env-var auth. Both this and DSGO_APP_PASSWORD must be set together. | | DSGO_APP_PASSWORD | WordPress Application Password for env-var auth. Whitespace is stripped (paste the WP format as-is).|

When DSGO_USER and DSGO_APP_PASSWORD are both set, apps deploy skips the saved-credentials lookup entirely — useful in CI, Makefiles, or scripted deploys where you don't want a credentials file on disk. Setting only one of the two errors out with partial_env_credentials to catch CI config bugs.

If neither is set, the existing ~/.config/designsetgo/credentials.json lookup runs as before.

Project config

Create a .dsgorc.json at the root of your app directory to set a default site URL:

{
  "site_url": "https://example.com"
}

apps init --site <url> writes this file for you.

Bridge proxy server

@designsetgo/proxy is a companion Node service for apps dev --bridge proxy. It holds the WP Application Password server-side so teammates never handle credentials directly. See proxy/README.md for deployment instructions (Fly.io, Render, Docker).

Solo mode: the CLI auto-spawns a local proxy subprocess when --bridge proxy is used without --proxy-url. Set DSGO_DEV_AUTO_SPAWN_PROXY=0 to go direct to WP instead.

Team mode: deploy the proxy to a host, set DSGO_PROXY_UPSTREAM, DSGO_PROXY_WP_USERNAME, DSGO_PROXY_WP_APP_PASSWORD, and DSGO_PROXY_SECRET in the host's env, then pass --proxy-url and --proxy-secret to apps dev.

License

MIT