> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Sandbox CLI reference > Command syntax and operating rules for sandboxes, executions, terminals, operations, snapshots, volumes, services, and secrets. All sandbox commands are under `stackshift sandbox`. They use the same public `/api/v1` contract as the dashboard and SDKs. ## Authentication and global options ```bash theme={null} stackshift auth login stackshift auth status stackshift sandbox --help ``` The CLI resolves the active profile, then `STACKSHIFT_TOKEN` or its configured token. For CI, prefer a mode-0600 token file or stdin over a command argument. | Option | Default | Purpose | | ---------------- | -------------: | ----------------------------------------------- | | `--profile` | active profile | Select stored API/auth configuration | | `--api-url` | profile URL | Override the StackShift API host | | `--output`, `-o` | `table` | `table`, `json`, `yaml`, or `name` | | `--token-file` | none | Read a token from a mode-0600 file | | `--token-stdin` | false | Read a CI token from stdin | | `--timeout` | `30s` | Bound HTTP requests and `--wait` | | `--yes`, `-y` | false | Confirm destructive actions | | `--quiet`, `-q` | false | Suppress progress output | | `--color` | `auto` | `auto`, `always`, or `never` | | `--debug` | false | Show request diagnostics; review before sharing | `--project`, `--app`, and `--environment` are global StackShift selectors but are not substitutes for explicit sandbox IDs. ## Sandbox lifecycle | Command | Important options | Result | | ----------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------- | | `sandbox list` | `--state`, `--sandbox-profile`, `--cursor`, `--limit` | Cursor page or table of sandboxes | | `sandbox get SANDBOX` | output options | Sandbox and normalized effective policy | | `sandbox create` | required `--name`, `--template`; profile defaults to `coding_agent`; optional `--tags`, `--wait` | Durable create operation | | `sandbox start SANDBOX` | `--wait` | Start operation | | `sandbox sleep SANDBOX` | `--wait` | Sleep operation | | `sandbox resume SANDBOX` | `--wait` | Resume operation | | `sandbox recover SANDBOX` | `--wait` | Recovery operation when recovery is available | | `sandbox destroy SANDBOX` | global `--yes`; optional `--wait` | Permanent destroy operation | | `sandbox events SANDBOX` | `--after-sequence` | Resumable JSON event stream | | `sandbox operation OPERATION` | `--wait` | Current or terminal operation | `create --template` requires a digest-qualified OCI reference. The CLI sends a generated idempotency key for each mutation. If a CLI process is interrupted after submission, use the printed operation ID instead of issuing a second create. ```bash theme={null} stackshift --output json sandbox operation stackshift --timeout 15m sandbox operation --wait ``` ## Execute and connect ```bash theme={null} stackshift sandbox exec SANDBOX [flags] -- COMMAND [ARG...] ``` | Flag | Default | Meaning | | ------------------- | -----------: | ---------------------------------------------------- | | `--cwd` | `/workspace` | Working directory inside an allowed mount | | `--user` | `sandbox` | Template-allowed OS user | | `--command-timeout` | `600` | Remote timeout in seconds | | `--shell` | false | Interpret the joined command with the template shell | | `--background` | false | Return the execution resource instead of streaming | The separator `--` prevents remote arguments from being parsed as StackShift flags. Without `--shell`, argv is executed literally. With `--shell`, quoting and expansion are the caller's responsibility. ```bash theme={null} stackshift sandbox exec -- python -m pytest -q stackshift sandbox exec --shell -- 'npm test && npm run build' ``` Interactive terminal syntax: ```bash theme={null} stackshift sandbox terminal SANDBOX \ [--cwd /workspace] [--user sandbox] [--rows 24] [--columns 80] ``` The terminal command obtains a writer lease and scoped ticket. It does not expose or persist those credentials. ## Snapshots | Command | Required/important options | | -------------------------------------------- | ------------------------------------------------------------------------------------- | | `sandbox snapshots list [SANDBOX]` | global list supports `--cursor`, `--limit` | | `sandbox snapshots get SNAPSHOT` | none | | `sandbox snapshots create SANDBOX` | `--name`; `--type filesystem\|group`; `--retention-seconds` default `86400`; `--wait` | | `sandbox snapshots restore SNAPSHOT SANDBOX` | target must sleep; `--safety-snapshot` defaults true; `--wait` | | `sandbox snapshots fork SNAPSHOT` | `--name`, `--template`; profile defaults to `development`; `--wait` | | `sandbox snapshots delete SNAPSHOT` | global `--yes`; optional `--wait` | ```bash theme={null} stackshift --timeout 15m sandbox snapshots create \ --name release-candidate \ --type filesystem \ --retention-seconds 604800 \ --wait ``` Do not restore from `pending`, `creating`, `failed`, `deleting`, or `deleted`. Inspect integrity, compatibility, encryption, lineage, and `volatile_secrets_excluded` on the snapshot. ## Volumes | Command | Required/important options | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `sandbox volumes list [SANDBOX]` | global list supports `--cursor`, `--limit` | | `sandbox volumes get VOLUME` | none | | `sandbox volumes create SANDBOX` | `--name`, `--kind persistent\|sidecar`, absolute `--mount-path`, positive `--capacity-bytes`; optional `--read-only`, `--wait` | | `sandbox volumes grow VOLUME` | larger `--capacity-bytes`; optional `--wait` | | `sandbox volumes attach VOLUME SANDBOX` | absolute `--mount-path`; optional `--read-only`, `--wait` | | `sandbox volumes detach SANDBOX VOLUME` | sandbox must sleep; optional `--wait` | | `sandbox volumes delete VOLUME` | volume must detach; global `--yes`; optional `--wait` | ```bash theme={null} stackshift --timeout 10m sandbox volumes create \ --name workspace-data \ --kind persistent \ --mount-path /workspace/data \ --capacity-bytes 21474836480 \ --wait ``` Capacity is a hard byte limit. Grow requests must increase it; shrinking is unsupported. ## Temporary services | Command | Required/important options | | ----------------------------------------- | ------------------------------------------------------------------------------------ | | `sandbox services list SANDBOX` | none | | `sandbox services get SANDBOX SERVICE` | none | | `sandbox services create SANDBOX` | `--name`; `--engine postgres\|mysql\|redis`; `--capacity-gib` default `10`; `--wait` | | `sandbox services start SANDBOX SERVICE` | `--wait` | | `sandbox services sleep SANDBOX SERVICE` | `--wait` | | `sandbox services delete SANDBOX SERVICE` | global `--yes`; optional `--wait` | Service deletion also deletes its encrypted sidecar data volume. List/get output contains safe connection metadata, never the generated credential URL. ## Secrets and bindings | Command | Required/important options | | ---------------------------------------- | -------------------------------------------------------------------------------- | | `sandbox secrets list` | safe metadata only | | `sandbox secrets get SECRET` | safe metadata only | | `sandbox secrets create` | plaintext stdin; `--name`; optional `--type`, `--description`, `--allowed-hosts` | | `sandbox secrets rotate SECRET` | new plaintext stdin | | `sandbox secrets revoke SECRET` | global `--yes` | | `sandbox secrets bindings SANDBOX` | safe binding metadata | | `sandbox secrets bind SANDBOX SECRET` | `--scope`, `--target`, `--delivery proxy\|file\|env`, optional `--allowed-hosts` | | `sandbox secrets unbind SANDBOX BINDING` | global `--yes` | ```bash theme={null} printf '%s' "$API_TOKEN" | stackshift sandbox secrets create \ --name upstream-api \ --type token \ --allowed-hosts api.example.com ``` Avoid `echo` because implementations can add a newline or interpret escapes. The CLI never prints submitted plaintext. ## Automation rules * Use `--output json` and parse fields, not human tables. * Retain operation IDs before waiting. * Set `--timeout` to the expected operation duration. * Page while `has_more` is true using `next_cursor`. * Resume events from the last committed sequence. * Treat timeouts and transport failures as unknown outcomes. * Never automate `--yes` without a prior inventory and exact resource IDs. Use the same contract programmatically. Interpret errors and recover safely.