Quickstart Guide

This guide follows a progressive disclosure approach: you’ll start with commands that work immediately without any setup, then gradually unlock more powerful features as you configure authentication. By the end, you’ll have a fully functional kagi CLI setup tailored to your needs.

Progression Overview

Step 1: Unauthenticated Commands (30 seconds)
    ↓
Step 2: Verify Installation (1 minute)
    ↓
Step 3: Subscriber Setup with Session Token (3 minutes)
    ↓
Step 4: Paid API Setup with API Key or Legacy API Token (optional)
    ↓
Step 5: Persistent Configuration (2 minutes)
    ↓
Step 6: First Real Workflows (5 minutes)

Step 1: Unauthenticated Commands (30 seconds)

The fastest way to verify kagi is working is to run commands that don’t require authentication. These use Kagi’s public endpoints.

Test 1: Kagi News

kagi news --category world --limit 3

Demo:

Expected output:

{
  "data": [
    {
      "title": "Example News Story",
      "url": "https://example.com/news/123",
      "snippet": "Summary of the news story..."
    }
  ]
}

Test 2: Small Web Feed

kagi smallweb --limit 3

This fetches the latest posts from Kagi’s Small Web curation.

What These Commands Prove

✅ Binary is installed and in PATH
✅ Network connectivity to Kagi works
✅ CLI can parse and output JSON
✅ You can run kagi successfully

If these commands work, your installation is successful. If not, see the Troubleshooting guide.

Step 2: Verify Installation (1 minute)

Before moving to authenticated commands, let’s verify the installation details:

# Check version
kagi --version

# View all available commands
kagi --help

# Check which credentials are configured (if any)
kagi auth status

At this stage, kagi auth status will likely show:

selected: none
api key: not configured
legacy api token: not configured
session token: not configured
config path: ~/.config/kagi-cli/config.toml

This is expected - we’ll configure credentials next.

Step 3: Subscriber Setup with Session Token

To unlock subscriber-only features (lens search, Quick Answer, Assistant, ask-page, translate, subscriber Summarizer, and account settings management), you need a Kagi Session Token.

Getting Your Session Token

