Authentication Matrix

This reference provides a complete mapping of which commands require which authentication tokens, including fallback behavior and special cases.

Command Overview

Detailed Breakdown

Search Commands

Base Search (kagi search)

Key insight: Base search is the only command with fallback behavior, and that fallback only matters when you explicitly opt into API-first mode.

Lens Search (kagi search --lens <INDEX>)

No fallback: Lens search requires session token exclusively.

Search Filters and Session-Only Options

--region, --from-date, and --to-date map to the current V1 Search API filters object. --lens, --time, --order, --verbatim, and personalization flags remain session-only because they target the subscriber web-product flow exposed by this CLI.

Authentication Commands

kagi auth

• Purpose: Interactive setup wizard
• Network: Yes, during credential validation
• Uses: The credential the user just pasted
• Writes: ~/.config/kagi-cli/config.toml
• TTY only: In non-interactive environments, use auth set, status, or check

kagi auth status

• Purpose: Display current configuration
• Network: No
• Reads: Environment variables, config file
• Output: Shows which tokens are configured and their sources

kagi auth check

• Purpose: Validate the selected primary credential works
• Network: Yes; endpoint depends on credential: API key and session token run a test search, legacy API token validates against the FastGPT endpoint
• Uses: Primary credential per [auth.preferred_auth] setting (defaults to session token)
• No fallback: Tests primary credential only

kagi auth set

• Purpose: Save credentials to file
• Network: No
• Writes: ~/.config/kagi-cli/config.toml
• Creates: Config file if doesn't exist

Content Commands

Summarization

Important: These are mutually exclusive. You cannot use --subscriber with API-only options like --engine.

AI Commands

Settings Commands

Data Commands

Enrichment

Both enrich web and enrich news require legacy KAGI_API_TOKEN:

• Teclis (web) - Enhanced web search
• TinyGem (news) - Enhanced news search

Feed Commands

Public Feeds (No Auth Required)

Token Requirements by Feature

Session Token Features

Requires KAGI_SESSION_TOKEN:

• ✅ Lens-aware search (--lens)
• ✅ Quick Answer (quick)
• ✅ Session-only search options (--lens, --time, --order, --verbatim, personalization flags)
• ✅ Kagi Assistant prompt and thread commands (assistant)
• ✅ Custom assistant management (assistant custom)
• ✅ Ask Page (ask-page)
• ✅ Lens management (lens)
• ✅ Custom bang management (bang custom)
• ✅ Redirect management (redirect)
• ✅ Kagi Translate (translate)
• ✅ Subscriber Summarizer (summarize --subscriber)
• ✅ Base search (fallback)

API Key Features

Requires KAGI_API_KEY:

• ✅ Current Search API (search when [auth.preferred_auth] = "api")
• ✅ Extract API (extract)

Legacy API Token Features

Requires KAGI_API_TOKEN:

• ✅ FastGPT (fastgpt)
• ✅ Public Summarizer (summarize)
• ✅ Web Enrichment (enrich web)
• ✅ News Enrichment (enrich news)

No Token Required

Works without authentication:

• ✅ Kagi News (news)
• ✅ Small Web (smallweb)
• ✅ Auth status (auth status)

Configuration Precedence

Resolution Order

1. Environment Variables (KAGI_API_KEY, KAGI_API_TOKEN, KAGI_SESSION_TOKEN)
   ↓ (if not set)
2. Configuration File (`~/.config/kagi-cli/config.toml`)
   ↓ (if not set)
