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 ~/.config/kagi-cli/config.toml, and validates the selected credential immediately. Auth command demo

​
Synopsis

​
Interactive Wizard

Run this on a TTY:
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:
The wizard points you to:
It accepts either:
  • the full Session Link URL
  • the raw token value

​
API Key Path

The wizard points you to:
It accepts:
  • the raw API key

​
Legacy API Token Path

The wizard points you to:
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:
That keeps CI, shell scripts, and other automation explicit.

​
Subcommands

​
kagi auth status

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

​
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:

​
kagi auth set

Use this when you want scripting or explicit non-interactive config writes.
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):

​
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

​
Non-Interactive Session Setup

​
Add API Credentials Later

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

​
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