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.

The CLI is designed to be both readable on a TTY and scriptable from a pipe. When you run a list command in a terminal you get a compact table; when stdout is piped, the same command emits JSON automatically. Exit codes are a stable contract — agents and CI can branch on them.

​
Output modes

FlagOutputWhen to use
(default on TTY)Human-readable tableInteractive use.
(default on non-TTY)Compact JSON arrayPiping into jq, scripts, agents.
--jsonCompact JSON array, forcedForce JSON inside a TTY (e.g., when copying into a snippet).
--ndjsonOne JSON object per lineStreaming large lists; lets consumers process records as they arrive without buffering the whole array.
--quietSuppress human output; emit only IDs (for write commands) or nothingCron jobs that should fail silently on success.
--debugVerbose stderr logging (request URLs, headers, retries)Diagnosing why a command isn’t behaving as expected.

​
Default auto-detection

breadbox transactions list in a terminal prints a table. The same command piped to jq emits JSON without --json. Agents calling the CLI never need to pass --json — they just read JSON off stdout. 
# Interactive
breadbox transactions list
# ┌────────┬────────────┬───────────┬────────────┐
# │ id     │ date       │ amount    │ name       │
# ├────────┼────────────┼───────────┼────────────┤
# │ ...    │ 2026-05-26 │   12.50   │ Trader Joe │
# └────────┴────────────┴───────────┴────────────┘

# Piped — JSON kicks in automatically
breadbox transactions list | jq '.[].name'

​
Field selection

Most list endpoints support ?fields=<presets> server-side; the CLI exposes this as --fields: 
breadbox transactions list --fields=core,timestamps
breadbox accounts list --fields=balances
Field presets are documented per resource in the API Reference. Passing --fields keeps responses small over slow links and reduces the JSON your agent has to parse.

​
Cursor pagination

Cursor-paginated commands (transactions list, rules list) accept --limit (default 25, max 500) and walk one page at a time. Pass --all to fetch every page sequentially and stream the combined result: 
# One page (25 rows)
breadbox transactions list

# Custom page size
breadbox transactions list --limit 200

# Walk every page (best paired with --ndjson)
breadbox transactions list --all --ndjson > all-transactions.ndjson
See API pagination for the underlying cursor contract.

​
Exit codes

CodeMeaningTypical cause
0SuccessCommand completed and any side effects landed.
1Runtime errorLocal I/O, parsing, panic, unexpected condition.
2Usage errorWrong flag, missing required argument, mutually exclusive flags.
3Auth errorMissing host, revoked key, denied device-code, scope insufficient.
4Upstream errorServer returned 5xx (HTTP 500, 502, 503). Worth retrying.
5Validation errorServer returned 4xx other than 401/403 — bad request body, conflict, validation failure. Not worth retrying without changing the input.
Branching on exit codes lets agents distinguish “the server is down, retry later” (4) from “my request is wrong, don’t retry” (5) from “my key is broken, surface this to the operator” (3): 
breadbox sync trigger --connection conn_abc123
status=$?
case $status in
  0) echo "synced" ;;
  3) echo "auth broken — alert operator" ;;
  4) echo "server down — retry in 5 min" ;;
  5) echo "validation failed — check parameters" ;;
  *) echo "unknown failure" ;;
esac

​
Errors

Errors print to stderr in the same JSON envelope the API uses: 
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "X-API-Key header is required."
  }
}
The error.code field is stable (UPPER_SNAKE_CASE) and safe to grep. The error.message is for humans and may change between releases.

​
Combining flags

The standard flags are orthogonal — --host, --json, --fields, --limit, --all, --quiet, --debug apply to every command and can be combined freely: 
breadbox transactions list \
  --host production \
  --all \
  --ndjson \
  --fields=core,merchant \
  --limit 500 \
  --quiet \
  > transactions.ndjson 2> debug.log
Per-command flags (like --wait on connections link, --prefix on agent run, --scope on keys create) layer on top.

​
Next steps

Command reference

Every command grouped by noun.

Headless deployment

Agent patterns and CI examples.