Command reference - DeepSpace

This page documents every CLI command. For an overview and the dev loop, see CLI overview.

npx deepspace <command> [options]

All commands support --help (or -h). The top-level deepspace command also accepts --version.

`create`

Shortcut for npm create deepspace@latest. Useful when you already have deepspace on your PATH (or as an npx target) and don’t want to switch CLIs to scaffold a new app.

npx deepspace create                  # interactive scaffold
npx deepspace create my-app           # named app

Internally this just runs npm create deepspace@latest [name] with stdio inherited.

`dev`

Run the app locally with Vite + worker in-process. HMR on localhost:5173.

npx deepspace dev
npx deepspace dev ./my-app            # run from a specific app directory
npx deepspace dev --port 5180         # parallel apps
npx deepspace dev --prod              # workers point at production (real auth, real API)

Arg / Flag	Default	Description
`[dir]`	`.`	App directory (positional).
`--port <n>`	`5173` (or `$DEEPSPACE_PORT`)	Listening port. Vite uses `--strictPort` - fails loudly if held.
`--prod`	off	Use production workers (real auth, real API calls).

dev rewrites the SDK-managed keys in .dev.vars on every run. User-added secrets (below the divider) are preserved.

`deploy`

Deploy to Workers for Platforms.

npx deepspace deploy                  # live at <wrangler.name>.app.space
npx deepspace deploy ./my-app         # deploy from a specific directory

Arg	Default	Description
`[dir]`	`.`	App directory (positional).

The subdomain comes from the name field in wrangler.toml. To change it, edit wrangler.toml before deploying - deploy doesn’t accept a name override. User secrets below the .dev.vars divider are uploaded as secret_text bindings. Custom bindings declared in wrangler.toml are validated and auto-provisioned if id = "auto".

`undeploy`

Tear down a deployed app and its subdomain.

npx deepspace undeploy                # reads name from ./wrangler.toml
npx deepspace undeploy my-app         # explicit app name

Arg	Default	Description
`[name]`	`wrangler.toml` `name` field	App name to undeploy (positional).

R2 buckets with files are not auto-deleted (preserves user uploads). Hyperdrive is never auto-provisioned and never auto-deleted. Authenticate via GitHub or Google OAuth. Opens a browser tab and polls up to 10 minutes. For CI/agent contexts, an email + password mode is also supported.

npx deepspace login                                  # browser-based OAuth
npx deepspace login --email me@x.test --password ******  # non-interactive

Flag	Description
`--email <addr>`	Email address (non-interactive mode). Requires `--password`.
`--password <pw>`	Password (non-interactive mode). Requires `--email`.

The session is stored at ~/.deepspace/session and is shared across all DeepSpace apps on the machine.

Don’t wrap in timeout N or sleep N && kill. OAuth needs the full polling window. Ctrl-C is safe - server-side state is preserved. Re-login only when whoami reports not signed in or the session has expired.

`logout`

Clear the local session.

npx deepspace logout

`whoami`

Print the current login state. The canonical login-state probe - it refreshes the JWT in the same call path that dev / test / deploy use.

npx deepspace whoami
npx deepspace whoami --json

Flag	Description
`--json`	Emit a single-line JSON object instead of human output.

Human output shows Name, Email, UserID, Type (developer / test-account), Issuer, and Dashboard URL. The JSON variant also includes expiresAt. On not-signed-in: prints an error to stderr (typically Not signed in. Run \deepspace login`.`) and exits 1.

`add`

Install a scaffold feature into the current app.

npx deepspace add --list                  # discover available features
npx deepspace add --info <name>           # inspect what a feature installs
npx deepspace add <feature>               # install into current dir
npx deepspace add <feature> ./my-app      # install into specific dir

Arg / Flag	Description
`[feature]`	Feature to install (positional).
`[dir]`	App directory (positional, default `.`).
`--list`, `-l`	List available features and exit.
`--info <name>`	Show details about a feature and exit.

Available features (subject to change - run --list for the current set): admin-page, ai-chat, canvas, cron, docs, file-attachments, file-manager, integration-test, items, kanban, landing, leaderboard, messaging, presence-test, sidebar, tasks, testing, topbar, tree Each feature installs source files, registers schemas, and runs npm install for any new dependencies. The command runs .deepspace/scripts/add-feature.cjs from the target directory, so it must be a scaffolded DeepSpace app.

`test`

Run tests against the dev workers. Auto-installs Playwright + Chromium on first run.

npx deepspace test                    # default = smoke + api
npx deepspace test smoke              # smoke only
npx deepspace test api                # api only
npx deepspace test e2e                # all Playwright specs
npx deepspace test unit               # vitest
npx deepspace test all                # vitest + Playwright
npx deepspace test tests/foo.spec.ts  # one file
npx deepspace test --port 5180        # match a parallel `dev`

