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
Pipe stdout straight into
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.Environment variables
Authentication
clay login opens a browser to authorize the CLI with OAuth — this works from a human terminal or an agent’s shell tool. Use clay whoami as the canonical check that authentication is working, and clay logout to clear a stored credential.
Each sign-in covers one workspace — the one you pick on the consent screen. To work across several, run clay login once per workspace: signing into a second keeps the first. clay workspaces list shows what you are signed into, clay workspaces current shows which one commands run against, and clay workspaces switch <id> switches. Signing in makes the workspace just added the active one, so switch back explicitly if you were working in another. clay logout signs out of the active workspace and leaves the rest.
On machines where a local browser can’t open — SSH sessions, containers, headless machines — use clay login --device instead. It prints a link and a short code; open the link in a browser on any device to approve the sign-in, and the CLI completes automatically. Run clay login --help for details.