kagi-cli

Overview

kagi-cli is a terminal CLI that provides command-line access to Kagi search, Quick Answer, AI Assistant, translation, summarization, public feeds through news and smallweb, and account-level search settings like lenses, custom assistants, custom bangs, and redirects. It outputs JSON by default for scripting and automation, with --format pretty for human-readable terminal output on the commands that support alternate renderers.

The CLI prioritizes the subscriber session-token path, so existing Kagi subscribers can use most features without paying for API access. Current /api/v1 Search and Extract features use KAGI_API_KEY; legacy paid API features (summarize, fastgpt, enrich) use KAGI_API_TOKEN.

Installation

# Homebrew (macOS/Linux)
brew tap Microck/kagi
brew install kagi

# Scoop (Windows)
scoop bucket add kagi https://github.com/Microck/scoop-kagi
scoop install kagi

# npm (cross-platform)
npm install -g kagi-cli

# Direct install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.sh | sh

# Direct install (Windows PowerShell)
irm https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.ps1 | iex

Authentication

Interactive Setup (Recommended)

kagi auth

Opens a guided TTY wizard that walks through:

• Choosing Session Link, API Key, or Legacy API Token
• Pasting credentials
• Saving to ~/.config/kagi-cli/config.toml
• Immediate validation

Non-Interactive Setup

# Session token (from https://kagi.com/settings/user_details)
kagi auth set --session-token 'https://kagi.com/search?token=...'

# Or via environment variable
export KAGI_SESSION_TOKEN='...'

# API key for current /api/v1 endpoints (from https://kagi.com/api/keys)
export KAGI_API_KEY='...'

# Legacy API token for /api/v0 endpoints (from https://kagi.com/settings/api)
export KAGI_API_TOKEN='...'

Auth Model

Environment variables override ~/.config/kagi-cli/config.toml. When a session token and API key are both present, base kagi search defaults to the session token; set [auth] preferred_auth = "api" in config to prefer the API key.

Commands

kagi search

Search Kagi with JSON output by default.

# Basic search
kagi search "query"

# Pretty terminal output
kagi search --format pretty "query"

# Search with lens
kagi search --lens 2 "query"

# News-tab search (returns clusters of articles, session-only)
kagi search --news "iran"

# Filtered search
kagi search --time month --region us --order recency "rust release notes"

# Date-bounded search
kagi search --from-date 2026-03-01 --to-date 2026-03-31 "rust release notes"

# Limit results (truncated locally)
kagi search --limit 5 "rust release notes"

# Per-request personalization override
kagi search --no-personalized "rust release notes"

# Output formats: json (default), toon, pretty, compact, markdown, csv
kagi search --format markdown "query" > results.md

kagi quick

Get a direct answer with references instead of a list of results.

# Quick answer with pretty output
kagi quick --format pretty "what is rust"

# JSON for scripting
kagi quick "capital of japan" | jq -r '.message.markdown'

# Markdown for documentation
kagi quick --format markdown "explain async/await" > notes.md

Output includes the answer, structured references, and follow-up questions.

kagi translate

Translate text through Kagi Translate with language detection and extras.

# Auto-detect source, translate to English (default)
kagi translate "Bonjour tout le monde"

# Translate to specific target
kagi translate "Hello world" --to es

# Translation output is always JSON
kagi translate "Good morning" --to de | jq -r '.translation.translation'

# Skip extras for faster response
kagi translate "text" --to ja --no-alternatives --no-word-insights

Includes alternatives, word insights, alignments, and suggestions by default.

kagi batch

Run multiple searches in parallel with rate limiting.

# Parallel searches
kagi batch "rust async" "python tutorial" "go concurrency"

# With output format
kagi batch "query1" "query2" --format compact

# CSV for spreadsheet analysis
kagi batch "product A review" "product B review" --format csv > comparison.csv

kagi assistant

Prompt Kagi Assistant and manage conversation threads.

# Start conversation
kagi assistant "Explain quantum computing"

# Continue existing thread
kagi assistant --thread-id "<thread-id>" "Give me an example"

# Use a saved assistant profile with prompt overrides
kagi assistant --assistant research --model gpt-5-4-nano --web-access --no-personalized "Summarize the latest Rust release"

# Stream markdown deltas as they arrive
kagi assistant --stream "Explain quantum computing"

# Stream structured events for scripts
kagi assistant --stream --stream-output json "Explain quantum computing"

# List threads
kagi assistant thread list

# Get one thread as JSON
kagi assistant thread get "<thread-id>"
kagi assistant thread get "https://assistant.kagi.com/chat/<thread-id>"

# Export thread
kagi assistant thread export "<thread-id>" --format markdown > thread.md

# Delete thread
kagi assistant thread delete "<thread-id>"

kagi assistant custom

Manage saved assistant profiles.

# List built-in and custom assistants
kagi assistant custom list

# Inspect one assistant by id or exact name
kagi assistant custom get "Release Notes"

# Create a custom assistant
kagi assistant custom create "Release Notes" --model gpt-5-4-nano --web-access --lens 2 --instructions "Focus on release diffs and migrations."

# Update an existing custom assistant
kagi assistant custom update "Release Notes" --bang-trigger relnotes --no-personalized

# Delete a custom assistant
kagi assistant custom delete "Release Notes"

kagi ask-page

Ask the Assistant about a specific web page.

kagi ask-page https://example.com/article "What are the main points?"

kagi summarize

Summarize URLs or text using Kagi's summarizer.

# Subscriber summarizer (free with subscription)
kagi summarize --subscriber --url https://example.com

