> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deep.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

> Every `deepspace` CLI command, with flags and examples.

This page documents every CLI command. For an overview and the dev loop, see [CLI overview](/cli-reference/overview).

```bash theme={null}
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.

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

## `login`

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.

```bash theme={null}
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.

<Warning>
  **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.
</Warning>

## `logout`

Clear the local session.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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. |

<Warning>
  **Don't kill a parallel session's processes.** If a sibling session is on 5173, run yours on `--port 5174` instead.
</Warning>

## `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

```bash theme={null}
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)

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
# 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`.

```bash theme={null}
# 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.

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

## `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.

```bash theme={null}
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)  |

## See also

* [CLI overview](/cli-reference/overview) - dev loop summary
* [Quickstart](/get-started/quickstart) - first-time walkthrough
* [Custom domains guide](/guides/custom-domains) - purchase and attach flow
* [Testing guide](/guides/testing) - the test runner in context