---
title: 'Command conventions'
description: 'The rules every stackbone command obeys: how a verb picks its target, the JSON envelope, pagination, the --yes gate, secrets and exit codes.'
position: 2
---

# Command conventions

> Every command page in this section assumes the rules below. They are written
> once here so no 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](/docs/cli/reference/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](/docs/sdk/agents/overview) plus the durable
[workflows](/docs/sdk/workflows/overview) 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`](/docs/cli/reference/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`](/docs/cli/reference/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`) instead of guessing.

### 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 at all, so none of them takes
`--agent`. Three verb groups sit inside the installation surface and still take
no `--agent`:

| Verbs                                                                     | Why                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`stackbone agents`](/docs/cli/reference/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`](/docs/cli/reference/db) | 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`](/docs/cli/reference/config)                    | 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](/docs/cli/reference/configuration#output-contract).

## 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:

- [`stackbone runs list`](/docs/cli/reference/runs#stackbone-runs-list)
- [`stackbone hitl list`](/docs/cli/reference/hitl#stackbone-hitl-list)
- [`stackbone storage list`](/docs/cli/reference/storage)
- [`stackbone rag list`](/docs/cli/reference/rag)
- [`stackbone rag jobs`](/docs/cli/reference/rag)
- [`stackbone db table`](/docs/cli/reference/db#stackbone-db-table)

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`](/docs/cli/reference/agents)             | Every installation in your organization.            |
| [`stackbone workflows list`](/docs/cli/reference/workflows)       | Every workflow the installation exposes.            |
| [`stackbone db schemas`](/docs/cli/reference/db)                  | Every schema and table visible to the installation. |
| [`stackbone storage buckets`](/docs/cli/reference/storage)        | Every bucket the installation exposes.              |
| [`stackbone rag collections list`](/docs/cli/reference/rag)       | Every collection, with document and chunk counts.   |
| [`stackbone secrets list`](/docs/cli/reference/secrets)           | Every secret name, values always masked.            |
| [`stackbone config versions`](/docs/cli/reference/config)         | The most recent versions, newest first, up to 100.  |
| [`stackbone prompts list`](/docs/cli/reference/prompts)           | Every prompt at its current version.                |
| [`stackbone prompts versions <key>`](/docs/cli/reference/prompts) | One prompt's history, newest first, up to 200.      |

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

## Destructive verbs

Any verb that mutates or deletes (`retry`, `cancel`, `remove`, `rollback`,
`approve`, `reject`) refuses to run without `--yes` and exits `5` (permission
denied) until you pass it. See
[Configuration → global flags](/docs/cli/reference/configuration#global-flags).

[`stackbone workflows start`](/docs/cli/reference/workflows) is not gated by
`--yes`: it begins a run rather than destroying anything.

## Secrets are never printed

[`stackbone secrets`](/docs/cli/reference/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](/docs/cli/reference/configuration#exit-codes).