# With options
kagi summarize --subscriber --url "$URL" --summary-type keypoints --length digest

# Paid API summarizer
kagi summarize --url https://example.com --engine cecil

kagi news

Fetch Kagi News (public, no auth required), optionally with local content filters.

# Tech news
kagi news --category tech --limit 5

# JSON output
kagi news --category world | jq '.stories[0].title'

# List built-in content-filter presets
kagi news --list-filter-presets

# Hide stories that match the politics preset
kagi news --filter-preset politics

# Keep matching stories in output, but tag them for downstream tools
kagi news --filter-preset politics --filter-mode blur

kagi smallweb

Fetch the Kagi Small Web feed (public, no auth required).

kagi smallweb --limit 10

kagi fastgpt

Quick factual answers through the paid API.

kagi fastgpt "what changed in rust 1.86?"

kagi enrich

Query Kagi's enrichment indexes (paid API).

kagi enrich web "local-first software"
kagi enrich news "browser privacy"

kagi lens

Manage Kagi search lenses.

kagi lens list
kagi lens get "Default"
kagi lens create "Rust Docs" --included-sites rust-lang.org,docs.rs --shortcut rustdocs
kagi lens update "Rust Docs" --description "Rust docs only" --region us
kagi lens enable "Rust Docs"
kagi lens disable "Rust Docs"
kagi lens delete "Rust Docs"

kagi bang custom

Manage custom bangs.

kagi bang custom list
kagi bang custom get docs
kagi bang custom create "Docs" --trigger docs --template "https://docs.rs/releases/search?query=%s"
kagi bang custom update docs --shortcut-menu
kagi bang custom delete docs

kagi redirect

Manage redirect rules.

kagi redirect list
kagi redirect get '^https://old.example.com/(.*)|https://new.example.com/$1'
kagi redirect create '^https://old.example.com/(.*)|https://new.example.com/$1'
kagi redirect update '^https://old.example.com/(.*)|https://new.example.com/$1' '^https://old.example.com/(.*)|https://docs.example.com/$1'
kagi redirect enable '^https://old.example.com/(.*)|https://docs.example.com/$1'
kagi redirect disable '^https://old.example.com/(.*)|https://new.example.com/$1'
kagi redirect delete '^https://old.example.com/(.*)|https://docs.example.com/$1'

Output Formats

search and batch support json, pretty, compact, markdown, and csv. quick and assistant support json, pretty, compact, and markdown. Commands like translate, news, smallweb, fastgpt, enrich, ask-page, and summarize emit JSON only.

kagi search "query" --format json | jq '.'
kagi search "query" --format pretty
kagi search "query" --format markdown > results.md
kagi search "query" --format csv > results.csv

Shell Completions

Install completions for the detected shell:

kagi completion install
kagi completion install --shell fish

Generate completion scripts for Bash, Zsh, Fish, and PowerShell:

# Bash
kagi completion generate bash > ~/.local/share/bash-completion/completions/kagi

# Zsh
kagi completion generate zsh > ~/.zsh/completions/_kagi

# Fish
kagi completion generate fish > ~/.config/fish/completions/kagi.fish

# PowerShell
kagi completion generate powershell >> $PROFILE

Common Workflows

Research Pipeline

# Quick overview
kagi quick --format pretty "topic overview"

# Deep search with filters
kagi search --time month --format pretty "topic research"

# Batch related searches
kagi batch "topic history" "topic applications" "topic future" --format compact

# Ask assistant about findings
kagi assistant "Summarize what I found about topic"

Daily News Briefing

kagi news --category tech --limit 5

Content Analysis

# Summarize an article
kagi summarize --subscriber --url "$URL" --summary-type keypoints

# Ask about a page
kagi ask-page "$URL" "What is the author's main argument?"

Translation Workflow

# Quick translation
kagi translate "text" --to es

# Full analysis
kagi translate "text" --to de | jq '{
  translation: .translation.translation,
  alternatives: .alternatives.elements[0:3],
  insights: .word_insights.insights[0:5]
}'

Assistant Thread Management

# Start research thread
kagi assistant "Help me understand X" > thread.json
THREAD_ID=$(cat thread.json | jq -r '.thread.id')

# Continue later
kagi assistant --thread-id "$THREAD_ID" "Now explain Y"

# Export for documentation
kagi assistant thread export "$THREAD_ID" --format markdown > research.md

Batch Research

# Compare multiple topics
kagi batch "rust vs go" "python vs ruby" "react vs vue" --format pretty

# Save as CSV
kagi batch "topic1" "topic2" "topic3" --format csv > comparison.csv

Input Requirements

• Search queries: Text strings; optionally with --lens, --time, --region, --order filters
• Quick queries: Natural language questions
• Translate text: Text string; optionally --from and --to language codes
• URLs: Valid HTTP/HTTPS URLs for summarize and ask-page
• Thread IDs: Alphanumeric strings from assistant responses
• Categories: News categories: world, usa, tech, science, business, etc.

Constraints

• Session token required for: search --lens, search --news, quick, ask-page, assistant, translate, summarize --subscriber
• API token required for: summarize (public API), fastgpt, enrich
• Rate limits apply based on Kagi subscription tier
• API usage has per-query costs; session-based features included with subscription
• Translation requires session token

Error Handling

Resources

• Documentation: https://kagi.micr.dev
• GitHub: https://github.com/Microck/kagi-cli
• npm: https://www.npmjs.com/package/kagi-cli
• Kagi: https://kagi.com
• Auth Matrix: https://kagi.micr.dev/reference/auth-matrix