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

> Save a Clay API key to the local config file.

Save an API key to the config file. The key is required for all authenticated commands. Use `--stdin` when an agent provides the key or when you want to pipe it yourself; otherwise the command prompts for the key on a TTY.

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

The key is validated against Clay before it is persisted — if validation fails, the config file is not written. The key is stored under the `default` profile; any other profiles already present in the file are preserved.

## Flags

| Flag      | Description                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `--stdin` | Read the API key from standard input as a single line. Useful for agents 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                                                                                  |
| ------------------ | ---- | -------------------------------------------------------------------------------------- |
| `tty_required`     | 2    | Ran without `--stdin` in a non-interactive environment. Pipe the key on stdin instead. |
| `validation_error` | 2    | Input was empty after trimming.                                                        |
| `auth_invalid`     | 3    | Clay rejected the key during the pre-write probe. Nothing was written.                 |
| `aborted`          | 1    | Interactive prompt was cancelled (Ctrl-C, Esc).                                        |

## Examples

Non-interactive, preferred for agents:

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

Interactive, masked TTY prompt:

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