Auto-detect agent contexts for JSON output; gh-style exit codes

[kcmannem]

Summary

Mirrors the workos CLI behavior so agents and shell pipelines get machine-readable output and meaningful exit codes without callers having to opt in.

• Auto-detect JSON output. clickhousectl now emits JSON to stdout when any of these hold: --json is passed, stdout is not a terminal, or one of CLAUDECODE / CURSOR_AGENT / CODEX_SANDBOX is set. Resolution lives in src/output_mode.rs and is computed once in main / run_cloud, so all downstream json: bool plumbing stays unchanged.
• gh-style exit codes. Error::exit_code() now returns 0 success, 1 error, 2 cancelled, 4 auth required. CloudError carries a kind (Generic / Auth); 401/403 responses, missing creds, and the OAuth-only-can't-write block all route to Error::AuthRequired and exit with 4.
• Docs (README.md, CLAUDE.md, cli.rs after_help) document the new behavior.

Test plan

• cargo build -p clickhousectl
• cargo test -p clickhousectl — 283 + 37 tests pass, including new tests for output_mode::resolve and Error::exit_code
• Smoke: cargo run -- local list (non-TTY) → JSON without --json
• Smoke: CLAUDECODE=1 cargo run -- local list → JSON
• Smoke: cargo run -- cloud service list with no creds → exit 4
• Smoke: cargo run -- local use 99.99 → generic error, exit 1

---

Note

Low Risk
Behavior changes are limited to CLI output mode, exit codes, and error classification; no auth protocol or cloud API contract changes beyond clearer exit 4 for credential failures.

Overview
Adds agent-aware JSON output and gh-style exit codes so scripts and coding agents can rely on machine-readable stdout and meaningful process exits without always passing --json.

JSON: A new json_output() helper turns on JSON when --json is set or is_ai_agent::detect() finds a known agent (same signal as the outbound User-Agent). Local and cloud dispatch use it instead of the raw flag; cloud auth status follows the same rule. local server start --foreground with --json no longer errors—the foreground path ignores JSON because it never prints a summary.

Exit codes: Error::exit_code() maps success/cancelled/auth to 0 / 2 / 4 (everything else 1); main exits with that code. CloudError gains CloudErrorKind (Auth vs Generic): missing/partial API keys, no credentials, and API 401/403 become Error::AuthRequired (exit 4); OAuth blocked on write commands and half-set login flags route there too. Cloud handlers that return Box<dyn Error> preserve auth kind via downcast to CloudError.

Docs (README, AGENTS.md, cloud after_help) describe auto-JSON for agents and the exit table.

^{Reviewed by Cursor Bugbot for commit dc032b4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[sdairs]

@kcmannem love the idea; dynamically adapting the experience for agents I've something I've been playing around with (even so far as completely changing the command layout for agents - some fun results in evals) - but I haven't played around with output formats yet. I assume most run --json anyway so that they can jq, so in theory I'm supportive.

Before merging, I'm going to run some comparative evals to see how models react to this change.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8440191. Configure here.}

[sdairs]

Pushed a round of review changes (commits 7b9931c..d4f23de):

JSON output mode

• Use the existing is_ai_agent::detect() (same detection as the User-Agent) instead of a hardcoded CLAUDECODE/CURSOR_AGENT/CODEX_SANDBOX list — broader, consistent coverage (standard AGENT var, Gemini CLI, Goose, Devin, …).
• Dropped the non-TTY → JSON trigger. Auto-JSON now fires only for detected agents or explicit --json; pipes/redirects stay human-readable (matches gh/kubectl). This also fixes the red local postgres edge cases job, which pipes output and greps human tables.
• server start --foreground now simply ignores --json (it streams stdout/stderr, no JSON summary) instead of erroring. Removed JsonForegroundConflict, the json_explicit plumbing, and the #[allow(too_many_arguments)].
• Collapsed output_mode.rs into a one-line json_output() helper.

Exit codes

• Fixed an inconsistency (thanks Bugbot): partial --api-key/--api-secret on cloud auth login now exits 4 like the same condition in resolve_auth, not 1.
• Added unit tests for the previously-untested convert_error classification (401/403 → Auth, else Generic) and the Box<dyn Error> downcast routing.

Docs: README, cli.rs after_help, and CLAUDE.md updated to match.

Follow-ups filed: #233 (return a concrete Error from cloud handlers to retire the downcast) and #234 (review the exit-code taxonomy — 403 granularity, 5xx, 429/rate-limit backoff, etc.).

[sdairs]

take a look at how we do agent detection when building the user agent string for http calls; we should do it the same way (I maintain a library for it that detects more agents already)

[sdairs]

https://github.com/ClickHouse/clickhousectl/blob/main/crates/clickhousectl/src/user_agent.rs

[sdairs]

https://crates.io/crates/is-ai-agent

[iskakaushik]

LGTM!