Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.breadbox.sh/llms.txt

Use this file to discover all available pages before exploring further.

breadbox is a single Go binary that plays three roles. It hosts the HTTP server (breadbox serve), it speaks MCP over stdio for Claude Desktop (breadbox mcp), and it acts as a CLI client driving a local or remote Breadbox over HTTP (breadbox transactions list, breadbox connections link --wait, and so on). The CLI is a thin shell over the REST API. Every data command — anything that lists, gets, creates, updates, or deletes a resource — calls the same /api/v1/* endpoint a curl one-liner would. A handful of commands (serve, mcp, init, migrate, backup, reveal-key, doctor in local mode) talk to the service layer or filesystem directly because there is no server to talk to.

​
Why a CLI when there’s an API and a dashboard?

  • Headless deployments. SSH into a NAS, run breadbox sync trigger, walk away.
  • Agents. AI agents reading and writing data through one stable, scriptable surface — same shape on every host, JSON on every pipe.
  • Scripting. Cron jobs, GitHub Actions, shell pipelines. The CLI auto-emits JSON when stdout is not a TTY, so breadbox transactions list | jq just works.
  • Operations. breadbox doctor, breadbox sync logs --follow, breadbox backup create are the operator surface; no dashboard needed.

​
Three builds, one source tree

BuildCommandWhat shipsWhen to use
Full (default)go build -o breadbox ./cmd/breadboxServer + CLI + admin dashboardThe everyday self-hosted deployment.
Headlessgo build -tags=headless -o breadbox ./cmd/breadboxServer + CLI, no dashboard assetsServers where you don’t want the dashboard compiled in at all. Same REST/MCP/webhook surface.
Litego build -tags=lite -o breadbox-cli ./cmd/breadboxCLI only — no server packages, no DB drivers, no provider SDKsAgent hosts and ops boxes that only drive a remote Breadbox over HTTP.
The full and headless builds also accept --no-dashboard at runtime — useful when you want the same binary in dev and prod but want to suppress the dashboard in prod without recompiling. See Installation for how to get each flavor onto your machine.

​
How the CLI is organized

Every command follows the same breadbox <noun> <verb> [args] [flags] shape: 
breadbox accounts list
breadbox transactions update <id> --category groceries
breadbox connections link --provider plaid --wait
The <noun> matches a REST resource (transactions, accounts, rules, …) or a CLI-only concept (auth, keys, config, backup, agent). The <verb> is typically list, get, create, update, delete, plus resource-specific verbs like categorize, merge, apply, tail, relink. See Commands for the full catalog organized by noun.

​
Authentication, in one paragraph

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_… (paste mode for headless). Switch with --host <name> or BREADBOX_HOST=<name>. On a local machine you’ve never logged into, breadbox auth bootstrap mints a full_access key via the service layer and saves it as host local. Full flow at Authentication.

​
Output and exit codes

The CLI prints a human table on a TTY and emits JSON automatically when stdout is piped. Add --json to force JSON anywhere, --ndjson for streaming large lists, or --fields=… to pass through API field selection. Exit codes are a contract: 0 success, 1 runtime, 2 usage, 3 auth, 4 upstream (server 5xx), 5 validation (server 4xx). Agents and scripts can branch on these. See Output and exit codes.

​
Next steps

Install the CLI

Pick a build flavor and get it on your machine.

Authenticate

Device-code login, paste-mode, and auth bootstrap.

Command reference

Every noun and verb, with scope and behavior notes.

Headless deployment

Patterns for running agents against a remote Breadbox.