Arg / Flag	Default	Description
`[suite]`	smoke + api	Suite name (`smoke`, `api`, `e2e`, `unit`, `all`) or a `*.spec.ts` file path.
`--port <n>`	`5173` (or `$DEEPSPACE_PORT`)	Port for Vite / Playwright’s `webServer`.

test requires a logged-in user (to mint APP_OWNER_JWT for .dev.vars). It regenerates .dev.vars against dev workers and forwards $DEEPSPACE_PORT to the Playwright child.

`screenshot`

Capture a Playwright screenshot of any URL. Shares the same Chromium install as test.

npx deepspace screenshot http://localhost:5173/ out.png
npx deepspace screenshot http://localhost:5173/ out.png --full-page
npx deepspace screenshot http://localhost:5173/ out.png --wait-for-timeout 500

Arg / Flag	Description
`<url>`	URL to capture (positional, required).
`<output>`	Output image path (positional, required).
`--full-page`	Capture the full scrollable page.
`--wait-for-timeout <ms>`	Milliseconds to wait before capture.

`kill`

Stop leaked workerd / wrangler / vite processes from prior dev runs.

npx deepspace kill                    # default port 5173
npx deepspace kill --port 5180
npx deepspace kill --all              # sweep every workerd/wrangler/vite

Flag	Default	Description
`--port <n>`	`5173` (or `$DEEPSPACE_PORT`)	Port whose listener (and its workerd children) to kill.
`--all`	off	Also sweep stray `workerd` / `wrangler` / `vite` processes anywhere on the machine.

Don’t kill a parallel session’s processes. If a sibling session is on 5173, run yours on --port 5174 instead.

`integrations` and `invoke`

Discover and call third-party integration endpoints. deepspace invoke ... is a top-level alias for deepspace integrations invoke ..., and invoke --list / invoke --info <target> are shortcuts for integrations list / integrations info <target>.

Discovery

npx deepspace integrations list                                  # full catalog
npx deepspace integrations list --json
npx deepspace integrations info openai/chat-completion           # schema + example body
npx deepspace integrations info openai/chat-completion --json

npx deepspace invoke --list                                      # same as `integrations list`
npx deepspace invoke openai/chat-completion --info               # same as `integrations info ...`

Calling endpoints (billed to the logged-in user)

npx deepspace integrations invoke openai/chat-completion --body '{"messages":[...]}'
npx deepspace invoke openai/chat-completion --body '{"messages":[...]}'
npx deepspace invoke openai/chat-completion --body-file req.json
cat req.json | npx deepspace invoke openai/chat-completion --body-file -

Flag	Alias	Description
`--body '<json>'`	`-d`	JSON request body inline
`--body-file <path>`	`-f`	Read body from file (or `-` for stdin)
`--json`		Print only the response JSON (machine-readable)
`--timeout <ms>`		Request timeout in milliseconds (default `120000`)
`--info`		(top-level `invoke` only) Print schema + example body for the target, then exit
`--list`		(top-level `invoke` only) Print all available integrations, then exit

`domain`

Buy, attach, and manage custom domains.

# Search and buy
npx deepspace domain search <query>
npx deepspace domain buy <domain>
npx deepspace domain buy <domain> --app <name> --yes
npx deepspace domain buy <domain> --no-open    # print URL instead of opening
npx deepspace domain buy <domain> --no-wait    # exit after Checkout session

# List and inspect
npx deepspace domain list
npx deepspace domain status <domain>

# Manage
npx deepspace domain attach <domain> --app <new-app-name>
npx deepspace domain detach <domain> --yes
npx deepspace domain renew <domain> --auto on|off

Subcommand	Args / Flags
`search`	`<query>` (required), `--limit <n>` (default 10), `--json`
`buy`	`<domain>` (required), `--app <name>`, `--yes`, `--no-open`, `--no-wait`, `--json`
`list`	`--json`
`status`	`<domain>` (required), `--json`
`attach`	`<domain>` (required), `--app <name>`, `--json`
`detach`	`<domain>` (required), `--yes`
`renew`	`<domain>` (required), `--auto on\|off` (required)

--app defaults to the name field in ./wrangler.toml. buy and detach require --yes in non-TTY contexts (otherwise they refuse rather than hang). Provisioning time varies by TLD: Cloudflare Registrar TLDs (.com, .dev, .app) take ~60–90 seconds; Porkbun / NameSilo TLDs (.ai, .io, .me) take 15–60 minutes.

`test-accounts`

Manage @deepspace.test accounts for Playwright multi-user tests. The pool is global per developer, hard cap of 10.

# List
npx deepspace test-accounts list

# Create
npx deepspace test-accounts create --email alice-1@deepspace.test --password Pass123! --name "Alice"

