clay) is JSON-first: every command writes machine-readable JSON to stdout on success and a structured error envelope to stderr on failure. There are no spinners, colors, or progress bars, so agents and scripts can branch on the output and exit code directly.
Output contract
| Result | Behavior |
|---|---|
| Success | JSON is written to stdout, exit code 0. |
| Failure | { "error": { "code", "message", "details"? } } is written to stderr, non-zero exit code. |
jq, and read the exit code ($?) to decide what to do next.
Exit codes
Branch on these from agents and scripts instead of parsing error text.| Exit | Meaning |
|---|---|
0 | Success. |
1 | Generic or unrecoverable (server_error, contract_mismatch, conflict, internal_error, invalid_config_file). |
2 | validation_error — input was rejected as malformed. |
3 | auth_required | auth_invalid | auth_forbidden — run clay login to (re)authenticate. |
4 | rate_limited (HTTP 429) — details has retryAfter (seconds), plus limit/remaining/reset when Clay sends the X-RateLimit-* headers. |
5 | network_error | network_timeout — could not reach Clay. |
6 | not_found (HTTP 404). |
Environment variables
| Variable | Purpose |
|---|---|
CLAY_API_KEY | API key used when none is stored by clay login. A stored key wins over this variable. |
CLAY_CONFIG_HOME | Highest-precedence config directory parent; config.json and cache.json live under <CLAY_CONFIG_HOME>/clay. |
XDG_CONFIG_HOME | Used when CLAY_CONFIG_HOME is unset (<XDG_CONFIG_HOME>/clay), falling back to ~/.config/clay when neither is set. |
CLAY_REQUEST_TIMEOUT_MS | Per-request network timeout in milliseconds (default 60000). |
CLAY_UPLOAD_TIMEOUT_MS | Bulk file-upload timeout in milliseconds (default 600000). |
Authentication
By default,clay login opens a browser to authorize the CLI with OAuth — this works from a human terminal or an agent’s shell tool. For headless contexts such as CI, pass an API key on stdin instead:
CLAY_API_KEY also authenticates the CLI without logging in at all. Use clay whoami as the canonical check that authentication is working, and clay logout to clear a stored credential.