> ## 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.

# Quickstart

> Get up and running with *kagi* CLI in minutes - from your first unauthenticated command to full subscriber workflows.

# 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

```bash theme={null}
kagi news --category world --limit 3
```

**Demo:**

<img src="https://mintcdn.com/kagi-cli/azau7DEucCKj5AfG/images/demos/news.gif?s=6ab088d39fbebddb91d137c74ef19229" alt="News command demo" width="789" height="450" data-path="images/demos/news.gif" />

**Expected output:**

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

### Test 2: Small Web Feed

```bash theme={null}
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](/guides/troubleshooting) guide.

## Step 2: Verify Installation (1 minute)

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

```bash theme={null}
# 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

1. **Log into Kagi** in your web browser
2. **Open** [Session Link settings](https://kagi.com/settings/user_details)
3. **Find "Session Link"**
4. **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:

```bash theme={null}
kagi auth
```

Choose `Session Link`, paste the full Session Link or raw token, and let the wizard save and validate it.

**Auth Demo:**

<img src="https://mintlify.s3.us-west-1.amazonaws.com/kagi-cli/images/demos/auth.gif" alt="Auth command demo" />

### Option B: Environment Variable (Quick Testing)

For immediate testing without saving to disk:

```bash theme={null}
export KAGI_SESSION_TOKEN='https://kagi.com/search?token=YOUR_TOKEN_HERE'
```

**Verify it works:**

```bash theme={null}
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:

```bash theme={null}
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:**

```bash theme={null}
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:

```bash theme={null}
# 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:**

<img src="https://mintcdn.com/kagi-cli/azau7DEucCKj5AfG/images/demos/search.gif?s=87cd0cfe70ef1b3f7e9339d9f7bfebde" alt="Search command demo" width="789" height="450" data-path="images/demos/search.gif" />

```bash theme={null}
# 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:**

<img src="https://mintlify.s3.us-west-1.amazonaws.com/kagi-cli/images/demos/quick.gif" alt="Quick command demo" />

**Assistant Demo:**

<img src="https://mintcdn.com/kagi-cli/azau7DEucCKj5AfG/images/demos/assistant.gif?s=08a6827e9693b26fa9086aeca1fadb66" alt="Assistant command demo" width="789" height="450" data-path="images/demos/assistant.gif" />

**Ask Page Demo:**

<img src="https://mintlify.s3.us-west-1.amazonaws.com/kagi-cli/images/demos/ask-page.gif" alt="Ask Page command demo" />

**Translate Demo:**

<img src="https://mintlify.s3.us-west-1.amazonaws.com/kagi-cli/images/demos/translate.gif" alt="Translate command demo" />

**Subscriber Summarize Demo:**

<img src="https://mintcdn.com/kagi-cli/azau7DEucCKj5AfG/images/demos/summarize.gif?s=c5e3f37edad76390c4e6eaf04ea4619d" alt="Summarize command demo" width="789" height="450" data-path="images/demos/summarize.gif" />

## 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

1. **Log into Kagi** in your web browser
2. **Open** [API keys](https://kagi.com/api/keys)
3. **Generate a new API key** if you don't have one
4. **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**

```bash theme={null}
kagi auth
```

Choose `API Key`, paste it, and let the wizard add it alongside your existing Session Link.

**Option B: Environment Variable**

```bash theme={null}
export KAGI_API_KEY='your_api_key_here'
```

**Option C: Persistent Configuration**

```bash theme={null}
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

```bash theme={null}
# 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](/reference/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:**

```toml theme={null}
[auth]
api_token = "your_api_token_here"
session_token = "your_session_token_here"
```

**Creating the file manually:**

```bash theme={null}
# 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):

1. **Environment variables** (`KAGI_API_KEY`, `KAGI_API_TOKEN`, `KAGI_SESSION_TOKEN`)
2. **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):**

```bash theme={null}
# Kagi CLI
export KAGI_SESSION_TOKEN='your_session_token'
export KAGI_API_TOKEN='your_api_token'
```

**Zsh (\~/.zshrc):**

```bash theme={null}
# Kagi CLI
export KAGI_SESSION_TOKEN='your_session_token'
export KAGI_API_TOKEN='your_api_token'
```

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

```fish theme={null}
# Kagi CLI
set -x KAGI_SESSION_TOKEN 'your_session_token'
set -x KAGI_API_TOKEN 'your_api_token'
```

**PowerShell (\$PROFILE):**

```powershell theme={null}
# Kagi CLI
$env:KAGI_SESSION_TOKEN = 'your_session_token'
$env:KAGI_API_TOKEN = 'your_api_token'
```

### Security Best Practices

1. **File permissions**: Set `~/.config/kagi-cli/config.toml` to 600 (readable only by you)
2. **Environment variables**: Don't commit these to version control
3. **Token rotation**: Regenerate tokens periodically
4. **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

```bash theme={null}
#!/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:

```bash theme={null}
chmod +x ~/bin/news-brief.sh
~/bin/news-brief.sh
```

### Workflow 2: Research Assistant

```bash theme={null}
# 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

```bash theme={null}
#!/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

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/guides/authentication)** - Understand the complete auth system
* **[Common Workflows](/guides/workflows)** - More real-world patterns
* **[Command Reference](/commands/search)** - Complete command documentation
* **[Advanced Usage](/guides/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](/guides/troubleshooting) guide.

***

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