# Delete
npx deepspace test-accounts delete --email alice-1@deepspace.test
npx deepspace test-accounts delete --id <id>
npx deepspace test-accounts clear                # delete all (with confirm)
npx deepspace test-accounts clear --label e2e    # delete labeled subset
npx deepspace test-accounts clear --yes          # skip confirmation

Subcommand	Flags
`create`	`--email` (required, must end `@deepspace.test`), `--password` (required, min 8 chars), `--name`, `--label`
`list`	-
`delete`	`--email` or `--id` (exactly one)
`clear`	`--label <tag>`, `--yes`

Credentials are stored locally at ~/.deepspace/test-accounts.json (mode 0600). Public sign-up is intentionally disabled; these accounts are the only way to obtain signed-in browser contexts for tests.

`library`

Publish (or unpublish) your deployed app in the DeepSpace community library at deepdotspace-site.app.space.

# Publish the current app (reads name from ./wrangler.toml)
npx deepspace library publish

# Override metadata
npx deepspace library publish --app my-cool-app --name "My Cool App" \
  --description "A short tagline" --category Productivity \
  --tags utility,ai --visibility unlisted

# Remove an entry
npx deepspace library unpublish <handle>

Subcommand	Args / Flags
`publish`	`--dir <path>` (default `.`), `--app <name>` (default: `wrangler.toml` `name`), `--name <display>`, `--description <text>`, `--category <cat>` (default `General`), `--tags <a,b,c>`, `--visibility public\|unlisted\|private` (default `public`), `--screenshot <url>`, `--library-app <subdomain>`, `--json`
`unpublish`	`<handle>` (positional, required), `--library-app <subdomain>`, `--json`

library publish requires a logged-in session (deepspace login) and that the app is already deployed - the library server verifies you own the deployed app via the deploy worker’s registry before writing the entry. Publishing another user’s app is rejected server-side. <handle> for unpublish is the templateHandle returned by publish (usually the same as your app name). Only the owner (or an admin) can unpublish.

Deploy first. library publish registers the deployed app and its preview - run npx deepspace deploy before publishing, otherwise the ownership check fails.

`managed-repos`

Create and manage DeepSpace-owned private GitHub repositories. Intended for users who do not have or do not want to connect their own GitHub account; subject to per-developer quotas.

npx deepspace managed-repos list
npx deepspace managed-repos list --json

npx deepspace managed-repos create my-app
npx deepspace managed-repos create my-app --appId cli-my-app --nameHint my-repo

npx deepspace managed-repos token <repo-id>           # short-lived GitHub token
npx deepspace managed-repos delete <repo-id>
npx deepspace managed-repos delete <repo-id> --yes    # skip confirmation

Subcommand	Args / Flags
`list`	`--json`
`create`	`<appName>` (positional, required), `--appId`, `--nameHint`, `--json`
`token`	`<repoId>` (positional, required), `--json`
`delete`	`<repoId>` (positional, required), `--yes`, `--json`

token mints a short-lived GitHub access token scoped to the repo and prints a ready-to-use git clone command. delete removes the GitHub repository and counts against your daily delete quota.

Global flags

Flag	Available on	Purpose
`--help`, `-h`	every command	Print help (ANSI-free)
`--version`	top-level `deepspace`	Print CLI version
`--json`	discovery + status commands	Machine-readable output
`--yes`	`domain buy`, `domain detach`, `test-accounts clear`, `managed-repos delete`	Skip confirmation prompt

Environment

The CLI reads a small set of environment variables:

Variable	Used by	Purpose
`DEEPSPACE_PORT`	`dev`, `test`, `kill`	Default port when `--port` is not passed
`DEEPSPACE_AUTH_URL`	`login`, `logout`, `test-accounts`	Override auth-worker URL (advanced/testing)
`DEEPSPACE_API_URL`	`domain`, `invoke`, `integrations`, `managed-repos`, `deploy`	Override api-worker URL (advanced/testing)
`DEEPSPACE_DEPLOY_URL`	`deploy`, `undeploy`	Override deploy-worker URL (advanced/testing)
`DEEPSPACE_LIBRARY_HOST`	`library`	Override library host URL (advanced/testing)

Documentation Index

​create

​dev

​deploy

​undeploy

​login

​logout

​whoami

​add

​test

​screenshot

​kill

​integrations and invoke

​Discovery

​Calling endpoints (billed to the logged-in user)

​domain

​test-accounts

​library

​managed-repos

​Global flags

​Environment

​See also

`create`

`dev`

`deploy`

`undeploy`

`login`

`logout`

`whoami`

`add`

`test`

`screenshot`

`kill`

`integrations` and `invoke`

Discovery

Calling endpoints (billed to the logged-in user)

`domain`

`test-accounts`

`library`

`managed-repos`

Global flags

Environment

See also