> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay login
```

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
echo "$CLAY_API_KEY" | clay login --stdin
```