Command conventions

Every command page in this section assumes the rules below. This page states them once, so no command page repeats them. Each command page names only the two or three that matter to it, and links back.

All commands accept the global flags documented in Configuration → Global flags.

Target resolution

Most verbs act on a running agent installation rather than on the agent template. An installation is a workspace: one or more durable deep agents plus the durable workflows you ship alongside them. Those verbs inspect and operate that running workspace: its agents, its workflows, the durable runs they produce, and the agent-local stores (database, storage, RAG, secrets, config, prompts) each agent reaches through the ambient stackbone client.

A verb with no --agent runs against the local-dev installation linked to the current project, talking to it directly, so stackbone dev must be running. If it is not, the verb fails with the dev_not_running error (exit code 3) telling you to start it. Pass --agent <installationId> to target a cloud installation instead, which does not need stackbone dev. With no project and no --agent, the verb cannot guess a target and fails with exit code 3 (no project).

A deployed box must have a registered deployment (see stackbone link). Without one the CLI does not know the box's URL, so the verb refuses with the runtime_not_configured error (exit code 4).

Verbs that take no `--agent`

The account and project commands (login, logout, whoami, current, list, organization use, metadata, init, add, link, dev, build, package, docs) do not target an installation, so none of them takes --agent. Three verb groups sit inside the installation surface and still take no --agent:

Verbs	Why
`stackbone agents`	It reaches the control plane directly and lists the installations your organization owns. It is how you discover the installation ids the other commands need.
`stackbone db migrate up` / `create` / `status`	They run the migration engine against your local dev database, not against an installation. They read `STACKBONE_POSTGRES_URL` when it is set, and otherwise discover the connection from a running `stackbone dev`.
`stackbone config types`	It runs on your machine: it reads `config.schema.ts` and rewrites `.stackbone/config.d.ts`. It reaches no control plane and needs no running `stackbone dev`. `--cwd <dir>` points it at a project other than the current one.

JSON output

Every verb accepts --json (or STACKBONE_JSON=1) and then emits a single { "schema_version": 1, ... } line on stdout. Each command page shows the inner fields of its own payload. See Configuration → output contract.

stackbone logs tail is the one exception. It streams, so it prints one envelope per log line instead of one for the command.

Pagination

A paginated verb takes --limit <n> and --cursor <opaque>, and its JSON payload carries items plus nextCursor / prevCursor (either may be null). Pass the previous page's nextCursor back as --cursor to walk forward. Some lists add domain-specific fields alongside items.

Six verbs paginate:

Not every list-style verb paginates. These return the whole set in one call and take neither flag:

Verb	What it returns
`stackbone agents list`	Every installation in your organization.
`stackbone workflows list`	Every workflow the installation exposes.
`stackbone db schemas`	Every schema and table visible to the installation.
`stackbone storage buckets`	Every bucket the installation exposes.
`stackbone rag collections list`	Every collection, with document and chunk counts.
`stackbone secrets list`	Every secret name, values always masked.
`stackbone config versions`	The most recent versions, newest first, up to 100.
`stackbone prompts list`	Every prompt at its current version.
`stackbone prompts versions <key>`	One prompt's history, newest first, up to 200.

stackbone logs tail streams instead of paginating. It takes --limit (default 100) but no --cursor, and the CLI applies the limit locally as lines arrive.

Destructive verbs

Nine verb names refuse to run without --yes and exit 5 (permission denied) until you pass it: remove, remove-version, retry, cancel, rollback, approve, reject, publish and unpublish. Each one deletes something, replays something, or settles a decision you cannot take back. The gate runs before the request, so a refused verb changes nothing. See Configuration → global flags.

Writing a new value is not gated. secrets set, config set, storage put, rag ingest, prompts create, prompts update and stackbone workflows start all run without --yes, because each adds something rather than taking something away.

Secrets are never printed

stackbone secrets never prints a plaintext secret or key. list masks every value and there is no reveal verb. Reading a raw value is a human-only action in Studio, behind a re-auth challenge.

Exit codes

Every command exits with a code from one shared table: 0 ok, 1 generic, 2 auth, 3 no project, 4 not found, 5 permission denied. The error.code in the JSON envelope is finer: several names share one exit code (dev_not_running exits 3, runtime_not_configured exits 4), so a script can branch on the integer or on the name. Each command page lists the codes that command can produce and what triggers them. Both tables: Configuration → exit codes.