--- title: "Output and automation" description: "Global flags, the JSON envelope, exit codes, error codes, pagination, timeouts, retries, and environment variables for scripting the Bucky CLI." last_updated: "2026-10-29" --- ## Global flags Put global flags **before** the command: `bucky --json projects list`. | Flag | Effect | | --------------------- | ---------------------------------------------------------------------------- | | `--json` | Print one JSON envelope and nothing else | | `--full` | Include detail that compact output leaves out | | `--profile ` | Use a separate saved session ([profiles](/docs/cli/authentication#profiles)) | | `--yes` | Skip the interactive review of a write (required when not in a terminal) | | `--timeout ` | Wait this long for a response; `0` disables it. Default 120 | | `--retries ` | Extra attempts for reads and safe writes. Default 2 | | `--verbose` | Add diagnostic detail to errors (secrets are redacted) | | `--no-color` | Turn off color | | `-V`, `--version` | Print the CLI version | ## JSON output With `--json`, every command prints exactly one envelope: ```json { "schemaVersion": 1, "requestId": "…", "ok": true, "data": { … } } ``` ```json { "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 codes | Code | Meaning | | ----- | --------------------------------------------------------------------------------------------------------------- | | `0` | Success | | `1` | Bucky refused the operation: a validation rule, a cancelled write, a partial batch failure, an unsupported city | | `2` | Invalid input, not signed in, or an infrastructure problem (network, timeout, unexpected response) | | `130` | Interrupted (Ctrl-C) during a write | 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_` for other API errors. A `401` from Bucky becomes `AUTH_REQUIRED`. `bucky --json agent-context` lists every code with its exit code. ## Human output 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 default 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: ```bash bucky --json --full projects get bucky --json --full knowledge search --q "front setback" ``` ## Pagination 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 retries - `--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](/docs/cli/safe-writes#recovering-from-an-unknown-outcome). - 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 variables | Variable | Effect | | ------------------------------------ | ---------------------------------------------------------------- | | `BUCKY_PROFILE` | Same as `--profile` | | `BUCKY_API_URL` | Bucky deployment to sign in to. Default `https://buckybuild.com` | | `BUCKY_ACCESS_TOKEN` | Use this token for the run; never saved or refreshed | | `BUCKY_EMAIL`, `BUCKY_PASSWORD` | Headless `auth login` | | `BUCKY_NO_TUI` | No prompts, spinners, or progress frames | | `NO_COLOR` | No color | | `XDG_CONFIG_HOME` | Where profiles are saved (default `~/.config`) | | `XDG_STATE_HOME` | Where receipts are saved (default `~/.local/state`) | | `EDITOR`, `VISUAL` | Editor for the **edit** option when reviewing a write | | `DO_NOT_TRACK`, `BUCKY_NO_TELEMETRY` | Leave the command name out of the `User-Agent` header | ## What each request identifies Every request to the Bucky API carries `User-Agent: bucky-cli/ (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/`. Commands that run offline, such as `help` and `agent-context`, send nothing. ## Shell completion ```bash 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. ## Sitemap See the full [sitemap](/sitemap.md) for all pages.