Output & exit codes

The renza CLI is driven as often by an agent as by a human, so its output is a contract, not a convenience. The same command serves both audiences — the difference is rendering, never capability.

Output modes

On a terminal, output is compact and human-readable — a one-line summary for single objects, an aligned table for lists.
--json prints the exact API response body (the same envelope documented on every reference page), pretty-printed. This is the shape to code against — it equals what the HTTP API returns, field for field.
Piped or non-TTY output defaults to JSON automatically: a pipe means a machine is reading.
Lists under --json stream as NDJSON — one object per line, so large pages are consumable incrementally.
--quiet / -q prints only the primary id(s) — ideal for command substitution:

deck=$(renza decks create -q --title "Q3 Board Deck")
renza shares create "$deck" --mode link

Status and progress go to stderr; results go to stdout — they never interleave, so redirection always captures clean data. Colour respects NO_COLOR and disables itself when not a TTY.

Exit codes

Exit codes are a closed set mapped from the API error types — scripts branch on the code; the code field in the --json error envelope is the precise discriminator:

Exit	Meaning	Maps from
`0`	success	—
`1`	generic / unexpected	`api_error`, unhandled
`2`	usage error (bad flags, missing arg, refused destructive action without `--yes`)	local validation
`3`	not found	`resource_not_found`
`4`	authentication (missing/invalid key or session)	`authentication_error`
`5`	permission / no org	`permission_error`, `org_required`
`6`	conflict (idempotency or state)	`conflict_error`
`7`	rate limited	`rate_limit_error`

Errors print the standard envelope to stderr — the full JSON envelope under --json, a one-line ✗ code: message otherwise.

Global flags

Flag	Effect
`--json`	Machine output (the exact API envelope; lists as NDJSON)
`-q`, `--quiet`	Print only the primary id(s)
`-y`, `--yes`	Skip interactive confirmation on destructive actions (required for scripts)
`--api-key <key>`	Override the stored credential (highest precedence)
`--api-url <url>`	Target a different API host (staging, local)

Credential precedence: flags → RENZA_API_KEY / RENZA_API_URL env vars → ~/.renza/config.json (written by renza login). See Authentication.

Writes from scripts

--idempotency-key <uuid> on any write sends the Idempotency-Key header — safe retries for flaky networks.
Destructive commands (delete, revoke) confirm interactively on a TTY. In a script, pass --yes — a non-TTY destructive call without --yes is a usage error (exit 2), never a silent deletion.
Pagination: --limit / --cursor mirror the API; --all opt-in follows cursors and emits every page.