Skip to main content

​
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 ./.kagi.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:
  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 ./.kagi.toml
  8. warns if an environment variable will still override what you saved
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 is interactive on TTYs; 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

SubcommandPurpose
statusShow which credentials are configured and where they come from
checkValidate the currently selected primary credential
setSave 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: .kagi.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 ./.kagi.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 ./.kagi.toml [auth]
Environment variables override the config file. Use --profile <NAME> to select a named profile from .kagi.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
  • ./.kagi.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