3. Missing (error for commands requiring 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.

Example Scenarios

Scenario 1: Multiple credentials in file

# ~/.config/kagi-cli/config.toml
[auth]
api_token = "api123"
api_key = "key123"
session_token = "session456"

• search: Uses the configured base-search preference (session by default)
• assistant: Uses session token
• assistant custom: Uses session token
• lens: Uses session token
• news: No token needed

Scenario 2: Mixed sources

export KAGI_API_KEY="key789"
# ~/.config/kagi-cli/config.toml has session_token only

• search: Uses env API key when [auth.preferred_auth] = "api"
• summarize --subscriber: Uses file session token
• fastgpt: Requires KAGI_API_TOKEN or [auth].api_token

Scenario 3: Environment overrides file

export KAGI_SESSION_TOKEN="special_session"
# ~/.config/kagi-cli/config.toml has different session_token

• search: Uses env session token (not API, so tries web)
• assistant: Uses env session token
• redirect: Uses env session token

Common Configurations

Session Token Only

Setup:

kagi auth
# choose "Session Link" and paste your link; the token never lands in
# shell history or the process list

Working commands:

• ✅ kagi search "query" (uses session path)
• ✅ kagi search --lens 2 "query"
• ✅ kagi quick "what is rust"
• ✅ kagi search --region us --time month "query"
• ✅ kagi ask-page https://example.com "question"
• ✅ kagi assistant "prompt"
• ✅ kagi assistant custom list
• ✅ kagi lens list
• ✅ kagi bang custom list
• ✅ kagi redirect list
• ✅ kagi translate "Bonjour tout le monde"
• ✅ kagi summarize --subscriber --url ...
• ✅ kagi news
• ✅ kagi smallweb

Non-working:

• ❌ kagi fastgpt - requires API token
• ❌ kagi summarize --url ... (without --subscriber) - requires API token
• ❌ kagi enrich web - requires API token
• ❌ kagi extract - requires API key

Legacy API Token Only

Setup:

kagi auth
# choose "Legacy API Token" and paste the value interactively

Working commands:

• ✅ kagi summarize --url ...
• ✅ kagi fastgpt "query"
• ✅ kagi enrich web "query"
• ✅ kagi news
• ✅ kagi smallweb

Non-working:

• ❌ kagi search "query" with [auth.preferred_auth] = "api" - requires API key or session token
• ❌ kagi search --lens 2 - requires session token
• ❌ kagi quick - requires session token
• ❌ kagi search --region us "query" - requires session token
• ❌ kagi ask-page https://example.com "question" - requires session token
• ❌ kagi quick - requires session token
• ❌ kagi assistant - requires session token
• ❌ kagi assistant custom list - requires session token
• ❌ kagi lens list - requires session token
• ❌ kagi bang custom list - requires session token
• ❌ kagi redirect list - requires session token
• ❌ kagi summarize --subscriber - requires session token
• ❌ kagi extract - requires API key

Session Token, API Key, and Legacy API Token

Setup:

kagi auth
# run the wizard once per credential, choosing Session Link, API Key,
# then Legacy API Token; each paste is saved immediately

All search, AI, and feed commands work. Mail requires separate OAuth login:

• ✅ Everything listed above

Smart behavior:

• search: Uses session (default), or API key if [auth.preferred_auth = "api"] is set
• extract: Uses API key directly
• summarize without --subscriber: Uses legacy API token
• summarize --subscriber: Uses session
• quick: Uses session
• ask-page: Uses session
• assistant: Uses session
• assistant custom: Uses session
• lens: Uses session
• bang custom: Uses session
• redirect: Uses session
• fastgpt: Uses legacy API token

Troubleshooting Matrix

Security Considerations

Token Storage

• Environment variables: Process-wide, may leak to subprocesses
• Config file: Stored on disk, should be 600 permissions
• Shell history: May contain export commands

Recommendation: Use config file for persistence, environment variables for overrides.

Scope of Access

• Session Token: Full subscriber access (search, assistant, summarizer)
• API Key: Current /api/v1 API-only access (search, extract)
• Legacy API Token: Older /api/v0 API-only access (fastgpt, enrich, public summarizer)

Principle: Use least-privilege tokens for specific workflows.

Migration Scenarios

Adding a legacy API token to an existing Session setup

kagi auth
# already have a session token saved: choose "Legacy API Token" and paste it

# Now fastgpt works
kagi fastgpt "question"

Adding Session to existing API setup

kagi auth
# choose "Session Link" and paste your session link

# Now assistant works
kagi assistant "prompt"

Reference Tables

Quick Reference

Error to Action Mapping