Skip to main content

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.

​
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 or 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 or 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 Token Path

The wizard points you to: 
https://kagi.com/settings/api
It accepts:
  • the raw 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)
preferred auth for base search: session
api token: not configured
session token: configured via config
config path: .kagi.toml
precedence: env > config; base search defaults to session unless [auth.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)

​
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-token '...'
kagi auth set --session-token 'https://kagi.com/search?token=...' --api-token '...'
Options:
  • --session-token <TOKEN_OR_URL> saves a Session Link or raw session token
  • --api-token <TOKEN> saves a raw API token
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_TOKEN / KAGI_SESSION_TOKEN
  2. ./.kagi.toml
Environment variables override the config file. The wizard calls this out after save when it detects that the matching env var is already set.

​
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 Token Later

kagi auth
Choose API Token, paste it, then verify: 
kagi auth status
kagi fastgpt "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