---
title: 'Commands reference'
description: 'Every CLI command Stackbone ships today, with flags, exit codes and JSON output.'
position: 1
---

# Commands reference

> Every command shipped today gets its own page: the synopsis, flags, the
> human-mode output, the `--json` shape and the possible exit codes. This page
> is the index. Find your command in [Every command](#every-command) and follow
> it to its page.
>
> The rules every command obeys (how a verb picks its target, the JSON
> envelope, pagination, the `--yes` gate, exit codes) are stated once at
> [Command conventions](/docs/cli/reference/conventions). Global flags,
> environment variables and on-disk state live at
> [Configuration](/docs/cli/reference/configuration), and the manifest fields at
> [agent.yaml](/docs/cli/reference/agent-yaml).
>
> When this page and the binary disagree, the binary wins: run the command with
> `--help` to see what your installed version accepts.

## What a Stackbone project is

A project is a **workspace**: one or more agents and a set of durable
[workflows](https://workflow-sdk.dev/docs), discovered
**by convention** from the files on disk. You maintain no registry: the CLI
reads the workspace straight from two folders:

- **Agents**: every folder under `deep-agents/` that contains an `index.ts`
  entry file. The folder name is both the agent's identity and the `model`
  a client selects to talk to it.
- **Workflows**: every `workflows/<name>.workflow.ts`. The workflow name is the
  file basename without the `.workflow.ts` suffix, and the file exports a
  `<camelCase(name)>Workflow` function (e.g. `qualify-lead.workflow.ts` exports
  `qualifyLeadWorkflow`).

`stackbone dev` reads this convention. An optional `stackbone.config.ts`
(default-exporting `defineWorkspace({ agents: [], workflows })` from
`@stackbone/sdk`) is an **override**: when it exists, its `workflows` win over
the convention scan, and an explicit `deepAgents` list wins over the
`deep-agents/` scan. Most projects need no `stackbone.config.ts` at all. See
[Configuration → State on disk](/docs/cli/reference/configuration#state-on-disk)
for the full shape of that file.

If you are new to these concepts, read
[Agents](/docs/sdk/agents/overview),
[Workflows](/docs/sdk/workflows/overview) and
[Stackbone Connect](/docs/home/features/integrations) first.

## Going to production

There is no publish command. You run the agent in **your own cloud**, by one of
two routes:

- [`stackbone package`](/docs/cli/reference/package) writes a **deploy folder**: your
  compiled workspace plus a Dockerfile, a compose file, an `.env` and a README.
  Hand that folder to whoever runs your infrastructure and they bring it up with
  `docker compose up -d`. Start here.
- [`stackbone build`](/docs/cli/reference/build) writes only the **workspace bundle**.
  Take this route when you already own the image and the deployment, and you
  want to copy the bundle into a Dockerfile of your own.

Either way, register the running agent with
[`stackbone link`](/docs/cli/reference/link) so Stackbone knows its URL, its HMAC secret
and the image tag it is running. The tag is the agent's version, so shipping a
new version means deploying a new image and re-running `link`.

## Every command

One row per command. The page is the whole reference for that command.

### Your account

| Command                      | What it does                                                                                    | Page                                         |
| ---------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `stackbone login`            | Authenticate the CLI via the device-code flow and store the session on disk.                    | [login](/docs/cli/reference/login)           |
| `stackbone logout`           | Revoke the active session and drop it from disk.                                                | [login](/docs/cli/reference/login)           |
| `stackbone whoami`           | Show the active user and organization.                                                          | [inspection](/docs/cli/reference/inspection) |
| `stackbone current`          | Print the slug of the organization currently linked to this session.                            | [inspection](/docs/cli/reference/inspection) |
| `stackbone list`             | List the organizations you belong to.                                                           | [inspection](/docs/cli/reference/inspection) |
| `stackbone organization use` | Choose which organization the CLI acts as.                                                      | [inspection](/docs/cli/reference/inspection) |
| `stackbone metadata`         | One payload with user, organization, agents and runtime state, for a coding agent to plan from. | [inspection](/docs/cli/reference/inspection) |

### Your project

| Command          | What it does                                                                                              | Page                             |
| ---------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `stackbone init` | Scaffold a new workspace and link it to your organization.                                                | [init](/docs/cli/reference/init) |
| `stackbone add`  | Add one agent, workflow or workflow-agent to an existing workspace. Offline, writes only new files.       | [add](/docs/cli/reference/add)   |
| `stackbone link` | Link the current directory to an organization + agent, and register the deployment you run that agent on. | [link](/docs/cli/reference/link) |

### Local development

| Command          | What it does                                                                                       | Page                             |
| ---------------- | -------------------------------------------------------------------------------------------------- | -------------------------------- |
| `stackbone dev`  | Boot the full local runtime for the project and open a tunnel so cloud-hosted Studio can reach it. | [dev](/docs/cli/reference/dev)   |
| `stackbone docs` | Print the connection details for the documentation MCP server.                                     | [docs](/docs/cli/reference/docs) |

### Shipping

| Command             | What it does                                                                                                              | Page                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `stackbone build`   | Compile the project into the workspace bundle your container image serves the agent from.                                 | [build](/docs/cli/reference/build)     |
| `stackbone package` | Write a deploy folder someone else can run: the compiled workspace, a Dockerfile, a compose file, an `.env` and a README. | [package](/docs/cli/reference/package) |

### The running installation

| Command               | What it does                                                                                               | Page                                       |
| --------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `stackbone agents`    | Discover the agent installations in your organization. This is where the `--agent` ids come from.          | [agents](/docs/cli/reference/agents)       |
| `stackbone workflows` | List the durable workflows an installation exposes, read one's JSON Schema, start a run by name.           | [workflows](/docs/cli/reference/workflows) |
| `stackbone runs`      | List, inspect, retry and cancel the durable runs an installation produces.                                 | [runs](/docs/cli/reference/runs)           |
| `stackbone hitl`      | The human-in-the-loop approvals inbox: list, read, approve and reject parked decisions.                    | [hitl](/docs/cli/reference/hitl)           |
| `stackbone logs`      | Live-tail an installation's logs over a server-sent stream.                                                | [logs](/docs/cli/reference/logs)           |
| `stackbone contract`  | Inspect the agent-protocol contract an installation advertises, and validate your `agent.yaml` against it. | [contract](/docs/cli/reference/contract)   |
| `stackbone eval`      | Run a saved eval suite, watch it to the end, and exit non-zero if it misses the pass mark.                 | [eval](/docs/cli/reference/eval)           |

### Agent stores

| Command             | What it does                                                                                       | Page                                   |
| ------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `stackbone db`      | Migrations for your workspace database, plus the read-only Explorer verbs against an installation. | [db](/docs/cli/reference/db)           |
| `stackbone storage` | Operate the S3-style object store bound to an installation.                                        | [storage](/docs/cli/reference/storage) |
| `stackbone rag`     | Operate the managed retrieval index: collections, documents, queries and ingest jobs.              | [rag](/docs/cli/reference/rag)         |
| `stackbone secrets` | List, set and remove the secrets bound to an installation. Values are never printed.               | [secrets](/docs/cli/reference/secrets) |
| `stackbone config`  | Manage the agent's versioned `AGENT_CONFIG` document, and regenerate its local types.              | [config](/docs/cli/reference/config)   |
| `stackbone prompts` | Manage the versioned, named-by-key prompt catalog on an installation.                              | [prompts](/docs/cli/reference/prompts) |