> ## Documentation Index > Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Command reference > Every breadbox CLI command grouped by noun — auth, server, accounts, transactions, categories, tags, rules, connections, sync, csv, providers, users, logins, reports, keys, config, backup, webhooks, and agent. This page lists every command the CLI exposes. Scope codes follow the same convention as the [REST API](/api/authentication#key-scopes): * **R** — readable with any API key (`read_only` or `full_access`). * **W** — requires a `full_access` key. * **L** — local-only; talks to the service layer or filesystem directly (no HTTP call). Stripped from the lite build. * **—** — no auth (`version`, `auth login`, `completion`). Standard flags apply to every command — `--host`, `--json`, `--ndjson`, `--fields`, `--limit`, `--all`, `--quiet`, `--debug`. See [Output and exit codes](/cli/output) for what they do. Per-command flags are listed inline below; full flag sets live in `breadbox --help`. ## Auth | Command | Scope | Description | | ---------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------ | | `breadbox auth login --host URL [--token KEY]` | — | Add a host. With `--token`, validates and saves the key (paste mode). Without it, runs the interactive device-code flow. | | `breadbox auth logout [name]` | — | Drop credentials for one host, or every host if no name. | | `breadbox auth status` | — | List configured hosts and the current default. | | `breadbox auth use ` | — | Set the default host. | | `breadbox auth bootstrap [--base-url URL]` | L | Mint a `full_access` `user` key via the service layer and save as host `local`. | | `breadbox auth whoami` | R | Print the actor (type + name) and host the current key authenticates as. | See [CLI authentication](/cli/authentication) for the full flow. ## Server and process management These commands operate on the local box (filesystem, DB, embedded migrations) — they do not call the REST API. They are stripped from the lite (`-tags=lite`) build. | Command | Scope | Description | | ------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `breadbox serve [--no-dashboard]` | L | Start the HTTP server (REST + MCP-over-HTTP + dashboard + hosted-link + webhooks). `--no-dashboard` suppresses the dashboard at runtime without recompiling. | | `breadbox mcp` | L | MCP server over stdio; Claude Desktop spawns this per session and blocks until stdin closes. | | `breadbox mcp-stdio` | L | Deprecated hidden alias for `breadbox mcp`. Kept so existing Claude Desktop configs keep working. | | `breadbox init` | L | First-run setup: mints `ENCRYPTION_KEY` if absent, creates the first admin login + household user, prints the first API key. | | `breadbox reveal-key` | L | Print the configured `ENCRYPTION_KEY` to stdout for recovery. 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 (host configured) consumes `GET /api/v1/headless/bootstrap`; local mode (no host) runs env / DB / provider preflight. `--with-live` fires the agent SDK round-trip (\~\$0.01, local-only). | | `breadbox version` | — | Print build version, commit, and upgrade availability. | | `breadbox completion [bash\|zsh\|fish]` | — | Print a shell-completion script. | ## Accounts | Command | Scope | Description | | ------------------------------------------------------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `breadbox accounts list` | R | List household bank accounts. | | `breadbox accounts get ` | R | Single account summary. | | `breadbox accounts detail ` | R | Detail + last 25 transactions + per-currency balances. | | `breadbox accounts update [--name] [--excluded] [--dependent-linked]` | W | Patch display name; hide from views (`--excluded`); exclude from household totals (`--dependent-linked`, e.g. a kid's account you fund but don't count toward your spending). | | `breadbox accounts links list ` | R | List account-link reconciliation rows where this account is primary or dependent. | | `breadbox accounts links add --dependent [--strategy] [--tolerance-days]` | W | Link a dependent account to a primary for reconciliation. | | `breadbox accounts links remove ` | W | Delete an account-link row. | ## Transactions | Command | Scope | Description | | --------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `breadbox transactions list [filters]` | R | Cursor-paginated list. Filters: `--account`, `--category`, `--from`, `--to`, `--search`, `--user`, `--tag`, `--has-comment`, `--cursor`. `--all` walks every page. | | `breadbox transactions get ` | R | Single transaction. | | `breadbox transactions count [filters]` | R | Count matching the same filters as `list`. | | `breadbox transactions summary [--by=category\|month\|week\|day] [filters]` | R | Aggregates with grouping dimension. | | `breadbox transactions update [--category] [--note] [--tags]` | W | Atomic multi-field update. | | `breadbox transactions batch ` | W | Batch update from a JSON file (max 50 rows). | | `breadbox transactions categorize ` | W | Set category as an override. | | `breadbox transactions uncategorize ` | W | Drop the override; revert to provider-default category. | | `breadbox transactions recategorize --target-category [filters]` | W | Server-side recategorize: every row matching the filters becomes `--target-category`. | | `breadbox transactions delete ` | W | Soft-delete (sets `deleted_at`). | | `breadbox transactions restore ` | W | Restore a soft-deleted transaction. | | `breadbox transactions tag ` | W | Attach a tag. | | `breadbox transactions untag ` | W | Detach a tag. | | `breadbox transactions annotations ` | R | Activity-timeline rows (category changes, comments, tags, system events). | | `breadbox transactions comments add ` | W | Add a comment. | | `breadbox transactions comments list ` | R | List comments on a transaction. | | `breadbox transactions comments edit ` | W | Edit an existing comment. | | `breadbox transactions comments delete ` | W | Delete a comment. | ## Categories | Command | Scope | Description | | ------------------------------------------------- | ----- | -------------------------------------------------------- | | `breadbox categories list` | R | List every category. | | `breadbox categories get ` | R | Single category. | | `breadbox categories create [--name] [--parent]` | W | Create a category. | | `breadbox categories update [...]` | W | Update name or parent. | | `breadbox categories delete ` | W | Delete (blocked if any transactions reference it). | | `breadbox categories merge ` | W | Merge `from` → `to` (migrate transactions, drop source). | | `breadbox categories export [--format=tsv\|json]` | R | Dump the category tree. | | `breadbox categories import ` | W | Import categories from TSV. | ## Tags | Command | Scope | Description | | ------------------------------------------------- | ----- | ---------------------------------------------------- | | `breadbox tags list` | R | List every tag. | | `breadbox tags get ` | R | Single tag. | | `breadbox tags create [--label] [--color]` | W | Create a tag. | | `breadbox tags update [...]` | W | Update label or color. | | `breadbox tags delete ` | W | Delete the tag (transactions keep their other tags). | ## Rules | Command | Scope | Description | | ------------------------------------------ | ----- | ------------------------------------------------------------------ | | `breadbox rules list [--enabled]` | R | List transaction rules. | | `breadbox rules get ` | R | Single rule. | | `breadbox rules create --json ` | W | Create a rule from a DSL JSON file. | | `breadbox rules update --json ` | W | Update a rule. | | `breadbox rules delete ` | W | Delete a rule. | | `breadbox rules preview ` | R | Preview which transactions a rule would touch without applying it. | | `breadbox rules apply ` | W | Apply retroactively to existing transactions. | | `breadbox rules batch ` | W | Create or update many rules atomically. | See [Rule DSL](/transactions/rules) for the condition grammar. ## Connections A **connection** is a bank-side OAuth link — a Plaid item, Teller enrollment, or CSV-import bucket. Different from account-links (`breadbox accounts links`) which map household users to bank accounts. | Command | Scope | Description | | ------------------------------------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `breadbox connections list` | R | List bank connections (active + disconnected). | | `breadbox connections get ` | R | Single connection. | | `breadbox connections link [--provider=plaid\|teller] [--user] [--wait]` | W | Mint a hosted-link session. Prints the URL operators or agents open in a browser. `--wait` polls every two seconds until terminal status or 5-minute timeout. | | `breadbox connections link get ` | R | Check a hosted-link session's status (`active` / `completed` / `failed` / `expired`) and the resulting connection IDs. | | `breadbox connections relink [--wait]` | W | Mint a relink hosted-link session for an existing (broken or pending-reauth) connection. | | `breadbox connections disconnect ` | W | Mark connection disconnected (preserves history). | | `breadbox connections delete ` | W | Currently aliases `disconnect` — there is no hard-delete endpoint today. | ## Sync | Command | Scope | Description | | -------------------------------------------------------- | ----- | --------------------------------------------- | | `breadbox sync trigger [--connection] [--account]` | W | Kick a manual sync. | | `breadbox sync status` | R | Last sync per connection and scheduler state. | | `breadbox sync logs [--connection] [--limit] [--follow]` | R | Sync history. `--follow` tails new entries. | ## CSV | Command | Scope | Description | | ------------------------------------------- | ----- | ------------------------------------------------ | | `breadbox csv preview [--account]` | R | Dry-run parse + dedupe report (no rows written). | | `breadbox csv import --account ` | W | Import a CSV into an account. | See the [CSV import guide](/connections/csv-import) for column mapping rules. ## Providers | Command | Scope | Description | | ----------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------ | | `breadbox providers list` | R | What's configured and per-provider status. | | `breadbox providers config plaid [--client-id] [--secret] [--env]` | W | Set Plaid credentials. | | `breadbox providers config teller [--app-id] [--signing-secret] [--pem-file]` | W | Set Teller credentials. | | `breadbox providers test ` | W | Round-trip a credentials check against the provider. | | `breadbox providers disable ` | W | Disable a provider (existing connections keep working until they break). | ## Users | Command | Scope | Description | | ----------------------------------------------- | ----- | ----------------------- | | `breadbox users list` | R | List household members. | | `breadbox users get ` | R | Single user. | | `breadbox users create --name [--email]` | W | Add a household member. | | `breadbox users update [--name] [--email]` | W | Update a member. | | `breadbox users delete ` | W | Remove a member. | ## Logins | Command | Scope | Description | | ------------------------------------------------ | ----- | ---------------------------------------------------------------------------------------------------- | | `breadbox logins list` | W | List admin login accounts. | | `breadbox logins create --user --email [--role]` | W | Create a login account linked to a household user (one-time `setup_token` returned in the response). | | `breadbox logins update --role` | W | Update login role (`admin` / `editor` / `viewer`). | | `breadbox logins delete ` | W | Delete a login. | | `breadbox logins reset-password ` | W | Generate a one-time reset token (returned in the response). | ## Reports Agent reports — summaries an AI agent submits back to the household. See the [agent reports concept](/mcp/reference/reports). | Command | Scope | Description | | ---------------------------------------------- | ----- | ----------------------------------------------- | | `breadbox reports list [--kind] [--status]` | R | List agent reports. | | `breadbox reports get ` | R | Single report. | | `breadbox reports submit --kind --json ` | W | Submit a report on behalf of the current actor. | | `breadbox reports read ` | W | Mark a report read. | | `breadbox reports unread ` | W | Mark a report unread. | ## API keys | Command | Scope | Description | | ---------------------------------------------------------------------------------------------- | ----- | --------------------------------------------------------------------- | | `breadbox keys list` | W | List every API key (the plaintext is never returned). | | `breadbox keys create [--scope=read_only\|full_access] [--actor=user\|agent\|system] [--name]` | W | Mint a new key. The full secret is returned **once** in the response. | | `breadbox keys revoke ` | W | Soft-revoke a key. | ## App config The `app_config` table lets you override certain server settings without restarting (sync interval, agent transcript dir, dashboard banners, …). Precedence is env vars → DB → defaults. | Command | Scope | Description | | ----------------------------------- | ----- | ----------------------------------------------------------------- | | `breadbox config list` | W | List `app_config` entries with their source (env / db / default). | | `breadbox config get ` | W | Get one config value. | | `breadbox config set ` | W | Set a config value (DB source). | | `breadbox config unset ` | W | Remove a DB-sourced value (falls back to env / default). | See [App config precedence](/configuration/app-config) for what's configurable. ## Backup Local-only. Wraps `pg_dump`. The server must be stopped before `backup restore`. | Command | Scope | Description | | ------------------------------------- | ----- | ---------------------- | | `breadbox backup create [--out path]` | L | Dump the database. | | `breadbox backup list` | L | List existing backups. | | `breadbox backup restore ` | L | Restore from a backup. | ## Webhooks | Command | Scope | Description | | ------------------------------------- | ----- | ----------------------------------------------------------------- | | `breadbox webhooks tail [--provider]` | W | Tail recent webhook events as Server-Sent Events from the server. | | `breadbox webhooks replay ` | W | Re-process a stored webhook event. | ## Agent Drive the Claude Agent SDK subsystem (scheduled agent definitions + on-demand runs). See [Scheduled agents](/guides/scheduled-agents) for the full pattern and [`breadbox agent`](/cli/agents) for cookbook examples. | Command | Scope | Description | | ----------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `breadbox agent list [--json]` | L | Every agent definition with status, schedule, model, and next-fire time. | | `breadbox agent run [--json] [--prefix "..."]` | L | Trigger an immediate run — same path as the admin "Run now" button. `--prefix` prepends a per-run operator note to the prompt. | | `breadbox agent test` | L | Smoke test: credential configured, sidecar binary discoverable, "say OK" prompt round-trips. Cost-bounded to \~5¢. Exit `3` = no auth; exit `5` = no binary. | ## Next steps Patterns for driving Breadbox from agent hosts. Trigger and inspect scheduled agent runs.