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 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. Global flags, environment variables and on-disk state live at Configuration, and the manifest fields at 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, 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 for the full shape of that file.

If you are new to these concepts, read Agents, Workflows and Stackbone Connect first.

Going to production

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

• stackbone 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 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 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
stackbone logout	Revoke the active session and drop it from disk.	login
stackbone whoami	Show the active user and organization.	inspection
stackbone current	Print the slug of the organization currently linked to this session.	inspection
stackbone list	List the organizations you belong to.	inspection
stackbone organization use	Choose which organization the CLI acts as.	inspection
stackbone metadata	One payload with user, organization, agents and runtime state, for a coding agent to plan from.	inspection

Your project

Command	What it does	Page
stackbone init	Scaffold a new workspace and link it to your organization.	init
stackbone add	Add one agent, workflow or workflow-agent to an existing workspace. Offline, writes only new files.	add
stackbone link	Link the current directory to an organization + agent, and register the deployment you run that agent on.	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
stackbone docs	Print the connection details for the documentation MCP server.	docs

Shipping

Command	What it does	Page
stackbone build	Compile the project into the workspace bundle your container image serves the agent from.	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

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
stackbone workflows	List the durable workflows an installation exposes, read one's JSON Schema, start a run by name.	workflows
stackbone runs	List, inspect, retry and cancel the durable runs an installation produces.	runs
stackbone hitl	The human-in-the-loop approvals inbox: list, read, approve and reject parked decisions.	hitl
stackbone logs	Live-tail an installation's logs over a server-sent stream.	logs
stackbone contract	Inspect the agent-protocol contract an installation advertises, and validate your agent.yaml against it.	contract
stackbone eval	Run a saved eval suite, watch it to the end, and exit non-zero if it misses the pass mark.	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
stackbone storage	Operate the S3-style object store bound to an installation.	storage
stackbone rag	Operate the managed retrieval index: collections, documents, queries and ingest jobs.	rag
stackbone secrets	List, set and remove the secrets bound to an installation. Values are never printed.	secrets
stackbone config	Manage the agent's versioned AGENT_CONFIG document, and regenerate its local types.	config
stackbone prompts	Manage the versioned, named-by-key prompt catalog on an installation.	prompts