login

Sign in to Clay, saving credentials to the local config file.

Sign in to Clay. By default this opens a browser to authorize the CLI (no TTY required — works the same from a human terminal or an AI agent’s shell). The sign-in link is also printed to stderr in case the browser can’t open. Use --stdin in headless contexts (CI) to read an API key from standard input instead; CLAY_API_KEY also works without logging in.

clay login [--stdin]

The credential is validated before being persisted, under the default profile; other profiles are preserved. Running the browser flow again replaces the stored credential — that’s also how to switch workspaces, since the consent screen picks the workspace.

The browser flow waits up to 5 minutes for sign-in. An agent with a shorter shell-tool timeout should background the call and poll clay whoami instead. It also prints its sign-in link to stderr before any eventual JSON error, so a caller needing stderr to be pure parseable JSON should use --stdin instead.

Flags

Flag	Description
--stdin	Read the API key from standard input as a single line instead of opening a browser. Useful for CI and for keeping the key out of shell history.

Output

{
  "ok": true,
  "configPath": "/Users/you/.config/clay/config.json"
}

Field	Type	Description
ok	true	Always true on success.
configPath	string	Absolute path to the config file that was written (0600).

Errors

Code	Exit	Notes
validation_error	2	The --stdin key was empty or contained invalid characters.
auth_invalid	3	Clay rejected the credential — during the OAuth token exchange, or the --stdin key’s pre-write probe. Nothing was written.
auth_forbidden	3	The browser sign-in was denied before a credential was issued.
oauth_login_failed	1	The browser sign-in did not complete (cancelled, timed out, or could not start).
conflict	1	Already signed in via clay login; run clay logout before login --stdin.

Examples

Default, works from a human terminal or an AI agent’s shell:

clay login

Non-interactive, for CI and other headless contexts with no browser or human available:

echo "$CLAY_API_KEY" | clay login --stdin