Commands reference

Every CLI command Stackbone ships today, with flags, exit codes and JSON output.

Every command shipped today, grouped by purpose. Each entry documents the synopsis, flags, the human-mode output, the --json shape and the exit codes that may be raised.

The canonical reference is stackbone docs cli (no network, no fetch). When this page and the binary disagree, the binary wins.

Conventions

All commands accept the global flags documented in Configuration → Global flags.
All --json payloads are wrapped in { "schema_version": 1, ... } — see Configuration → Output contract.
Exit codes follow the table in Configuration → Exit codes.

Authentication

`stackbone login`

Authenticate the CLI via the device-code flow (RFC 8628). Stores the session in ~/.stackbone/credentials.json (chmod 600).

Flag	Type	Description
`--no-browser`	boolean	Print the verification URL + code instead of opening the browser. Auto-detected when `CI`, `SSH_CLIENT`, or `SSH_TTY` is set.

JSON payload

{
  "schema_version": 1,
  "user": { "id": "...", "email": "..." },
  "control_plane_url": "https://api.stackbone.dev",
  "expires_at": "2026-...",
}

Exit codes: 0 ok, 2 auth, 1 generic.

`stackbone logout`

Revoke the active session and drop it from disk. No flags.

JSON payload

{
  "schema_version": 1,
  "control_plane_url": "https://api.stackbone.dev",
  "previous_user": { "id": "...", "email": "..." } /* or null */,
}

Inspection

`stackbone whoami`

Show the active user and workspace.

JSON payload

{
  "schema_version": 1,
  "user": { "id": "...", "email": "..." },
  "workspace": { "id": "...", "slug": "...", "name": "..." },
  "control_plane_url": "https://api.stackbone.dev",
}

Exit codes: 0 ok, 2 auth.

`stackbone current`

Print the slug of the workspace currently linked to this session. Newline-delimited <slug>\t<name> in human mode.

`stackbone list`

List workspaces the current user belongs to. Tab-separated table in human mode (SLUG\tNAME\tID).

`stackbone metadata`

One-shot agent-friendly overview. Replaces whoami + current + list for callers that want a single payload to plan from. Today it returns workspace, user and an empty agents / deployments / channels array — the shape is stable across epics so coding agents can rely on it.

{
  "schema_version": 1,
  "cliVersion": "0.0.1",
  "controlPlaneUrl": "https://api.stackbone.dev",
  "user": { "id": "...", "email": "..." } /* or null */,
  "workspace": { "id": "...", "slug": "...", "name": "..." } /* or null */,
  "agents": [],
  "deployments": [],
  "channels": [],
  "runtime": {
    "local": { "running": false },
    "remote": null,
  },
}

Project lifecycle

`stackbone init [name]`

Scaffold a new Stackbone project: agent record on the control plane, template files on disk, agent.yaml, .stackbone/project.json, .gitignore patch and a Claude Code skill. See Claude Code skill for the skill bundle.

Flag	Type	Default	Description
`[name]` positional	string	cwd basename	Subdirectory + initial agent name. Omit to use the current directory.
`--template`	string	`hello-world`	One of `hello-world`, `workflow`, `autonomous`.
`--slug`	string	derived	Override the agent slug. Lowercase, digits and single hyphens only.
`--description`	string		Optional human-readable description for the agent.
`--force`	boolean	`false`	Overwrite existing files in the target directory.

Interactive prompts — when stdin is a TTY and neither -y nor --json are set, init prompts for the missing name and template.

JSON payload

{
  "schema_version": 1,
  "agent": { "id": "...", "slug": "...", "name": "..." },
  "workspace_id": "...",
  "target_dir": "/abs/path",
  "template": "hello-world",
  "files_written": ["src/index.ts", "package.json", "..."],
}

Exit codes: 0 ok, 2 auth, 1 generic (e.g. directory contains conflicting files and --force was not passed).

`stackbone link`

Link the current directory to an existing workspace + agent. Writes .stackbone/project.json, patches .gitignore, regenerates the Claude skill. Does not scaffold template files — use init for that.

Flag	Type	Description
`--agent`	string	Agent slug to link to. Required in non-interactive mode (CI, `--json`, `-y`).
`--force`	boolean	Overwrite an existing `.stackbone/project.json`.

JSON payload

{
  "schema_version": 1,
  "agent": { "id": "...", "slug": "...", "name": "..." },
  "workspace_id": "...",
  "target_dir": "/abs/path",
  "files_written": [".stackbone/project.json", ".gitignore", ".claude/skills/stackbone/SKILL.md"],
}

Local development

`stackbone dev`

Run the local control-plane emulator. Boots Postgres + MinIO via Docker Compose, runs the agent under @stackbone/sdk, exposes the Studio API at http://127.0.0.1:4242 and (by default) opens a Cloudflare quick tunnel so cloud-hosted Studio can reach it.

Full reference: Local development.

Flag	Type	Default	Description
`--port`	number	`4242`	Studio API port.
`--tunnel` / `--no-tunnel`	boolean	`true`	Open a public Cloudflare quick tunnel.
`--auto-cloudflared` / `--no-auto-cloudflared`	boolean	`true`	Auto-fetch `cloudflared` into `~/.cache/stackbone/bin` when missing. Skip with `--no-auto-cloudflared` to require a system install.
`--listen`	boolean	`false`	Bind the HTTP server to `0.0.0.0` (LAN-reachable). Default binds to `127.0.0.1` only.

JSON payload (printed once when the emulator is fully up)

{
  "schema_version": 1,
  "emulator_url": "http://127.0.0.1:4242",
  "agent_url": "http://127.0.0.1:<auto>",
  "public_url": "https://<random>.trycloudflare.com" /* or null */,
  "services": {
    "postgres_url": "postgres://...",
    "queue_url": "...",
    "s3_endpoint": "http://127.0.0.1:9004",
    "s3_bucket": "stackbone-dev",
  },
}

Exit codes: 0 ok (graceful Ctrl-C), 3 no project (cwd has no .stackbone/project.json), 4 not found (linked agent disappeared upstream), 1 generic (Docker missing, port busy, …).

Cloud deployment

`stackbone deploy`

🚧 TODO — stubbed today. Tracked by the sibling task Implementar stackbone deploy a Fly Machines. When shipped this command will:

Build the agent image (multi-stage Dockerfile, distroless Node 24).
Push it to the platform registry.
Update the active version on Fly Machines.

Run stackbone docs cli once the task lands for the actual reference.

Inline help

`stackbone docs [topic]`

Print Stackbone documentation inline (no browser, no fetch). Useful when an agent of coding wants to look up the contract without burning tokens on a network round-trip.

Topics shipped today: cli, sdk, dev, agent-yaml (TODO), templates (TODO), connections (TODO).

stackbone docs            # list topics
stackbone docs cli        # CLI reference (mirror of this wiki, condensed)
stackbone docs sdk        # @stackbone/sdk overview
stackbone docs dev        # stackbone dev reference