CLI Reference

The package bin is devstack. Flags are command-scoped: put flags after the command that owns them.

Command index

`devstack up [options]`

Boot a stack and stay attached until interrupted.

Lifecycle: attached. Side effects: write. Docker: yes. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose, --config <path>, --network <name>, --renderer <tui|plain|silent>, --from-snapshot <name-or-id>, --snapshot-cache <name>, --snapshot-stale <warn|block|clean-start>.

`devstack apply [options]`

Re-emit the per-stack deployment file from a live or one-shot stack. The deployment file is deployment.json and carries the resolved ids, accounts, and dev-wallet connection. If a supervisor is live, apply reconciles through it; otherwise it boots once, emits, and exits. Refreshing the generated src/generated tree is devstack codegen's job, not apply's.

Lifecycle: live-aware. Side effects: write. Docker: yes. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose, --config <path>, --network <name>.

`devstack codegen [options]`

Regenerate committed bindings from Move source (no stack boot). The generated tree is src/generated. Deterministic and stack-free: no Docker, no on-chain ids. Requires the sui CLI on PATH for the sui move summary step. Writes the generated tree only.

Lifecycle: one-shot. Side effects: write. Docker: no. Requires: host sui CLI. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose, --config <path>, --network <name>.

`devstack dump-deployment [options]`

Emit the stack deployment for a real-network deploy. With --network <name>, write a typed deployments/<name>.ts (export const deployment = {…} satisfies AppNetworkDeployment) next to your app's src/ — the committed, tsc-checked authoring surface for going to production (see Going to production). Without --network, emit the raw deployment envelope JSON to --out or stdout (see Config & deployments).

Lifecycle: live-aware. Side effects: write (or stdout). Docker: yes (boots one-shot if no live supervisor). Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose, --config <path>, --network <name>, --out <path>.

`devstack status [options]`

Show the current stack projection (offline: from the manifest).

Lifecycle: offline. Side effects: read. Docker: no. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose.

`devstack doctor [options]`

Run host and stack preflight checks.

Lifecycle: offline. Side effects: read. Docker: yes. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose.

`devstack config [options]`

Print resolved config inputs.

Lifecycle: offline. Side effects: read. Docker: no. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose, --config <path>, --network <name>.

`devstack schema --json`

Emit the CLI schema.

Lifecycle: offline. Side effects: none. Docker: no. Options: --json.

`devstack snapshot <command> [options]`

Capture, restore, list, or delete stack snapshots.

Lifecycle: offline. Side effects: write. Docker: yes. Options: none.

`devstack snapshot save [name] [options]`

Capture a snapshot through a one-shot stack boot.

Lifecycle: one-shot. Side effects: write. Docker: yes. Arguments: name. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose, --config <path>, --network <name>, --name <name>.

`devstack snapshot restore <name-or-id> [options]`

Restore a snapshot by name or id.

Lifecycle: offline. Side effects: destructive. Docker: yes. Arguments: name-or-id. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose, --yes, --no-input.

`devstack snapshot list [options]`

List snapshots for the selected stack.

Lifecycle: offline. Side effects: read. Docker: no. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose.

`devstack snapshot delete <name-or-id> [options]`

Delete a snapshot by name or id.

Lifecycle: offline. Side effects: destructive. Docker: no. Arguments: name-or-id. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose, --yes, --no-input.

`devstack prune [--list | --dry-run | --all --yes] [options]`

Inventory and prune devstack-labelled Docker resources.

Lifecycle: offline. Side effects: destructive. Docker: yes. Options: --json, --state-dir <path>, --verbose, --list, --all, --no-containers, --no-networks, --no-volumes, --include-images, --dry-run, --yes, --no-input.

`devstack wipe [--dry-run] [--yes] [options]`

Destroy all state for the selected stack.

Lifecycle: offline. Side effects: destructive. Docker: yes. Options: --json, --app <name>, --stack <name>, --state-dir <path>, --verbose, --dry-run, --yes, --no-input.

Lifecycle commands

devstack up --renderer tui
devstack up --from-snapshot before-migration
devstack up --from-snapshot before-migration --snapshot-stale block
devstack up --snapshot-cache dev-baseline
devstack apply

up boots the stack and stays attached until you quit the TUI or interrupt the process. apply checks the selected stack first: if devstack up is live, it asks that supervisor to reconcile and waits for completion; otherwise it boots the stack in one-shot mode, reconciles, re-emits the per-stack deployment file, and exits. Neither touches the generated src/generated tree — that's devstack codegen's job.

