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

# auth

> Reference for the kagi auth wizard and non-interactive credential subcommands.

# `kagi auth`

`kagi auth` is the main onboarding path for this CLI. On a real terminal, it launches an interactive setup wizard that lets you choose `Session Link`, `API Key`, or `Legacy API Token`, shows the official Kagi settings page for that credential, accepts a paste, saves into `~/.config/kagi-cli/config.toml`, and validates the selected credential immediately.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/kagi-cli/images/demos/auth.gif" alt="Auth command demo" />

## Synopsis

```bash theme={null}
kagi auth
kagi auth status
kagi auth check
kagi auth set [OPTIONS]
```

## Interactive Wizard

Run this on a TTY:

```bash theme={null}
kagi auth
```

The wizard flow is:

1. shows your current auth state and config path
2. lets you choose `Session Link`, `API Key`, or `Legacy API Token`
3. shows the official place to get that credential
4. accepts the pasted value
5. asks before overwriting an existing config value of the same type
6. validates the selected credential
7. saves to `~/.config/kagi-cli/config.toml`
8. warns if an environment variable will still override what you saved
9. optionally offers to install `kagi mcp` into one or more AI agents

The MCP install offer is skipped outside a real terminal. To run it later:

```bash theme={null}
kagi mcp install
kagi mcp install --target codex --target cursor
```

### Session Link Path

The wizard points you to:

```text theme={null}
https://kagi.com/settings/user_details
```

It accepts either:

* the full Session Link URL
* the raw token value

### API Key Path

The wizard points you to:

```text theme={null}
https://kagi.com/api/keys
```

It accepts:

* the raw API key

### Legacy API Token Path

The wizard points you to:

```text theme={null}
https://kagi.com/settings/api
```

It accepts:

* the raw legacy API token

### Non-TTY Behavior

Bare `kagi auth` is intentionally interactive. In non-interactive environments it fails fast instead of hanging:

```text theme={null}
configuration error: `kagi auth` needs an interactive terminal. Use `kagi auth set`, `kagi auth status`, or `kagi auth check` in non-interactive environments
```

That keeps CI, shell scripts, and other automation explicit.

## Subcommands

| Subcommand | Purpose                                                        |
| ---------- | -------------------------------------------------------------- |
| `status`   | Show which credentials are configured and where they come from |
| `check`    | Validate the currently selected primary credential             |
| `set`      | Save credentials non-interactively                             |

## `kagi auth status`

```bash theme={null}
kagi auth status
```

This is read-only. It does not make a network request and it never prints secret values.

Example:

```text theme={null}
selected: session-token (config)
profile: default
preferred auth for base search: session
api key: not configured
legacy api token: not configured
session token: configured via config
config path: ~/.config/kagi-cli/config.toml
precedence: env > selected profile config > default config; base search defaults to session unless preferred_auth = "api"; lens search requires session token
```

## `kagi auth check`

```bash theme={null}
kagi auth check
```

This validates the selected primary credential only. It does not use base-search fallback behavior. That matters when both auth methods exist and you want to know which one is actually being tested.

Examples:

```text theme={null}
auth check passed: session-token (config)
```

```text theme={null}
auth check passed: api-token (env)
```

```text theme={null}
auth check passed: api-key (env)
```

## `kagi auth set`

Use this when you want scripting or explicit non-interactive config writes.

```bash theme={null}
kagi auth set --session-token 'https://kagi.com/search?token=...'
kagi auth set --api-key '...'
kagi auth set --api-token '...'
kagi auth set --session-token 'https://kagi.com/search?token=...' --api-key '...' --api-token '...'
kagi --profile work auth set --session-token 'https://kagi.com/search?token=...'
```

Options:

* `--session-token <TOKEN_OR_URL>` saves a Session Link or raw session token
* `--api-key <KEY>` saves a current API key for `/api/v1` endpoints
* `--api-token <TOKEN>` saves a legacy API token for `/api/v0` endpoints

Behavior:

* creates `~/.config/kagi-cli/config.toml` when needed
* preserves the other credential if you only set one
* normalizes full Session Link URLs into the raw token value
* writes the config file with restrictive permissions on Unix

## Precedence Rules

The CLI resolves credentials in this order:

1. `KAGI_API_KEY` / `KAGI_API_TOKEN` / `KAGI_SESSION_TOKEN`
2. selected profile config, such as `[profiles.work.auth]`
3. default `~/.config/kagi-cli/config.toml` `[auth]`

The config file is resolved from `$KAGI_CONFIG` (an explicit full path), then `$XDG_CONFIG_HOME/kagi-cli/config.toml`, then `~/.config/kagi-cli/config.toml`. Environment variables override the config file. Use `--profile <NAME>` to select a named profile from the config file (`~/.config/kagi-cli/config.toml`):

```toml theme={null}
[profiles.work.auth]
session_token = "work-session"
api_key = "work-api-key"
api_token = "work-legacy-api-token"
preferred_auth = "session"
```

## Preferred Auth

When both auth methods exist, base `kagi search` follows `[auth.preferred_auth]`:

* `"session"` - default
* `"api"`

The wizard only asks about this when both methods exist after the save and the selected method would change the current preference.

## Common Flows

### Fastest Subscriber Setup

```bash theme={null}
kagi auth
kagi auth check
kagi search --format pretty "rust programming language"
```

### Non-Interactive Session Setup

```bash theme={null}
kagi auth set --session-token 'https://kagi.com/search?token=...'
kagi auth check
```

### Add API Credentials Later

```bash theme={null}
kagi auth
```

Choose `API Key` for current Search API or Extract access. Choose `Legacy API Token` for FastGPT, public Summarizer, or Enrich.

```bash theme={null}
kagi auth status
kagi search --format pretty "what changed in rust 1.86?"
```

## Security Notes

* `auth status` and `auth check` never print the secret values
* `~/.config/kagi-cli/config.toml` is local plaintext config, so keep it out of version control
* on Unix, the CLI writes restrictive file permissions when saving the config
* environment variables still override config and may be preferable in CI/CD

## Related Pages

* [Authentication Guide](/guides/authentication)
* [Auth Matrix](/reference/auth-matrix)
* [Troubleshooting](/guides/troubleshooting)