Docs
Sign in

CLI

CLI reference

Every spawn command, flag, setting and environment variable. spawn help prints the same command list in your terminal.

Global flags

Global flags go before the command: spawn --json ls.

--json flag
Print API responses as JSON. Errors become {"status":"error","message":…} on stderr.
--api-url URL string
The API to talk to, for this run.
--timeout SECONDS integer
Per-request HTTP timeout, 1 to 86400. Defaults to 180. Long operations (create, pause, upload, pull) keep their own longer limits.

Interactive sessions

ID is a session ID (a sandbox ID works too). Leave it out to use this folder’s latest session; spawn ls lists them.

spawn command
Open the terminal dashboard: this folder’s session and all your sessions, live.
claude [PATH] command
Resume this folder’s session, or upload the folder to a new sandbox and run Claude there. Flags: --size SIZE, --name NAME, --idle-timeout DURATION (15m, 1h, 90s or seconds; new sessions only), --no-git (upload without .git), --new (always a new session), --yes / -y (no questions), -- CLAUDE_ARGS (passed to claude).
attach [ID] command
Reopen Claude in a session’s sandbox. Continues the last conversation if Claude had exited.
shell [ID] command
Open a shell in the sandbox. Exiting doesn’t pause it.
pull [ID] command
Apply the session’s changes to this folder, uncommitted. --dry-run checks and lists without writing; --force merges into files you changed locally.
pr [ID] command
Open the session page to create a pull request, or print the existing one.
open [ID] command
Open the session page. --code opens the browser editor; --preview PORT opens a port’s preview.
ls command
List your sessions; * marks the ones started from this folder.
stop [ID] command
Pause a session’s sandbox now.
rm [ID] command
End a session and delete its sandbox, after asking. --yes / -y skips the question (needed without a terminal).

Background sessions

fix ISSUE command
Have Claude fix a GitHub issue and open a pull request. ISSUE is a URL or owner/repo#number. --prompt TEXT adds instructions; --project ID names the spawn project (remembered per repository).
review PR command
Have Claude review a GitHub pull request. Same forms and flags as fix.
status [ID] command
A session’s status, summary, links and Claude’s latest message.
logs [ID] command
Show progress. -f / --follow keeps going until the session finishes, then prints the PR or review link.

Account and settings

login command
Sign in with the browser and store the API key in your OS keychain. --no-browser prints the link instead of opening it.
logout command
Remove the stored key. Revoke it on the API keys page to invalidate it.
whoami command
The signed-in account, the key (masked), where it came from, and the API URL.
config command
Every effective setting and where its value came from, plus which settings files were loaded.
trust command
Trust this folder for upload without starting a session. --forget makes spawn claude ask again.
version command
Print the version.

Sandboxes (low level)

Plain sandboxes, without Claude or a session: the same operations as the HTTP API.

Terminal 
id=$(spawn sandbox create --name scratch --size nano)
spawn sandbox exec "$id" -- uname -a
spawn sandbox exec "$id" -- sh -lc 'ls -la | head'
spawn sandbox destroy "$id"
sandbox create command
Prints the new sandbox ID. --name, --template IMAGE (default alpine), --size, --idle-timeout SECONDS, --max-lifetime SECONDS, --internet=false.
sandbox list | inspect ID command
Your sandboxes, or one sandbox, as JSON.
sandbox pause | resume | destroy ID command
Change a sandbox’s state. Destroy is immediate.
sandbox exec ID -- COMMAND command
Run a command and exit with its exit code. Each argument is quoted separately, so use sh -lc for pipes and expansion. --exec-timeout SECONDS limits the run.

Settings

JSON files, applied in this order (later ones win):

  1. ~/.spawn/settings.json: yours, for every project.
  2. .spawn/settings.json in the project: shared, safe to commit.
  3. .spawn/settings.local.json in the project: yours, never uploaded.
  4. Environment variables, then command-line flags.
.spawn/settings.json 
{
  "size": "4cpu-16gb",
  "idleTimeout": 1800,
  "upload": { "exclude": ["*.mp4", "fixtures/large"] },
  "env": { "NODE_ENV": "development" }
}
size string
Size of new sessions: 2cpu-4gb, 2cpu-8gb (default), 4cpu-16gb, 8cpu-32gb.
idleTimeout integer
Seconds a new session’s sandbox may sit idle before it pauses: 60 to 86400. Defaults to 900.
pauseOnExit boolean
Pause the sandbox when Claude exits. Defaults to true.
detachKey string
The detach key: ctrl+\ (default), ctrl+], ctrl+^, ctrl+_, or ctrl+ a letter other than h, i, j and m. none turns detaching off.
predictiveEcho string
adaptive (default: only when the connection is slow), always or off.
upload.exclude string[]
More paths to leave out. A pattern without / matches anywhere (*.mp4); one with / matches from the project root.
upload.include string[]
Upload files that are left out by default, such as a specific .env file.
upload.maxBytes integer
Largest compressed upload, in bytes. Defaults to 500 MiB.
env object
Environment variables for the sandbox terminal. Not for secrets; ANTHROPIC_* and CLAUDE_CODE_* are ignored.
secret string
Which Secrets-page entry gives Claude its model. Defaults to anthropic.
notifications boolean
The dashboard notifies you when a background session changes state. On by default on macOS.
apiUrl / dashboardUrl string
The API and the dashboard to talk to. HTTPS only, except localhost.

The upload lists add up across files, and env merges key by key. Settings files never hold credentials: a key that looks like one is ignored with a warning.

Environment variables

SPAWN_API_KEY string
An API key; takes precedence over the stored one. For CI and scripts. (RENDEROPS_API_KEY also works.)
SPAWN_API_URL string
Overrides apiUrl. (RENDEROPS_API_URL also works.)
SPAWN_DASHBOARD_URL string
Overrides dashboardUrl.
SPAWN_PREDICT string
Overrides predictiveEcho: adaptive, always or off.
NO_COLOR any
Turns colour off.

Files on your machine

spawn keeps its state in ~/.spawn/, readable only by you: your settings, the sessions and trust for each folder (folders.json), recent background sessions (background.json), and the API key when no keychain is available (credentials). It writes nothing into your projects.

Exit codes

0 code
Success, including detaching from a session.
1 code
Any failure.
130 code
Interrupted (Ctrl+C).
claude command
Exits with Claude’s own exit status.
sandbox exec command
Exits with the remote command’s exit code.
Ctrl I