# Command reference Per-command flags and examples for every `deepspace` command (large page - prefer search for one command). This page documents every CLI command. For an overview and the dev loop, see [CLI overview](/cli-reference/overview). ```bash npx deepspace [options] ``` The surface is **noun-verb**: related commands are grouped under a noun (`auth`, `app`, `dev`, `test`, `secrets`, `workspace`, `integrations`, `agent`). Running a group on its own prints its subcommands - `deepspace dev` does not start a server, `deepspace dev start` does. All commands support `--help` (or `-h`). The top-level `deepspace` command also accepts `--version`. Every command listed here supports `--json` unless noted. An unknown command path never falls back silently to root help. The CLI searches the **full** command tree - subcommands included - by lexical distance and answers with a concrete suggestion: `deepspace login` prints ``did you mean `deepspace auth login`?``, and a misplaced leaf like `deepspace whoami` resolves to its nested home `deepspace auth whoami`, not merely the nearest top-level group. Under `--json` the same situation is a coded refusal. Suggestions naming a destructive verb (`delete`, `rm`, `remove`, `drop`, `clear`, `undeploy`, `kill`) stay in the prose and are never handed back as an executable `action` - destructive commands have to be typed on purpose. ## Command map | Group | Commands | | -------------- | ------------------------------------------------------------------------------------------------------------------------ | | *(top level)* | `status`, `activity`, `logs`, `push`, `pull`, `clone`, `releases`, `rollback`, `deploy`, `testflight`, `add`, `feedback` | | `auth` | `login`, `logout`, `whoami` | | `app` | `create`, `init`, `list`, `files`, `undeploy`, `transfer`, `collaborators`, `domain`, `usage`, `source`, `update` | | `dev` | `start`, `kill` | | `test` | `run`, `screenshot`, `accounts` | | `secrets` | `list`, `set`, `get`, `delete`, `upload`, `download`, `pull`, `configs` | | `workspace` | `new`, `attach`, `sync`, `list`, `status`, `land`, `drop` | | `integrations` | `list`, `info`, `invoke` | | `agent` | `tools`, `invoke` | ## `auth` Session management. Login is shared across every app on the machine and stored at `~/.deepspace/session`. ### `auth login` Opens a browser to sign in with GitHub or Google. DeepSpace accounts are OAuth-only. ```bash npx deepspace auth login ``` | Flag | Description | | ------------------ | ------------------------------------------------------------- | | `--email ` | Email address, password accounts only (or `$DEEPSPACE_EMAIL`) | | `--password ` | Password. Discouraged - visible in `ps` and shell history | | `--password-stdin` | Read the password from stdin instead of `--password` | | `--json` | Single-line JSON result | The password flags sign in `@deepspace.test` [test accounts](#test-accounts) and internally provisioned maintainer accounts. **Regular DeepSpace accounts have no password.** To run an agent or a CI job as yourself, reuse the stored session instead - see [agents and CI](/cli-reference/overview#agents-and-ci), which also covers the `interactive_required` refusal. **Don't wrap browser login in `timeout N`.** The OAuth flow polls for up to ten minutes. Ctrl-C is safe - server-side state is preserved. Password login refuses through the same envelope as every other command: a `401` from the auth service is `invalid_credentials` (wrong email or password); any other refusal - or a session issued without a cookie or token - is `login_failed`. A `--json`/non-TTY call with no credentials is `interactive_required` (above). Credentials are stored per auth plane, so a login under `DEEPSPACE_ENV=staging` or a `DEEPSPACE_AUTH_URL` override never touches your production session - see [login state](/cli-reference/overview#login-state). ### `auth logout` Sign out and remove cached credentials. ```bash npx deepspace auth logout ``` ### `auth whoami` Print the current login state. This is the canonical login probe - it refreshes the JWT through the same path `dev`, `test`, and `deploy` use. ```bash npx deepspace auth whoami npx deepspace auth whoami --json ``` On not-signed-in it prints an error to stderr and exits non-zero. ## `app` Everything about the app as a platform object: its identity, its files, who can deploy it, and where its source lives. ### `app create` Scaffold a new app. Runs `create-deepspace`; all flags are forwarded. ```bash npx deepspace app create my-app npx deepspace app create my-app --template copilot ``` | Arg / Flag | Description | | ------------------- | ------------------------------------------------------------------ | | `[name]` | App name | | `--interactive` | Prompt for options instead of using defaults | | `--template ` | Starter template: `starter` (default) or `copilot` | | `--local ` | Use a local SDK monorepo checkout instead of the published package | `npm create deepspace@latest my-app` does the same thing without needing the CLI on PATH. ### `app init` Mint this app's immutable `DEEPSPACE_APP_ID` into `wrangler.toml`. ```bash npx deepspace app init npx deepspace app init --new-id # fork this repo as a SEPARATE app ``` | Flag | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `--new-id` | Replace the existing id - forks this repo as a separate app with new data, new secrets, new registration. The original keeps running. | | `--env `, `-e` | `wrangler.toml` `[env.]` block to stamp (each env is its own app) | The app id is the app's permanent identity. The `name` field in `wrangler.toml` is only the subdomain label; data, secrets, and collaborators key to the id, so renames are safe. "Already initialized" means **registered**, not merely id-shaped: `init` verifies the id with the platform before claiming done. The outcomes, and what `--json` carries: | Outcome | `status` / code | Notes | | ---------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Fresh registration | `status: "registered"` | `appId`, `committedScaffold` (true when `init` made the initial commit), and a `git commit … wrangler.toml` action when the file is left uncommitted | | `--new-id` on a registered id | `status: "forked"` | `previousAppId` names the id it replaced; the original app is untouched | | Id already registered to you | `status: "already_initialized"` | exit 0, nothing written | | Id was minted locally by an older SDK and never registered | refuses `app_not_registered` | ships the executable `app init --new-id` action - there is no server-side state to migrate, so the fork is the one next command | | Id belongs to another account (a cloned repo) | refuses `not_app_owner` | no action: forking is a data decision | | `DEEPSPACE_APP_ID` is present but malformed | refuses `invalid_app_id` | ids are server-minted, so a malformed one was hand-edited - restore it, or pass `--new-id` to replace it; the result then carries `replacedMalformed` naming the value it overwrote | Every result also names the plane and the slot: `env` is the platform plane the registration lives on (`production` unless `DEEPSPACE_ENV` says otherwise - the same field `status --json` reports), and `wranglerEnv` is the `[env.]` block (`null` for the top level). ### `app list` List every app you can access - both apps you own and apps shared with you as a collaborator, deployed and registered alike. The ROLE column shows your access on each. ```bash npx deepspace app list npx deepspace app list --json ``` ### `app files` Upload and manage the app's own files allocation - images, media, and other assets served from the app's origin. ```bash npx deepspace app files put logo.png npx deepspace app files put hero.jpg --key img/hero.jpg npx deepspace app files list --prefix img/ npx deepspace app files get img/hero.jpg --out ./hero.jpg npx deepspace app files rm img/hero.jpg ``` | Subcommand | Args / Flags | | ---------- | -------------------------------------------------------------------------------------------------- | | `put` | `` (required), `--key ` (default: the file name), `--private`, `--app ` | | `list` | `--prefix

