You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A terse catalog of every command the breadbox CLI exposes. The CLI drives the same surface documented in docs/api-endpoints.md — every data command is a thin shell over the REST API, plus a handful of server-only commands (serve, mcp, init, migrate, backup) that talk to the service layer directly because there's no server to talk to. Keep this file in sync with the cobra command tree — see .claude/rules/cli-commands.md for the upkeep rule.
Architecture
One binary, multiple roles.breadbox is the same binary as the server. It can run as a server (serve), as an MCP stdio host (mcp), or as a CLI that drives a local or remote breadbox over HTTP. The dashboard and CLI share one process when needed; nothing is reimplemented.
Local vs remote, same commands.breadbox transactions list works against http://localhost:8080 (default), a Unix socket, or --host my-remote-server. The CLI never reaches into the DB except when bootstrapping (init, migrate, auth bootstrap when no server is running) — in those cases there's no API to call.
Build tags.
Default build: full binary (server + CLI + dashboard).
-tags=headless: server + CLI, no dashboard assets.
-tags=lite: CLI-only, no server packages, no DB drivers. Ships as breadbox-cli for remote agents.
See .claude/rules/build-tags.md for the exclusion matrix.
Auth. Per-host credentials live in ~/.config/breadbox/hosts.toml. Add a host with breadbox auth login (interactive device-code) or breadbox auth login --host=URL --token=bb_.... Switch with --host <name> or BREADBOX_HOST=<name>. On a local box you've never logged into, breadbox auth bootstrap mints a key automatically.
Output. Default is a human table on stdout. Add --json for machine-readable JSON, --ndjson for streaming large lists, --fields=core,timestamps to pass through API field selection.
Standard flags (apply to every command): --host, --json, --ndjson, --fields, --limit, --all, --quiet, --debug. Per-command flags are listed in breadbox <noun> <verb> --help.
Exit codes.0 success, 1 runtime error, 2 usage error, 3 auth error (missing or revoked key), 4 upstream API error (server returned 5xx), 5 validation error (server returned 4xx). Agents can branch on these reliably.
Scope column: R = readable with any API key, W = requires full_access scope, L = local-only (talks to service layer / DB; no API call).
Auth
Command
Scope
Description
breadbox auth login --host URL [--token KEY]
—
Add a host; with --token, paste-mode validates and saves; without it, runs the interactive device-code flow (operator approves in a browser)
breadbox auth logout [name]
—
Drop credentials for a host
breadbox auth status
—
List configured hosts + which is default
breadbox auth use <name>
—
Set the default host
breadbox auth bootstrap [--base-url URL]
L
Local-only: mint a full_accessuser-actor key via the service layer and save as host local
breadbox auth whoami
R
Print the API key's actor (type + name) and host
Server / process
Command
Scope
Description
These commands operate on the local box (filesystem, DB, embedded migrations) — they do not call the REST API. They're stripped from the -tags=lite build.
Command
Scope
Description
breadbox serve [--no-dashboard]
L
Start the HTTP server (REST + MCP-over-HTTP + dashboard)
breadbox mcp
L
MCP server over stdio; Claude Desktop spawns this per session, blocks until stdin closes. Uses a singleton actor_type='system' api_keys row so the audit trail attributes every stdio call consistently
breadbox mcp-stdio
L
deprecated — use breadbox mcp instead. Hidden alias kept so existing Claude Desktop configs keep working
breadbox init
L
First-run setup: encryption key, first login account, first API key
breadbox reveal-key
L
Print the configured ENCRYPTION_KEY to stdout for recovery into a password manager. Exit 1 when no key is set
breadbox migrate [--down] [--to N]
L
Run goose migrations against DATABASE_URL (local-only — there is no remote migration endpoint by design)
breadbox doctor [--skip-external] [--with-live]
R/L
Remote mode (when a host is configured) consumes GET /api/v1/headless/bootstrap; local mode (no host) keeps the env/DB/provider preflight checks. --with-live additionally fires the agent SDK round-trip (~$0.01, local-mode only)
breadbox agent test
L
End-to-end smoke test of the Claude Agent SDK subsystem — verifies credential is configured, sidecar binary is discoverable, and a tiny "say OK" prompt round-trips through the SDK. Cost-bounded to ~5¢. Exit 3 = no auth; exit 5 = no binary
breadbox agent run <slug> [--json] [--prefix "..."]
L
Trigger an immediate run of the named agent — same path as the admin /agents "Run now" button. Mints a scoped API key, spawns the sidecar, persists the agent_runs row, revokes the key. --prefix prepends a per-run operator note to the prompt for this fire only. --json switches to the full AgentRunResponse JSON
breadbox agent list [--json]
L
Print every agent definition with status, schedule, model, and next-fire time as a table. --json emits the full AgentDefinitionResponse array for piping into jq. Useful for SSH-based ops without opening the admin dashboard
breadbox version
—
Print build version, commit, and upgrade check
breadbox completion [bash|zsh|fish]
—
Print a shell-completion script (e.g. breadbox completion zsh > _breadbox) for tab-completion of nouns/verbs/flags — same pattern as gh, kubectl
Accounts
Command
Scope
Description
breadbox accounts list
R
List household bank accounts
breadbox accounts get <id>
R
Single account summary
breadbox accounts detail <id>
R
Detail + last 25 transactions + per-currency balances
Patch display name, --excluded (hide from views), --dependent-linked (exclude from household totals — e.g., a kid's account you fund but don't count toward your spending)
breadbox accounts links list <id>
R
List account-link reconciliation rows where this account is primary or dependent
Merge from → to (migrate transactions, drop source)
breadbox categories export [--format=tsv|json]
R
Dump categories
breadbox categories import <file>
W
Import from TSV
Tags
Command
Scope
Description
breadbox tags list
R
List all tags
breadbox tags get <slug>
R
Single tag
breadbox tags create <slug> [--label] [--color]
W
Create a tag
breadbox tags update <slug> [...]
W
Update label / color
breadbox tags delete <slug>
W
Delete a tag
Rules
Command
Scope
Description
breadbox rules list [--enabled]
R
List transaction rules
breadbox rules get <id>
R
Single rule
breadbox rules create --json <file>
W
Create a rule from a DSL JSON file
breadbox rules update <id> --json <file>
W
Update a rule
breadbox rules delete <id>
W
Delete a rule
breadbox rules preview <id>
R
Preview matches without applying
breadbox rules apply <id>
W
Apply retroactively to existing transactions
breadbox rules batch <file>
W
Create / update many rules atomically
Connections
A connection is a bank-side OAuth link (Plaid item, Teller enrollment, or CSV-import bucket). Different from account-links (which live under breadbox accounts links and map household users to bank accounts).
Command
Scope
Description
breadbox connections list
R
List bank connections (active + disconnected)
breadbox connections get <id>
R
Single connection
breadbox connections link [--provider=plaid|teller] [--user] [--wait]
W
Mint a hosted-link session (POST /connections/link), print the URL agents and users can open in a browser; --wait polls until completed
breadbox connections link get <session-id>
R
Check a hosted-link session's status (active / completed / failed / expired) and the resulting connection IDs
List app_config entries (with source: env / db / default)
breadbox config get <key>
W
Get one config value
breadbox config set <key> <value>
W
Set a config value (db source)
breadbox config unset <key>
W
Remove a db-sourced value (falls back to env / default)
Backup
Command
Scope
Description
breadbox backup create [--out path]
L
Dump the database (pg_dump under the hood)
breadbox backup list
L
List existing backups
breadbox backup restore <file>
L
Restore from a backup (server must be stopped)
Webhooks
Command
Scope
Description
breadbox webhooks tail [--provider]
W
Tail recent webhook events (SSE from server)
breadbox webhooks replay <id>
W
Re-process a webhook event
Headless / agent surface
Agents can drive Breadbox via the CLI as a more direct alternative to MCP. Two recommended patterns:
Local same-host agent. Agent runs on the same machine as breadbox serve. Get a key with breadbox keys create --actor=agent --name="<agent-name>", store it as the agent's BREADBOX_TOKEN. All commands work over loopback (or Unix socket for speed).
Remote agent (lite CLI). Build -tags=lite (breadbox-cli binary) and ship it to the agent host. User provisions a key via breadbox keys create --actor=agent --name=... on the server side, hands it to the agent; agent runs breadbox-cli auth login --host=https://your-breadbox --token=<key>. From there, every data command works identically.
The CLI prints JSON to stdout when stdout isn't a TTY, so agents don't need to pass --json — piping just works.