CLI overview

The CLI ships inside the deepspace package, which is added to every scaffolded app. You run it via npx:

npx deepspace <command> [options]

No global install is needed. To create a new app, use npm create deepspace@latest - it fetches the latest scaffolder on demand.

The shape of the CLI#

The surface is noun-verb. Related commands live under a noun, and the noun on its own just prints its subcommands:

npx deepspace dev          # prints the subcommands - does NOT start a server
npx deepspace dev start    # starts the server

And at the top level: status, activity, logs, push, pull, clone, releases, rollback, deploy, add, feedback.

Full command reference →

Login state#

npx deepspace auth login opens a browser and signs you in with GitHub or Google. DeepSpace accounts are OAuth-only: there is no password to choose, and public email signup is closed.

You log in once per machine. The session is shared across every app and covers dev, test, deploy, and billed integration calls.

npx deepspace auth whoami        # human-readable
npx deepspace auth whoami --json # machine-readable

Login writes two files under ~/.deepspace/, both mode 0600:

• ~/.deepspace/session - the long-lived session token. This is the credential.
• ~/.deepspace/token - a cached short-lived JWT, re-minted from the session automatically by every other command.

Treat both as secret - never commit them.

When no usable session exists for the selected plane, every command refuses not_authenticated (exit 1) with a sentence that names the plane it selected and what selected it - Not logged in on staging (selected by DEEPSPACE_ENV=staging), or … on the auth service at <url> (selected by DEEPSPACE_AUTH_URL) - and, when another plane does hold a session, says so and how to select it (You are signed in on production - select that plane (unset DEEPSPACE_ENV), or log in here). The same sentence spells out the headless login form up front (auth login --email you@example.com --password-stdin, or DEEPSPACE_EMAIL / DEEPSPACE_PASSWORD), because the bare auth login action it ships refuses interactive_required without a TTY. Read the plane before running the action: a wrong plane is fixed by unsetting a variable, not by logging in again.

Agents and CI#

Agents do not get DeepSpace accounts. An agent runs as you, using your session.

On your own machine that is already true: any agent you launch inherits ~/.deepspace/session and every deepspace command it runs is attributed to you. Nothing extra to configure.

For an agent in a container, or a CI job, do the same thing deliberately - log in once where a browser exists, then supply that environment with the session file:

# once, on your machine
npx deepspace auth login

# then mount ~/.deepspace into the container
docker run -v ~/.deepspace:/root/.deepspace my-agent-image

In CI, store the contents of ~/.deepspace/session as an encrypted secret and write it to ~/.deepspace/session before the first deepspace command. Copying ~/.deepspace/token is unnecessary - it is only a cache, and the CLI re-mints it from the session.

The password flags#

deepspace auth login --help lists --email, --password, and --password-stdin, and the CLI reads $DEEPSPACE_EMAIL / $DEEPSPACE_PASSWORD when stdin is non-interactive or --json was passed. These exist for the two kinds of account that do have a password:

• @deepspace.test test accounts you create with deepspace test accounts create to drive multi-user auth flows in Playwright tests.
• Internally provisioned accounts, minted by SDK maintainers through an admin endpoint (the CI bot, for instance). Not available to the public.

Your own DeepSpace account is neither, so these flags cannot log you in - it has no password. Use the stored session above.

The interactive_required contract#

If you ask for --json, or stdout is not a TTY, and you supply no credentials, the CLI refuses immediately rather than opening a browser you cannot reach:

Browser login needs an interactive terminal. Use --email with
--password-stdin (or $DEEPSPACE_EMAIL/$DEEPSPACE_PASSWORD).

The refusal carries the machine-readable code interactive_required. Retrying will not help.

The remedy named in the message applies only to test and internally provisioned accounts. For a real DeepSpace account the fix is upstream of the failing call: log in once in a browser on a machine that has one, then give this environment the resulting ~/.deepspace/session, as above.

Agent-friendly defaults#

• --json nearly everywhere. Commands emit a single-line { ok, ... } envelope. logs --json and activity --follow --json emit NDJSON - one frame per line - so they pipe cleanly while following.
• Non-interactive by default. Missing required arguments produce a refusal with a machine-readable code and a Next: suggestion, rather than a stdin prompt.
• --yes skips confirmations on app undeploy, feedback, integrations invoke, and test accounts clear.
• Refusals carry codes. interactive_required, dirty_worktree, push_too_large, not_a_collaborator, and friends are stable identifiers - branch on the code, never on the prose. The table below lists them by command.

Exit codes#

Every command follows one exit contract. Human text is complete on its own; --json is the machine mirror of the same result, and refusals carry a stable code.

Branch on the exit code and the code field, never on the prose. Do not pre-check authentication before an operation - run the operation and let it refuse: an unauthenticated call fails with code: "not_authenticated" and exit 1, which is cheaper and more truthful than a separate probe.

The action contract#

When exactly one deterministic follow-up exists, the JSON result names it:

{"action":{"cwd":"/absolute/app","argv":["deepspace","pull"]}}

Human output renders the same thing as a Next: line. Two rules:

• Execute argv directly in cwd. Spawn it as an argv array; never join it into a shell string.
• Absence is not "done". Terminal results, status reports, consent decisions, destructive overrides, and input-dependent choices deliberately omit the field. An exit-2 result without an action means its facts need inspecting - never infer a command from the field's absence, and never invent one.

One-shot --json writes exactly one document. The exceptions are streams: logs --json is NDJSON in both snapshot and follow modes, activity --follow --json is NDJSON, and dev start / test screenshot inherit their child's output on stdout, so their final envelope follows the stream as the last line. Parse one frame per line; the command reference documents each stream's frame shapes.

test run --json is not one of those exceptions. It routes the spawned suite's output to stderr, so its stdout is exactly one JSON envelope - npx deepspace test run --json | jq works with no last-line handling, and the live suite transcript is still visible on stderr. (dev start --json writes two envelopes on stdout: a readiness line - {"ok":true,"ready":true,"url":...} - the moment the port answers, and the exit envelope last.)

Refusal codes by command#

The codes an agent branches on, grouped by where they come from. Codes are stable identifiers; the sentences beside them change. "Action" says whether the refusal ships an executable action - when it does not, the remedy is a decision, and the prose names the choices. Exit is 1 unless marked 2.

Every command (the shared preconditions, raised before any work):

Per command:

Local dev workflow#

npm create deepspace@latest my-app
cd my-app

npx deepspace auth login

npx deepspace dev start

npx deepspace test run

git commit -am "my changes"
npx deepspace deploy

Cleaning up leaked processes#

If a previous dev session crashed, leaked workerd / wrangler processes can hold ports:

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

Next steps#

• Command reference - every command, every flag.
• Quickstart - walk through the full dev loop.
• Collaborators - let teammates deploy your app.