--json for one result or error object on stdout. Diagnostic text goes to stderr. Success preserves data and pagination and adds meta.http_status, meta.request_id and meta.idempotent_replayed.
Errors include code, message, http_status, request_id, retry_after and mutation_may_have_succeeded. Branch on exit status and code rather than parsing human-readable prose.
Bound your automation
Lists do not fetch all pages automatically. Reads and writes do not retry automatically. Respect request budgets and preserve logical operation keys for mutations. For a timeout or pending result, inspect the resource before deciding how to retry. A zero exit from--dry-run proves local validation only. A nonzero exit after a mutation can still represent a committed change; inspect mutation_may_have_succeeded and the recovery guide.
A read-only shell job
jq is optional external tooling. Reports and redacted previews can still contain customer information. Store output appropriately and never print keys to job logs.