Log into Kagi in your web browser
Open Session Link settings
Find “Session Link”
Copy the full URL (looks like https://kagi.com/search?token=abc123...)

Important: This token is tied to your Kagi account and subscription. Keep it secure.

Option A: Auth Wizard (Recommended)

Run:

kagi auth

Choose Session Link, paste the full Session Link or raw token, and let the wizard save and validate it. Auth Demo: Auth command demo

Option B: Environment Variable (Quick Testing)

For immediate testing without saving to disk:

export KAGI_SESSION_TOKEN='https://kagi.com/search?token=YOUR_TOKEN_HERE'

Verify it works:

kagi auth check

Expected output:

auth check passed: session-token (env)

Option C: Persistent Configuration Without the Wizard

Save the token to a config file:

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

This creates ~/.config/kagi-cli/config.toml with your token. The CLI accepts either:

The full Session Link URL (recommended)
Just the raw token value

Verify it works:

kagi auth status

Expected output:

selected: session-token (config)
api key: not configured
legacy api token: not configured
session token: configured via config
config path: ~/.config/kagi-cli/config.toml

Testing Subscriber Features

Now that you’re authenticated, test the subscriber commands:

# Basic search (uses session token)
kagi search --format pretty "rust programming language"

# Search with a lens (replace 2 with your lens index)
kagi search --lens 2 "developer documentation"

# Search with live session-only filters
kagi search --region us --time month --order recency "rust release notes"

# Reuse one of your Kagi snaps
kagi search --snap reddit "rust async runtime"

Search Demo:

# Test Quick Answer
kagi quick --format pretty "what is rust"

# Test Assistant
kagi assistant "What are the key features of Rust?"

# Test Translate
kagi translate "Bonjour tout le monde" --to ja

# Ask Assistant about a page
kagi ask-page https://rust-lang.org/ "What is this page about?"

# List Assistant threads
kagi assistant thread list

# Inspect account-level settings
kagi assistant custom list
kagi lens list
kagi bang custom list
kagi redirect list

# Test subscriber Summarizer
kagi summarize --subscriber --url https://www.rust-lang.org --summary-type keypoints --length digest

Quick Answer Demo: Quick command demo

Assistant Demo:

Ask Page Demo: Ask Page command demo

Translate Demo: Translate command demo

Subscriber Summarize Demo:

Step 4: Paid API Setup with API Key or Legacy API Token (Optional)

If you have Kagi API access (separate from your subscription), add an API key for current /api/v1 commands or a legacy API token for older /api/v0 commands.

Getting Your API Key

Log into Kagi in your web browser
Open API keys
Generate a new API key if you don’t have one
Copy the key (looks like a long alphanumeric string)

Note: API access requires available credit. Check your Kagi account for API credit balance.

Setting Up the API Key

Option A: Auth Wizard

kagi auth

Choose API Key, paste it, and let the wizard add it alongside your existing Session Link. Option B: Environment Variable

export KAGI_API_KEY='your_api_key_here'

Option C: Persistent Configuration

kagi auth set --api-key 'your_api_key_here'

Note: If you previously set a session token, this will add the API key alongside it. Both can coexist. Use --api-token only for legacy FastGPT, Summarizer, and Enrich commands.

Testing Paid API Commands

# Test API authentication
kagi auth check

# Test public Summarizer
kagi summarize --url https://example.com --engine cecil

# Test FastGPT
kagi fastgpt "Explain quantum computing"

# Test Enrichment
kagi enrich web "artificial intelligence"

Understanding Multi-Credential Setup

When you have multiple credentials configured:

Session Token: Enables lens search, session-only search options, Quick Answer, ask-page, assistant, translate, and subscriber Summarizer
API Key: Enables current Search API and Extract API
Legacy API Token: Enables FastGPT, public Summarizer, and Enrichment APIs
Base Search: Defaults to session unless [auth.preferred_auth] = "api"

See the Auth Matrix for the complete command-to-token mapping.

Step 5: Persistent Configuration

Now that you’ve tested everything, let’s create a robust configuration.

The config file

Kagi uses a TOML configuration file located at ~/.config/kagi-cli/config.toml. Basic configuration:

[auth]
api_token = "your_api_token_here"
session_token = "your_session_token_here"

Creating the file manually:

# Create the file
mkdir -p ~/.config/kagi-cli
cat > ~/.config/kagi-cli/config.toml << 'EOF'
[auth]
api_token = "your_api_token_here"
session_token = "your_session_token_here"
EOF

# Set secure permissions
chmod 600 ~/.config/kagi-cli/config.toml

Configuration Precedence

Kagi resolves credentials in this order (first match wins):

Environment variables (KAGI_API_KEY, KAGI_API_TOKEN, KAGI_SESSION_TOKEN)
Config file (~/.config/kagi-cli/config.toml)

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. This means you can override file configuration with environment variables for specific workflows or CI/CD.

Shell Profile Integration

For convenience, add environment variables to your shell profile: Bash (~/.bashrc):

# Kagi CLI
export KAGI_SESSION_TOKEN='your_session_token'
export KAGI_API_TOKEN='your_api_token'

Zsh (~/.zshrc):

# Kagi CLI
export KAGI_SESSION_TOKEN='your_session_token'
export KAGI_API_TOKEN='your_api_token'

Fish (~/.config/fish/config.fish):

# Kagi CLI
set -x KAGI_SESSION_TOKEN 'your_session_token'
set -x KAGI_API_TOKEN 'your_api_token'

PowerShell ($PROFILE):

# Kagi CLI
$env:KAGI_SESSION_TOKEN = 'your_session_token'
$env:KAGI_API_TOKEN = 'your_api_token'

Security Best Practices

File permissions: Set ~/.config/kagi-cli/config.toml to 600 (readable only by you)
Environment variables: Don’t commit these to version control
Token rotation: Regenerate tokens periodically
Separate contexts: Use different tokens for different environments (dev/staging/prod)

Step 6: First Real Workflows

Now let’s put it all together with practical workflows.

Workflow 1: Daily News Briefing

#!/bin/bash
# save as ~/bin/news-brief.sh

echo "=== Technology News ==="
kagi news --category tech --limit 5 | jq -r '.stories[] | "\(.title)\n  \(.articles[0].link)\n"'

echo "=== World News ==="
kagi news --category world --limit 5 | jq -r '.stories[] | "\(.title)\n  \(.articles[0].link)\n"'

Make it executable and run:

chmod +x ~/bin/news-brief.sh
~/bin/news-brief.sh

Workflow 2: Research Assistant

# Search for documentation
kagi search --lens 2 "error handling rust" --format pretty

# Summarize a relevant article
kagi summarize --subscriber --url https://doc.rust-lang.org/book/ch09-00-error-handling.html --summary-type keypoints

# Ask Assistant for clarification
kagi assistant "Explain the difference between Result and Option in Rust"

Workflow 3: Content Pipeline

#!/bin/bash
# Process a list of URLs and generate summaries

URLS=(
  "https://example.com/article1"
  "https://example.com/article2"
  "https://example.com/article3"
)

for url in "${URLS[@]}"; do
  echo "Processing: $url"
  kagi summarize --subscriber --url "$url" --length overview > "summary_$(basename $url).json"
done

Workflow 4: Development Research

# Quick answer without opening browser
kagi fastgpt "What are the new features in Python 3.12?"

# Deep research with web enrichment
kagi enrich web "Python 3.12 performance improvements"

# Search for specific implementation examples
kagi search "python 3.12 generic types examples" --format pretty

Common First Commands Reference

Here’s a quick reference of useful commands organized by category:

Information Commands

kagi --version              # Show version
kagi --help                 # Show all commands
kagi auth status            # Check credential status
kagi auth check             # Validate credentials
kagi news --list-categories # Show available news categories

Search Commands

kagi search "query"                      # JSON output
kagi search --format pretty "query"             # Human-readable
kagi search --lens 2 "query"             # With lens
kagi search --region us --time month "query"    # With live filters
kagi search --lens 2 --format pretty "query"    # Combined

Content Commands

kagi summarize --url https://example.com                    # Public API
kagi summarize --subscriber --url https://example.com       # Subscriber
kagi quick "what is rust"                                   # Quick Answer
kagi fastgpt "question"                                     # Quick answer
kagi assistant "prompt"                                     # AI assistant
kagi enrich web "query"                                     # Web enrichment
kagi enrich news "query"                                    # News enrichment

Feed Commands

kagi news --category tech --limit 5     # Tech news
kagi news --category world --limit 10   # World news
kagi smallweb --limit 20                # Small Web feed
kagi news --chaos                       # Chaos index

What You’ve Learned

By completing this quickstart, you now understand:

✅ How to verify installation works
✅ The difference between session and API tokens
✅ How to configure credentials (env vars and config file)
✅ Basic search and content commands
✅ How to combine commands in workflows
✅ Where to find help and documentation

Next Steps

Continue your kagi journey:

Authentication Deep Dive - Understand the complete auth system
Common Workflows - More real-world patterns
Command Reference - Complete command documentation
Advanced Usage - Scripting and automation

Troubleshooting Quick Reference

Problem	Solution
”command not found”	Check PATH, reload shell
”missing credentials”	Set KAGI_SESSION_TOKEN, KAGI_API_KEY, or KAGI_API_TOKEN depending on the command
”auth check failed”	Verify token is valid and not expired
Empty search results	Try different query or check rate limits
JSON parse errors	Verify kagi version, check for CLI updates

For detailed troubleshooting, see the Troubleshooting guide.

Congratulations! You’re now ready to use kagi CLI effectively. Happy searching!

​Quickstart Guide

​Progression Overview

​Step 1: Unauthenticated Commands (30 seconds)

​Test 1: Kagi News

​Test 2: Small Web Feed

​What These Commands Prove

​Step 2: Verify Installation (1 minute)

​Step 3: Subscriber Setup with Session Token

​Getting Your Session Token

​Option A: Auth Wizard (Recommended)

​Option B: Environment Variable (Quick Testing)

​Option C: Persistent Configuration Without the Wizard

​Testing Subscriber Features

​Step 4: Paid API Setup with API Key or Legacy API Token (Optional)

​Getting Your API Key

​Setting Up the API Key

​Testing Paid API Commands

​Understanding Multi-Credential Setup

​Step 5: Persistent Configuration

​The config file

​Configuration Precedence

​Shell Profile Integration

​Security Best Practices

​Step 6: First Real Workflows

​Workflow 1: Daily News Briefing

​Workflow 2: Research Assistant

​Workflow 3: Content Pipeline

​Workflow 4: Development Research

​Common First Commands Reference

​Information Commands

​Search Commands

​Content Commands

​Feed Commands

​What You’ve Learned

​Next Steps

​Troubleshooting Quick Reference