`, `--limit ` (1-1000, default 100), `--private`, `--app ` | | `get` | `` (required), `--out ` (default: the key's file name), `--private`, `--app ` | | `rm` | `` (required), `--private`, `--app ` | `--private` addresses your own private folder in the app (served with `?scope=self`, readable only by you) instead of the public app files. Keys are relative to the app (`logo.png`, `img/hero.jpg`). The platform owns the physical prefix and validates every key against it, so a key can never address another app. That prefix is part of the serving URL: files are reachable from your app's origin at `/api/files/apps//?scope=app`, which `put` prints for you (and returns as `path` under `--json`). The relative key alone does not resolve. See [large files and media](/guides/file-uploads#large-files-and-media) for when to reach for this instead of Git. **1 GiB per file; 25 MiB per request** — larger files upload in parts automatically. The server refuses declared active-content types (HTML, SVG, JS); disguised bytes can be stored but are always served with their stored type and `nosniff`, so they never execute in your app's origin. ### `app collaborators` Authorize other people to deploy your app. See the [collaborators guide](/guides/collaborators) for the full model. ```bash npx deepspace app collaborators list npx deepspace app collaborators add teammate@example.com npx deepspace app collaborators remove teammate@example.com npx deepspace app collaborators cancel invited@example.com npx deepspace app collaborators invites # invites waiting for YOUR email npx deepspace app collaborators accept app_01H… # accept one, no email link needed ``` | Subcommand | Args / Flags | | ---------- | -------------------------------------------------------------------------------- | | `list` | `--app `, `-a` | | `add` | `` (required), `--app ` | | `remove` | `` (required), `--app ` | | `cancel` | `` (required), `--app ` - cancels a pending, un-accepted invite | | `invites` | none - lists pending invites addressed to the signed-in email | | `accept` | `` (required) - accepts an invite as the signed-in invitee | Collaborators have **owner-equivalent deploy access**. Only add people you trust. ### `app undeploy` Remove a deployed app. ```bash npx deepspace app undeploy # reads DEEPSPACE_APP_ID from wrangler.toml npx deepspace app undeploy my-app # explicit app id or subdomain name ``` | Arg / Flag | Description | | -------------- | ----------------------------------------------------------------------------------------- | | `[name]` | App id or subdomain name (positional). Reads `wrangler.toml` if omitted. | | `--env ` | `[env.]` block whose deployed app to remove. Ignored if a positional name is given. | | `--yes` | Skip the interactive confirmation | **At an interactive terminal `undeploy` confirms before the URL goes dark**, and the default answer is **No**. The prompt names the app (its wrangler `name` and id) and states exactly what happens: the URL stops serving immediately and the app's data - records, messages, canvas state, cron history - is destroyed with the worker's Durable Objects, while secrets and the registration stay and the name is reserved for you for 30 days. Declining refuses with the code `undeploy_declined` and changes nothing. Pass `--yes` to skip the prompt. Scripts and agents are never prompted: if stdin is not a TTY, or `--json` was passed, the command refuses `confirmation_required` without `--yes`, so a machine caller neither hangs nor treats invocation as consent. Undeploying an app that is not serving is a no-op, and says so: the result carries `alreadyUndeployed: true` with an empty `releasedHosts`, and the human line reads "was already offline". A real takedown lists the released hosts and `alreadyUndeployed: false`. Either way the app keeps its id; a later `deploy` revives it - see [undeploy and revival](/guides/app-identity#undeploy-and-revival). ### `app transfer` Transfer app ownership to another DeepSpace user. Two-sided: the owner offers, the recipient accepts. ```bash npx deepspace app transfer offer newowner@example.com npx deepspace app transfer status npx deepspace app transfer accept npx deepspace app transfer cancel # either party ``` The recipient must have signed in to DeepSpace at least once. Against an email with no DeepSpace user, `offer` fails with `user_not_found`. (This is unlike `collaborators add`, which emails an invite to strangers.) ### `app domain` Buy, attach, and manage custom domains. See the [custom domains guide](/guides/custom-domains). ```bash npx deepspace app domain search npx deepspace app domain buy npx deepspace app domain list npx deepspace app domain status npx deepspace app domain attach --external npx deepspace app domain verify npx deepspace app domain detach npx deepspace app domain renew ``` | Subcommand | Purpose | | ---------- | ------------------------------------------------------------------------------ | | `search` | Search for available domains | | `buy` | Buy a domain and attach it to an app | | `list` | List your domains | | `status` | Show details for one domain | | `attach` | Re-point a registered domain; use `--external` for one bought elsewhere | | `verify` | Verify external DNS ownership, provision the certificate, and activate routing | | `detach` | Stop routing the domain (keeps the registration; auto-renew unchanged) | | `renew` | Toggle auto-renewal at the registrar | ### `app usage` Show account-wide credit balance, quota headroom, and per-integration spend. The result is not scoped to the selected app. ```bash npx deepspace app usage npx deepspace app usage --json ``` JSON output includes `"scope": "account"` so automation does not mistake it for per-app usage. ### `app source` Report the app's one authoritative Git repository. **Read-only** — source latches permanently on first source use and is never declared by a setter (see [source control](/guides/source-control)). ```bash npx deepspace app source # report: claimed source, or unclaimed npx deepspace app source --json # { source: {...} | null, revision, ... } ``` | Arg / Flag | Description | | ------------------------ | --------------------------------- | | `--app `, `-a` | Target app (default: current app) | The old setter form (`app source github|deepspace`) refuses with `source_inferred`. An app has exactly one source of record: under DeepSpace source, `push`/`pull`/`clone`/`workspace` operate on the cloud repo and `deploy` synchronizes before shipping; under GitHub, you manage commits with normal Git and `deploy` ships the local working tree without touching Git. The first deploy with a selected GitHub remote claims that repository; the first `deepspace push`, or first deploy without one, claims DeepSpace source. The claim is permanent, and the latching release records revision 1. `status --json` reports an unclaimed app's next-deploy prediction as `sourceInference`. `deploy` removes a claimed-GitHub app's stale `space` remote. ### `app update` Inspect an app and print the exact work needed to move it to the running CLI's SDK version. Run the **target** CLI before installing the target SDK - it owns that release's checklist: ```bash npx deepspace@latest app update --json ``` `app update` is deliberately read-only: it does not edit `package.json`, rewrite source, stamp `deepspace.migrations.json`, run an installer, or require DeepSpace source control. Every successful result carries `writes: []` and no executable action. The JSON result contains: | Field | Meaning | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `status` / `ready` | `aligned` is the only ready state. Other successful states are `guidance_available`, `dependency_unverified`, `cli_version_behind`, and `version_gap_too_wide`. | | `currentSpec` / `targetVersion` | The app's declared `deepspace` spec and the running CLI's package version. The CLI you invoked is the sole target authority. | | `dependencies` | Manual `package.json` edits, including the compatible direct `ai` dependency when the app declares one. Local, workspace, VCS, and URL SDK specs are left under the developer's control and reported as unverified. | | `migrations` | Outstanding app-owned changes, each with an id, description, candidate files, and guidance. After applying and validating one, add its id to `deepspace.migrations.json`; mark it not applicable there when the named seam does not exist. | | `manualInstructions` | Policy or dependency checks that cannot be inferred safely, such as an app-owned users-schema visibility choice. | | `steps` | The ordered checklist assembled from those fields: edit dependencies, install when needed, apply migration guidance, type-check, test, review, and commit. | | `guidanceUrl` | The release-specific migration reference. | A malformed `package.json` or `deepspace.migrations.json` refuses with `invalid_package_manifest` or `invalid_migration_manifest`; neither file is repaired automatically. A wide version gap is a successful `version_gap_too_wide` guide rather than a failed partial migration. The full sequence, and what to do with a scaffold that predates server-minted ids, is in [Updating an app](/guides/updating). ## `dev` ### `dev start` Run the app locally with Vite and the worker in-process, with HMR. ```bash npx deepspace dev start npx deepspace dev start ./my-app npx deepspace dev start --port 5180 # parallel apps npx deepspace dev start --env staging ``` | Arg / Flag | Default | Description | | -------------------- | ----------------------------- | ----------------------------------------------------------------------- | | `[dir]` | `.` | App directory (positional) | | `--port ` | `5173` (or `$DEEPSPACE_PORT`) | Port to bind | | `--env `, `-e` | - | `[env.]` block to run. Applies the env's overrides at build time. | `dev start` regenerates `.dev.vars` **whole** on every run - SDK-managed keys plus the selected config from the [secrets store](/guides/secrets). Hand edits are overwritten; set values with `secrets set`, and restart dev to pick up store changes. If the store refresh fails, `dev start` aborts rather than run against stale values. Under `--json`, the server's own output still streams through. `dev start` emits **two** envelopes: a readiness line (`{"ok":true,"ready":true,"url":...}`) the moment the server is up, and a final exit envelope when it stops - the last line of output, not the only one. ### `dev kill` Stop the local dev server and any orphaned `workerd` processes. ```bash npx deepspace dev kill npx deepspace dev kill --port 5180 npx deepspace dev kill --all ``` | Flag | Default | Description | | ------------ | ----------------------------- | --------------------------------------------------------------- | | `--port ` | `5173` (or `$DEEPSPACE_PORT`) | Port the dev server is bound to | | `--all` | off | Also kill stray `workerd`/`wrangler` processes across all ports | **Don't kill a parallel session's processes.** If a sibling session is on 5173, run yours on `--port 5174` instead of using `--all`. ## `test` ### `test run` Run tests against the dev workers. Auto-installs Playwright and Chromium on first run. ```bash npx deepspace test run # default = smoke + api npx deepspace test run smoke npx deepspace test run e2e npx deepspace test run unit # vitest npx deepspace test run all npx deepspace test run tests/checkout.spec.ts # one file npx deepspace test run --port 5180 npx deepspace test run e2e --grep "sign in" # only matching Playwright tests ``` | Arg / Flag | Default | Description | | -------------------- | ----------------------------- | -------------------------------------------------------------------------------- | | `[suite]` | smoke + api | `smoke`, `api`, `e2e`, `unit`, `all`, or a path ending in `.spec.ts` | | `--port ` | `5173` (or `$DEEPSPACE_PORT`) | Port for Vite / Playwright's `webServer` | | `--env `, `-e` | - | `[env.]` block to test (uses secrets config `` by default) | | `--grep ` | - | Run only Playwright tests whose title matches (forwarded to Playwright `--grep`) | | `--project ` | - | Run only the named Playwright project (forwarded to `--project`) | | `--headed` | off | Run Playwright headed instead of headless | The default suite (`smoke + api`) does not include `e2e`; run `test run e2e` or `test run all` to exercise end-to-end specs, including any you add. An unrecognized `[suite]` refuses with `unknown_suite` and names every way to narrow a run - the five suite names, a path to a single spec file (`tests/.spec.ts`), and `--grep ` for part of a suite. Without those, the reader's next move was moving spec files out of `tests/` to isolate one. `test run` requires a logged-in user - it mints an app-owner JWT into the regenerated `.dev.vars`. The runner owns its web server: a live server already on the port refuses `port_in_use` before any install or Playwright work (a previous run's server still shutting down gets a bounded grace first) - the same guard and remedy `dev start` uses. Stop it with `deepspace dev kill` or pass another `--port`. **The Playwright dependency preflight writes to stderr under `--json`**, like the suite itself, so it cannot corrupt the stdout envelope. On Linux as root it also announces itself before starting: installing Chromium's system libraries shells out to `apt-get`, which is minutes of transcript on a cold container - the line up front is what distinguishes that from a hang. Under `--json` the suite streams on **stderr** and stdout carries exactly one JSON envelope, so `npx deepspace test run --json | jq` works with no last-line handling and the live Playwright/vitest transcript stays visible. (`test screenshot --json` routes its child's output to stderr the same way, so its stdout also carries exactly one envelope.) The envelope names what the run left out: `skippedSpecs` lists the spec files the chosen suite did not run - the default `smoke + api` suite reports every spec outside it - so a green result cannot be mistaken for full coverage. Human output prints the same fact as a `skipped N spec file(s) ...` line. ### `test screenshot` Capture a Playwright screenshot of any URL. Shares the same Chromium install as `test run`. ```bash npx deepspace test screenshot http://localhost:5173/ out.png npx deepspace test screenshot http://localhost:5173/ out.png --full-page npx deepspace test screenshot http://localhost:5173/ mobile.png --viewport 390x844 npx deepspace test screenshot http://localhost:5173/ out.png --wait-for-timeout 500 ``` | Arg / Flag | Description | | -------------------------------- | -------------------------------------------------------------------- | | `` | URL to capture (required) | | `` | Output image path (required) | | `--full-page` | Capture the full scrollable page | | `--viewport ` | Set positive browser viewport dimensions, for example `390x844` | | `--wait-for-timeout ` | Milliseconds to settle before capture (default `1000`; `0` disables) | | `--wait-for-selector ` | Also wait for a visible selector before capture (off by default) | ### `test accounts` Manage `@deepspace.test` accounts for multi-user Playwright tests. Unlike your own account, these sign in with **email and password** - that is what makes them usable as fixtures. They are heavily restricted in exchange; see [restrictions](/guides/testing#what-test-accounts-cannot-do). Only an OAuth-authenticated developer can create them. ```bash npx deepspace test accounts list npx deepspace test accounts create npx deepspace test accounts delete --email alice-1@deepspace.test npx deepspace test accounts clear ``` | Subcommand | Purpose | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `create` | Create a test account. `--name` sets the `users()` selector; omit it and the selector defaults to the email's local part | | `list` | List your test accounts. `--usable` shows only those with locally saved credentials (the ones `users()` can drive); passwords are masked unless you pass `--reveal`. `--json` adds a `usableByFixture` flag, and honours `--reveal` the same way: without it the `password` field is **omitted**, with it the locally saved password (or `null`) is included | | `delete` | Delete a test account by `--email` or `--id`. Immediate - it **never** prompts, and has no `--yes` | | `clear` | Delete all your test accounts (or those matching `--label`). This one confirms, and `--yes` skips it | Every account prints a `Selector:` - the string to pass `users(['Selector'])`. Test accounts cannot deploy apps or be added as [collaborators](/guides/collaborators). **`create` never echoes the password**, on either surface. You supplied it with `--password`, so repeating it only puts a live credential into terminal scrollback, CI logs, and agent transcripts. It is written 0600 to the local test-accounts file, and both surfaces name that file instead - `savedTo` in `--json`. Read it back deliberately with `test accounts list --reveal`. `delete` is unambiguous - one named account - which is why it runs immediately; `clear`, which empties the whole pool, is the verb that confirms. `delete --help` says so, so a teardown script does not have to discover it by hanging. ## `secrets` Manage the app's secrets store. Secrets live in named **configs** (default `prd`); `--env ` selects that environment's app id *and* its config. The store is the only deploy input - `.dev.vars` is a generated cache. The [secrets guide](/guides/secrets) carries the model, caps, and troubleshooting. ```bash npx deepspace secrets list npx deepspace secrets set STRIPE_KEY=sk_live_... OPENAI_KEY=sk-... npx deepspace secrets get STRIPE_KEY --plain npx deepspace secrets delete STRIPE_KEY npx deepspace secrets upload .env.production npx deepspace secrets download --format json npx deepspace secrets pull # refresh the .dev.vars cache npx deepspace secrets configs list ``` Every subcommand accepts these: | Flag | Description | | ----------------------- | --------------------------------------------------------------------- | | `--app `, `-a` | App id (default: `DEEPSPACE_APP_ID` from the nearest `wrangler.toml`) | | `--config `, `-c` | Config name (default: the `--env` name, or `prd`) | | `--env `, `-e` | `[env.]` slot - selects that env's app id and config | | Subcommand | Extra flags | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `list` | `--only-names` - print names only, omitting values and metadata | | `set` | `` (repeatable, required) | | `get` | `` (required), `--plain` - print the plaintext value | | `delete` | `` (repeatable, required) | | `upload` | `` (required; `-` for stdin), `--replace` - delete keys missing from the file | | `download` | `--format dotenv\|json\|shell` (default `dotenv`) | | `pull` | - | | `configs` | `list`; `create ` with `--copy-from ` for a server-side copy (refuses to copy over an existing config); `delete ` | The app is resolved **before** the token is read, through the same resolver `deploy` uses, so a missing target never surfaces as `not_authenticated`: outside an app directory it is `not_in_app_repo`, inside one whose `wrangler.toml` has no id it is `app_not_initialized` (with the `app init` action), and a malformed id is `invalid_app_id`. `upload` with a path that does not exist refuses `file_not_found` (pass a dotenv/JSON path, or `-` for stdin). A transport failure reaching the deploy service - offline, DNS, refused connection - is `network_error`, naming the URL and `DEEPSPACE_DEPLOY_URL`, rather than a bare `fetch failed`. ## `workspace` Durable parallel-agent workspaces: a server-side ref plus a local worktree, so several agents or people can work on one app without colliding. ```bash npx deepspace workspace new -t "add billing page" npx deepspace workspace status npx deepspace workspace sync npx deepspace workspace land npx deepspace workspace list npx deepspace workspace attach ws_... npx deepspace workspace drop ``` | Subcommand | Args / Flags | | ---------- | -------------------------------------------------------------------------------------------------------------------- | | `new` | `--task `, `-t` (required), `--base `, `--dir ` (default `.deepspace/ws/`), `--app` | | `attach` | `` (required), `[dir]`, `--app` | | `sync` | `--workspace `, `-w` (default: inferred from the `ws/` branch), `--app` | | `list` | `--all` (include landed/dropped), `--limit ` (default 50), `--app` | | `status` | `--workspace `, `-w`, `--app` | | `land` | `--into ` (default: cloud repo default branch), `--workspace `, `--keep-worktree`, `--validate`, `--app` | | `drop` | `[id]` (default: inferred from the branch), `--keep-worktree`, `--app` | `land --validate` runs the project validation on the merged tree before publishing trunk, and exits 2 on failure. ## Version control These operate on the app's cloud repo when the app uses `deepspace` source. Under `github` source all three refuse identically with `source_managed_by_github`, whose `--json` carries `repository` and `appId` - use normal Git instead. See [the refusal the source verbs share](/guides/source-control#the-refusal-the-source-verbs-share). ### `push` Push local git commits to the app's cloud repo. ```bash npx deepspace push npx deepspace push --branch feature-x ``` | Flag | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `--branch `, `-b` | Branch to push (default: the current branch) | | `--app `, `-a` | Target app | | `--force` | Allow a non-fast-forward ref move. Guarded: refuses whenever the remote tip is a commit your branch does not contain, so no work is silently dropped. | **Push size ceilings: 20 MiB per object, 32 MiB of compressed history per push.** An oversized push is refused with `push_too_large`. Untracking the file (`git rm --cached` + `.gitignore`) does **not** fix it - the blob stays reachable from the commit that introduced it and the next push is refused identically. You must drop the file from the commits that carry it, or rewrite history if it was already pushed. Large media belongs in [`app files`](#app-files), not Git. Two different empty-repo refusals, deliberately kept apart: * `no_commits` - the branch genuinely has no commits. On an **uninitialized scaffold** (`wrangler.toml` still holds the `__APP_ID__` placeholder) this is `actionRequired: true` and **exit 2**, carrying an executable `app init` action - the same tier as `deploy`'s `app_not_initialized`, since it is the same remedy. `app init` registers the app *and* makes the initial commit, so committing first would put an unregistered placeholder into history. On an already-registered app the same code stays an ordinary exit 1 with no action: "commit first" is not one command. * `unknown_branch` - the repo has commits but the named branch does not exist (a typo'd `-b`). Committing on the current branch would never make the missing ref appear, so this gets its own code and remedy: create or switch to the branch first. `push`, `pull`, and `deploy` share one more guard: a worktree in the middle of a merge, rebase, cherry-pick, or revert refuses `merge_in_progress` before touching the network. `HEAD` is the pre-operation commit then, so a push would publish a commit carrying none of the in-flight work and report success, and a pull would report `up_to_date` having touched nothing. The refusal names both remedies (`--continue` or `--abort`) and ships no single action, because finishing and abandoning are different decisions. ### `pull` Fetch the app's cloud repo and fast-forward the local branch. ```bash npx deepspace pull npx deepspace pull --branch main ``` Exits 2 only when one executable local continuation remains. ### `clone` Clone an app's cloud repo into a new directory. ```bash npx deepspace clone my-app npx deepspace clone app_01ABC... ./local-dir ``` | Arg | Description | | ------- | --------------------------------------------------- | | `` | App id (`app_...`) or subdomain name (required) | | `[dir]` | Target directory (default: the app name you passed) | ### `releases` List the app's deploy history. Releases are immutable. ```bash npx deepspace releases npx deepspace releases --limit 50 ``` | Flag | Description | | ------------------------ | ------------------------------------------------------- | | `--app `, `-a` | Target app (default: the surrounding app directory) | | `--env `, `-e` | `[env.]` slot - selects that environment's app id | | `--limit ` | Max entries (default 20) | Under `--json`, each entry carries `rollbackAvailable` - storage pressure can evict an old bundle while its ledger row remains - plus the stable opaque `actor` id and viewer-relative `byYou`. The internal Workers-for-Platforms upload ETag is not a public version id. What a release records depends on the app's source mode; see [Releases and rollback](/guides/releases-and-rollback). `releases`, `status`, and `activity` describe a release's source through one shared formatter, so a GitHub-source release reads `GitHub · owner/repo` on all three human surfaces instead of the "no source recorded" they used to print while `--json` knew better. The full mapping is in [how a release names its source](/guides/releases-and-rollback#how-a-release-names-its-source). ### `rollback` Re-deploy a prior release's exact bundle. No rebuild happens. ```bash npx deepspace rollback # the previous release npx deepspace rollback rel_01ABC... npx deepspace rollback rel_01ABC... --yes --json # agents/CI ``` | Arg / Flag | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------- | | `[release]` | Release id from `deepspace releases` (default: the previous release) | | `--app`, `-a` / `--env`, `-e` | Target app / environment | | `--yes` | Confirm rollback without a TTY; required with `--json` and in agents/CI | | `--allow-do-deletion` | Proceed even though the target release declares fewer Durable Object classes than the current one | `--allow-do-deletion` **deletes the stored data** of every Durable Object class the target release drops. Without the flag, `rollback` refuses that case. Spell out the exact loss and get the owner's explicit approval before passing it. Rollback itself also requires consent. At a TTY it asks and defaults to No; under `--json` or non-interactive stdin, pass `--yes` or handle the `confirmation_required` refusal. `--allow-do-deletion` does not imply `--yes`. A release whose bundle was evicted refuses with `no_bundle` - pick another release marked `rollbackAvailable` in `releases --json`. Every rollback appends a new release fact; see [Releases and rollback](/guides/releases-and-rollback). ## `deploy` Build and deploy the app. ```bash npx deepspace deploy npx deepspace deploy ./my-app npx deepspace deploy --env staging ``` | Arg / Flag | Description | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `[dir]` | App directory (default: current directory) | | `--env `, `-e` | `[env.]` block to deploy. Omit for the top-level config. | | `--rename` | Confirm that a changed wrangler `name` renames this app. Its URL moves; data, secrets, and collaborators travel - the [display name does not](/guides/app-identity#renaming-an-app). Without the flag an interactive prompt asks. | | `--claim-released` | Platform admins only: claim a name still inside its 30-day release cooldown. The previous owner permanently loses their reserved reclaim. Non-admin accounts are refused. | | `--push` / `--no-push` | Sync DeepSpace source before deploying (default on). GitHub source always deploys the local working tree without Git operations. | | `--ignore-stale` | Deploy even if someone released a newer version since you last synced (skips the stale-base guard) | | `--json` | Single-line JSON result; human output goes to stderr | The subdomain comes from the `name` field in `wrangler.toml`. Names are **globally unique** across all of DeepSpace - a name already claimed by another app is refused with `The name is taken by another app.` A repo without a `DEEPSPACE_APP_ID` gets one minted and written into `wrangler.toml` by its first deploy - commit it. Secrets ship from the app's [remote store](/guides/secrets); deploy never reads `.dev.vars` (it rewrites it). If the selected secrets config does not exist, deploy refuses with `secrets_config_missing` and returns the executable `secrets configs create` action - see [missing is not empty](/guides/secrets#missing-is-not-empty). The success envelope reports **what tree shipped** as `branch` and `dirty` (both `null` outside a usable Git repo), and, when the deploy renamed the app, `renamedFrom` plus `staleDisplayName`. See [what a release records](/guides/releases-and-rollback#what-a-release-records-depends-on-the-source) and [renaming an app](/guides/app-identity#renaming-an-app). Once the edge confirms the release (`serving: confirmed`), `deploy` sends the new worker **one request** - the template's own `GET /api/auth/ok` health route - so the app's Durable Objects exist before any visitor arrives; that is what arms a deployed [cron schedule](/guides/scheduled-jobs#when-a-schedule-starts-running). It is best effort: if the wake fails, the first real request arms it instead. **Who may deploy, and where from.** `forbidden` names both sides: the app id and the account you are signed in as (`app_… belongs to another account - you are signed in as you@example.com, who is neither its owner nor a collaborator`), and the two remedies - have the owner run `app collaborators add `, or `app init --new-id` to publish the code as your own app. An id no server has registered (an older SDK's locally minted scaffold) is `app_not_registered`, with `app init --new-id` as the remedy. **One deploy at a time, per checkout and per app.** Two deploys of one directory race on the shared `dist/`, so `deploy` takes a local lock at `.deepspace/deploy.lock` before any work and refuses a second run with `deploy_in_progress`, naming the other run's pid and start time (`lockPath` and `holder` in `--json`). A lock left by a dead process is reclaimed automatically; only remove it by hand when no deploy is running. Separately, when another deploy of the same app **from another checkout** is between prepared and live, the platform answers `release_in_progress`: this run built and uploaded fine but did not release, so it exits **2** with an executable retry action - wait a moment and run the same deploy again, and check `deepspace releases` if it keeps refusing for more than a couple of minutes. **`deploy` needs a committed worktree.** Under DeepSpace source with sync on, uncommitted changes are refused with `dirty_worktree`, because a deploy records the commit it ships. Commit them (WIP commits are fine), or pass `--no-push` to deploy without source lineage. A worktree mid-merge or mid-rebase is `merge_in_progress` instead (see [push](#push)). The full refusal taxonomy (`dirty_worktree`, `behind_trunk`, `stale_base`, and the concurrency codes above) is in [Releases and rollback](/guides/releases-and-rollback#the-refusal-taxonomy). ## `testflight` Upload a signed iOS build to App Store Connect and wait until TestFlight offers it. Requires `deepspace` 0.41 or later and macOS. ```bash npx deepspace testflight /tmp/app.ipa npx deepspace testflight /tmp/app.ipa --timeout-minutes 60 --json ``` | Arg / Flag | Description | | ----------------------- | ------------------------------------------------------------------------ | | `` | Path to the signed `.ipa`, for example from `eas build --local` | | `--timeout-minutes ` | How long to wait for App Store Connect processing (default 40) | | `--json` | Single-line JSON result with `appId`, `bundleId`, `version`, and `build` | The App Store Connect app is found from the IPA's own bundle id, so the command needs no per-app setup beyond an API key. It reads the key from `EXPO_ASC_API_KEY_PATH`, `EXPO_ASC_KEY_ID`, and `EXPO_ASC_ISSUER_ID` (the variables `eas build` uses), or from `submit.production.ios` (`ascApiKeyPath`, `ascApiKeyId`, `ascApiKeyIssuerId`) in `eas.json` in the app or its `mobile/` folder. The key file stays where it is. It succeeds once processing is `VALID` and the internal group's build is `IN_BETA_TESTING`. It refuses with `asc_no_internal_group` when no internal TestFlight group receives every build, `asc_build_invalid` when App Store Connect rejects the build, `asc_app_not_found` when no app has the bundle id, and `asc_timeout` when processing outlasts the wait. It sets no "What to Test" notes: TestFlight shows them in a screen that holds the app at its first launch on a Mac. ## `status` One screenful of current state: environment, session, app, workspace, and live release. The fastest orientation command in a fresh shell or sandbox. ```bash npx deepspace status npx deepspace status --json ``` | Flag | Description | | -------------------- | ----------------------------------------------------------- | | `--env `, `-e` | `[env.]` slot - reads that environment's app identity | **The environment line is always first, and never elided.** `status` opens with `Env` naming the plane the next command will mutate (`production` unless `DEEPSPACE_ENV` says otherwise), plus any of `DEEPSPACE_DEPLOY_URL` / `DEEPSPACE_AUTH_URL` / `DEEPSPACE_API_URL` / `DEEPSPACE_PLATFORM_URL` that are set: ``` Env production ``` A second `Services` line spelling out the four resolved service URLs is printed only when there is something to notice - a non-production plane, or at least one URL override: ``` Env staging · DEEPSPACE_DEPLOY_URL set Services auth https://... · api https://... · platform https://... · deploy https://... ``` `--json` carries both unconditionally: `env` is the plane string and `services` is the resolved `{ auth, api, platform, deploy }` object, whether or not the human `Services` line was printed. `urlOverrides` lists the override variable names when any are set. Check `env` before any mutating command rather than inferring the plane from the shell. ## `activity` The app's coordination feed: pushes, workspaces, releases. ```bash npx deepspace activity npx deepspace activity --follow npx deepspace activity --since now --limit 100 ``` | Flag | Description | | ------------------------ | ------------------------------------------------------------------------------------------- | | `--since ` | Events after this cursor, or `now`. One-shot defaults to `0`; `--follow` defaults to `now`. | | `--limit ` | Max events per page (default 50) | | `--follow` | Keep polling for new events | | `--app `, `-a` | Target app | One-shot `--json` returns a single document - `{ events, cursor, hasMore }`; page with `--since` while `hasMore` is true, and persist the last cursor for continuity. `--follow --json` is an **NDJSON stream**: one `ready` frame (`{"type":"ready","appId":...,"cursor":...}`), then one `activity` frame per event carrying the event and its cursor. Recoverable polling failures emit `transport` frames with `"state":"retrying"` and never advance the cursor. Events are facts, not instructions. ## `logs` Show production logs for a deployed app. ```bash npx deepspace logs npx deepspace logs --follow npx deepspace logs --since 2h --level error npx deepspace logs --search "checkout" --json ``` | Flag | Description | | ------------------------ | ------------------------------------------------------------------------- | | `--app `, `-a` | Target app (default: `DEEPSPACE_APP_ID` from the nearest `wrangler.toml`) | | `--env `, `-e` | `[env.]` slot - reads that env's own app id | | `--follow`, `-f` | Keep polling for new logs until Ctrl+C (\~3s cadence) | | `--since ` | `30s`, `15m`, `2h`, `24h`, `7d`, or an ISO timestamp (default `15m`) | | `--level ` | `debug`, `log`, `info`, `warn`, `error` | | `--search ` | Only events whose message contains this text | | `--limit ` | Max events per fetch (default 100, max 500) | | `--json` | Emit **NDJSON** - one event object per line | `--json` is NDJSON in both snapshot and follow modes. Log events never carry a `type` field; frames that do are metadata: an empty snapshot window emits `{"type":"meta","count":0,...}` so "ran, no events" is distinguishable from a crash, and a truncated snapshot emits `{"type":"meta","truncated":true}` - narrow with `--since`/`--level`, or raise `--limit`. An app that has never been deployed has no logs and never will until it is, so `logs` refuses `app_not_deployed` instead of printing an empty window - with the `deploy` action when you are in the app's own checkout. ### Reading an event Each event is `{ id, timestamp, level, eventType, message, source?, outcome?, request?, exception? }`. Three fields are easy to misread: * **`eventType`** is `log` for a `console.*` line, `request` for the invocation summary of one request, and `exception` **only for an exception that escaped the Worker** (uncaught). An error your code catches and logs - including what the template's `app.onError` does before answering 500 - is a `log` line at level `error`. * **`outcome`** rides `request` (invocation) events only and is the runtime's verdict on whether the Worker **returned** (`ok`, `exception`, `exceededCpu`, `canceled`, …) - not whether the app succeeded. An action that throws inside the app's own error handling and answers 500 is `outcome: "ok"`. Triage on `request.status`, `level`, and `eventType === "exception"`, never on `outcome !== "ok"` alone. * **`exception`** (`{ name, message, stack? }`) is present on `eventType: "exception"` and on browser-reported errors (`source: "client"`). The Workers runtime renders a **logged** Error object as its stack frames only - the message never reaches the store - so when you catch and log, put the message in the line itself: ``console.error(`[error] … ${err.message}`, err.stack)``. The scaffold's `app.onError` does exactly that, and so do the SDK's own rooms. Scheduled work logs one line per run - `[cron] ok ms` or `[cron] failed ms: ` (the stack rides along as plain text) - so `logs --search cron` finds every run by task name; a failed background job logs `[jobs] () failed: ` the same way. See [scheduled jobs](/guides/scheduled-jobs#when-a-schedule-starts-running). ## `add` Install a scaffold feature into the current app. ```bash npx deepspace add --list npx deepspace add --info messaging npx deepspace add messaging npx deepspace add messaging ./my-app --install ``` | Arg / Flag | Description | | --------------- | -------------------------------------------------- | | `[feature]` | Feature to install (positional) | | `[dir]` | App directory (positional, default `.`) | | `--list`, `-l` | List available features and exit | | `--info ` | Show details about a feature and exit | | `--install` | Run your package manager after adding dependencies | Run `--list` for the current feature set - it changes between releases. ## `integrations` Discover and call third-party integration endpoints, billed to the logged-in user. ```bash npx deepspace integrations list npx deepspace integrations info openai/chat-completion npx deepspace integrations invoke openai/chat-completion --body '{"messages":[]}' npx deepspace integrations invoke openai/chat-completion --body-file req.json cat req.json | npx deepspace integrations invoke openai/chat-completion --body-file - ``` | Subcommand | Args / Flags | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list` | `--json` | | `info` | `` (required) - `/` | | `invoke` | `` (required), `--body ` / `-d`, `--body-file ` / `-f` (`-` for stdin), `--timeout ` (default 120000), `--yes` / `-y` to skip the paid-call cost confirmation | **A paid call needs consent.** Without `--yes`, `invoke` looks the endpoint's price up first. At an interactive terminal (stdin **and** stdout are TTYs, no `--json`) it asks ` costs , billed to your account. Continue?` with the default **No** - declining is a success (`cancelled: true`), nothing was billed. Anywhere else - `--json`, a piped stdin such as `--body-file -`, CI - it refuses `cost_confirmation_required` **before** any call is made; pass `--yes` to confirm the spend. Free endpoints proceed without a prompt. `info` prints an example body you can copy: the catalog's own example when it has one, otherwise one **synthesized from the input schema's `required` keys** with placeholders from the schema (`example`, `default`, first `enum`) or the type (`""`, `0`, `false`), so the body an agent copies is never `{}` for an endpoint that rejects `{}`. `--json` carries the same body as `example`; it is `null` only when neither the catalog nor the schema says anything. ## `agent` Discover and invoke tools that a DeepSpace app exposes to a local agent. ```bash npx deepspace agent tools my-app --json npx deepspace agent invoke my-app records_query --input '{"collection":"posts"}' --json npx deepspace agent invoke my-app records_create --input-file tool-input.json --json cat tool-input.json | npx deepspace agent invoke my-app records_create --input-file - --json ``` | Subcommand | Args / Flags | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` | `` (required) - canonical app name or root canonical URL | | `invoke` | `` and `` (required), `--input ` or `--input-file ` (`-` for stdin), `--timeout ` (default 120000, maximum 600000) | Run `tools` before `invoke`. It returns the app's identity and each available tool's name, description, input JSON Schema, and optional output JSON Schema. `invoke` sends one JSON input and prints one JSON result. Pass the input through either `--input` or `--input-file`, not both; if neither is supplied, the input defaults to `{}`. Both commands use the current DeepSpace CLI session for the selected production or staging environment and refresh it automatically. Normal calls do not open a browser. If the session cannot be refreshed, the command refuses `not_authenticated` and directs the user to `auth login`. The CLI does not save a connection to the app; it resolves and authenticates each command separately. Pass an app name or its root canonical DeepSpace URL. Loopback URLs are accepted for local development. Custom domains and redirects are refused so the CLI does not send the user's login token to an unexpected host. The app decides whether the signed-in user may use its tools. `forbidden` means the user does not belong to the app or failed its additional authorization rule. `agent_endpoint_not_found` means the deployed app does not expose local agent tools. Local input failures use `conflicting_input_args`, `input_file_unreadable`, `invalid_input_json`, or `input_too_large`. The app uses `invalid_tool_input` when the input does not match the tool's schema and `tool_not_found` when the requested tool is unavailable; run `tools` again after `tool_not_found`. Network, timeout, and redirect failures use `agent_network_error`, `agent_timeout`, and `agent_redirect_refused`. See [Local agent tools](/guides/local-agent-tools) for the complete developer and user flow. ## `feedback` Submit a bug report or feature request to DeepSpace. ```bash npx deepspace feedback "Deploy hangs on large assets" npx deepspace feedback "Add dark mode" --type feature -m "Details here" --yes ``` | Arg / Flag | Description | | ------------------------ | ------------------------------------------------- | | `[title]` | Short summary (prompted if omitted in a terminal) | | `--type `, `-t` | `bug` (default), `feature`, or `other` | | `--message `, `-m` | Details / description | | `--yes` | Skip the confirmation prompt | ## `git-credential` Git credential helper. Installed automatically by the CLI so `git` can authenticate against the cloud repo. **Not for direct use.** ## Global flags | Flag | Available on | Purpose | | -------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--help`, `-h` | every command | Print help | | `--version` | top-level `deepspace` | Print CLI version | | `--json` | nearly every command | Single-line JSON envelope for scripts and agents (`logs` and `activity --follow` emit NDJSON; `dev start` / `test screenshot` envelopes follow the child stream on stdout; `test run` streams the suite on stderr and keeps stdout to the one envelope) | | `--yes` | `app undeploy`, `feedback`, `integrations invoke`, `test accounts clear` | Skip the confirmation prompt | ## Environment | Variable | Used by | Purpose | | ------------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DEEPSPACE_EMAIL` | `auth login` | Email for a password account (test or internally provisioned) | | `DEEPSPACE_PASSWORD` | `auth login` | Password for that account. Regular DeepSpace accounts have none | | `DEEPSPACE_PORT` | `dev`, `test` | Default port when `--port` is not passed | | `DEEPSPACE_ENV` | every command | Selects the platform plane (`production` when unset). Also selects which **stored credential** the CLI reads - each plane keeps its own `~/.deepspace/session` pair, see [login state](/cli-reference/overview#login-state) | | `DEEPSPACE_AUTH_URL` | `auth`, `test accounts` | Override auth-worker URL (advanced/testing). Like `DEEPSPACE_ENV`, selects its own stored credential | | `DEEPSPACE_API_URL` | `app`, `integrations`, `secrets` | Override api-worker URL (advanced/testing) | | `DEEPSPACE_DEPLOY_URL` | `deploy`, `push`, `pull`, `releases` | Override deploy-worker URL (advanced/testing) | | `DEEPSPACE_PLATFORM_URL` | `app files` | Override platform-worker URL (advanced/testing) | `DEEPSPACE_EMAIL` and `DEEPSPACE_PASSWORD` are consulted **only** when stdin is non-interactive or `--json` was passed, so ambient values in a dev shell cannot hijack an interactive `deepspace auth login`. ## See also * [CLI overview](/cli-reference/overview) - dev loop, and running agents and CI as yourself * [Collaborators](/guides/collaborators) - sharing deploy access * [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