Both commands accept --config <path>, --network <name>, --app <name>, --stack <name>, --state-dir <path>, --json, and --verbose. Only up accepts --renderer tui|plain|silent, --from-snapshot <name-or-id>, --snapshot-cache <name>, and --snapshot-stale warn|block|clean-start. The default snapshot stale policy is warn.

Accepted network names are exactly localnet, testnet, mainnet, devnet, testnet-fork, mainnet-fork, and devnet-fork — one canonical spelling each, with no sui: prefix or alias form; any other value is rejected with exit code 64. Plain sui() still means localnet; fork and live names select the surface network for mode-narrowed configs, generated identity, and configs that explicitly branch on the resolved network.

Inspection commands

devstack status --json
devstack doctor
devstack config
devstack schema --json

status reads the persisted projection without requiring a running stack. doctor runs host preflight checks. config prints resolved config inputs. schema --json prints the command tree and exit-code table consumed by automation.

Snapshot commands

devstack snapshot save before-migration
devstack snapshot list
devstack snapshot restore <name-or-id>
devstack snapshot delete <name-or-id>

snapshot save performs a one-shot stack boot and can accept --config <path>. A name can be provided positionally or with --name; if omitted, devstack generates a manual-... name. Restore and delete resolve an exact snapshot id first, then a unique name.

If you are already attached to devstack up --renderer tui, press s in the TUI to snapshot the attached session rather than starting a second snapshot command. The shortcut is available only in the TUI renderer, not in plain or silent mode. snapshot restore, snapshot delete, and wipe prompt for y in a TTY, or require --yes when prompts are unavailable. snapshot restore and wipe do not mutate state while an attached devstack up session is live. snapshot list and snapshot delete operate on the selected stack root.

Use devstack up --from-snapshot <name-or-id> when you want startup to restore a snapshot and then converge the stack. --snapshot-stale warn logs graph-input drift and proceeds, block refuses the restore, and clean-start skips the restore and boots normally when the snapshot's graph input id differs from the current stack.

Use devstack up --snapshot-cache <name> to restore that named snapshot only when its graph input id matches the current stack. If it is missing or stale, devstack boots normally and refreshes the named snapshot after startup.

Cleanup commands

devstack prune --dry-run
devstack prune --yes
devstack wipe --dry-run
devstack wipe --yes

prune runs cross-stack orphan cleanup without requiring a running stack. wipe removes all state for the selected stack after confirmation.

State directory resolution

Every verb resolves a single state directory before doing any work. The ladder, highest precedence first:

--state-dir <path> — the command-scoped flag.
config.options.stateDir — i.e. defineDevstack({ stateDir }) in devstack.config.ts.
$DEVSTACK_STATE_DIR — the environment variable.
<cwd>/.devstack — the default when nothing above is set.

The cleanup verbs (prune, wipe) resolve a state directory by this ladder without loading a config: pass --state-dir, set $DEVSTACK_STATE_DIR, or run from a directory whose .devstack you want to act on.

Exit codes

Every CLI failure carries one of the codes below in process.exitCode, and under --json it also appears in the structured error envelope as error.exitCode (numeric) and error.code (the name). The devstack-domain block (40–43) sits below the standard sysexits range so it does not overlap the OS table; these numbers are stable across releases. devstack schema --json emits this table for automation.

Code	Name	Meaning
`0`	`OK`	Successful termination.
`1`	`GENERIC`	Generic failure; no specific code applies.
`40`	`SUPERVISOR_LIVE`	Supervisor for the target stack is already live in another process.
`41`	`SNAPSHOT_NOT_FOUND`	Requested snapshot name or id not found.
`42`	`SEED_MISMATCH`	Seed-manifest mismatch (chain identity diverges from snapshot).
`43`	`CONFIRM_REQUIRED`	Destructive verb needs confirmation or the prompt was declined.
`64`	`USAGE`	Bad command-line usage.
`65`	`DATA_ERR`	Input data malformed.
`66`	`NO_INPUT`	Required input could not be opened.
`69`	`UNAVAILABLE`	A required service (e.g. Docker daemon) is unavailable.
`70`	`SOFTWARE`	Internal software error.
`73`	`CANT_CREATE`	Cannot create output (permissions, disk).
`75`	`TEMP_FAIL`	Transient failure; retry may succeed.
`78`	`CONFIG`	User configuration error.

Argv and usage parse failures — unknown flags, malformed args, mutually-exclusive flag pairs, or ambiguous references — exit 64. Under --json, a parse failure emits the structured error envelope with error.exitCode of 64 and error.code of USAGE.

On this page