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

Auth command demo

Synopsis

kagi auth
kagi auth status
kagi auth check
kagi auth set [OPTIONS]

Interactive Wizard

Run this on a TTY:

kagi auth

The wizard flow is:

shows your current auth state and config path
lets you choose Session Link, API Key, or Legacy API Token
shows the official place to get that credential
accepts the pasted value
asks before overwriting an existing config value of the same type
validates the selected credential
saves to ~/.config/kagi-cli/config.toml
warns if an environment variable will still override what you saved
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:

kagi mcp install
kagi mcp install --target codex --target cursor

Session Link Path

The wizard points you to:

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:

https://kagi.com/api/keys

It accepts:

the raw API key

Legacy API Token Path

The wizard points you to:

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:

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`

kagi auth status

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

Example:

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`

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:

auth check passed: session-token (config)

auth check passed: api-token (env)

auth check passed: api-key (env)

`kagi auth set`

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

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:

KAGI_API_KEY / KAGI_API_TOKEN / KAGI_SESSION_TOKEN
selected profile config, such as [profiles.work.auth]
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):

[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

kagi auth
kagi auth check
kagi search --format pretty "rust programming language"

Non-Interactive Session Setup

kagi auth set --session-token 'https://kagi.com/search?token=...'
kagi auth check

Add API Credentials Later

kagi auth

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

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

On this page