Output and automation

Global flagsCopy Anchor Link

Put global flags before the command: bucky --json projects list.

JSON outputCopy Anchor Link

With --json, every command prints exactly one envelope:

{ "schemaVersion": 1, "requestId": "…", "ok": true, "data": { … } }

{
  "schemaVersion": 1,
  "requestId": "…",
  "ok": false,
  "data": null,
  "error": { "code": "AUTH_REQUIRED", "message": "…", "details": { … } },
  "hint": "Run `bucky auth login`."
}

requestId is unique to the run. Quote it when you contact support. The hint is a safe next step; the CLI never runs it for you.

JSON and piped output never contain prompts, spinners, or color codes.

Exit codesCopy Anchor Link

Common error codes: INVALID_ARGUMENT, VALIDATION_FAILED, AUTH_REQUIRED, NETWORK_ERROR, TIMEOUT, CITY_UNSUPPORTED, MUTATION_CONFIRMATION_REQUIRED, MUTATION_CANCELLED, BATCH_PARTIAL_FAILURE, MUTATION_INTERRUPTED, and HTTP_<status> for other API errors. A 401 from Bucky becomes AUTH_REQUIRED. bucky --json agent-context lists every code with its exit code.

Human outputCopy Anchor Link

Without --json, output is summary-first: a one-line outcome, then the key facts or a table sized to your terminal. Errors say what happened, the likely cause, and a safe next step.

The CLI picks one of three modes:

• machine — --json, or stdout is piped.
• human-interactive — both stdin and stdout are a terminal. Prompts and progress are shown.
• human-static — CI, BUCKY_NO_TUI, TERM=dumb, or no terminal on stdin. No prompts or animation.

Compact by defaultCopy Anchor Link

Output is compact so it doesn't flood an agent's context. For example, knowledge search leaves out long section bodies, project detail leaves out associations, and references list returns 20 rows unless you ask for more. Add --full when you need everything:

bucky --json --full projects get <project-id>
bucky --json --full knowledge search --q "front setback"

PaginationCopy Anchor Link

List responses keep their pagination fields. Commands that page by offset take --limit and --offset; continue while pagination.hasMore is true. Commands that page by cursor (for example screen lots and conversations list) return a nextCursor; pass it back with --cursor until it is null.

Timeouts and retriesCopy Anchor Link

• --timeout covers the wait for response headers and the full JSON body. For streaming commands such as chat turn, it is an idle timeout that resets each time data arrives.
• Reads and safe writes retry twice by default on timeouts, rate limits, server errors, and network failures, and respect Retry-After.
• Writes that could create a duplicate are never retried automatically. Don't wrap the CLI in your own retry loop; use the recovery steps in Safe writes.
• Slow commands document it: opportunities screen can take minutes, and analysis wait, feasibility preview --wait, and package-checks run --wait poll until a result is ready.

Environment variablesCopy Anchor Link

What each request identifiesCopy Anchor Link

Every request to the Bucky API carries User-Agent: bucky-cli/<version> (command=<command>), for example bucky-cli/0.14.0 (command=projects location set). The command name comes from the CLI's fixed command list; arguments, flag values, ids, file paths, tokens, and results are never put in a header. Set DO_NOT_TRACK=1 or BUCKY_NO_TELEMETRY=1 to send only bucky-cli/<version>. Commands that run offline, such as help and agent-context, send nothing.

Shell completionCopy Anchor Link

bucky completion zsh > ~/.zsh/completions/_bucky
bucky completion bash >> ~/.bashrc
bucky completion fish > ~/.config/fish/completions/bucky.fish

Completion suggests your projects, conversations, and cities using quick read-only lookups.