github.com/Microck/kagi-cli @v0.14.1

<img src="https://github.com/Microck/kagi-cli/raw/v0.14.1/github/assets/kagi-cli-logo-light.svg" alt="kagi cli" width="720">

---

kagi is a terminal CLI for Kagi that gives you command-line access to search, quick answers, ask-page, assistant, translate, summarization, public feeds through news and smallweb, paid API commands like fastgpt and enrich, and account-level settings like lenses, custom assistants, custom bangs, and redirect rules. it is built for people who want one command surface for interactive use, shell workflows, and structured JSON output.

the main setup path is kagi auth. on a real terminal it opens a guided setup flow where you choose Session Link, API Key, or Legacy API Token, get the official instructions inline, paste the credential, save it to ~/.config/kagi-cli/config.toml, and validate it immediately. if you also use Kagi's paid API, the same wizard can add that too.

documentation | npm | mcp

why

if you already use Kagi and want to access it from scripts, shell workflows, or small tools, this CLI gives you a practical path without making the paid API flow the starting point.

• use your existing session-link URL for subscriber features
• get structured JSON for scripts, agents, and other tooling
• use one CLI for search, quick answers, assistant, translate, summarization, news, and smallweb
• add KAGI_API_KEY for current /api/v1 commands, or KAGI_API_TOKEN for legacy /api/v0 commands

quickstart

Linux or macOS

curl -fsSL https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.sh | sh
kagi --help

Windows

irm https://raw.githubusercontent.com/Microck/kagi-cli/main/scripts/install.ps1 | iex
kagi --help

using a package manager

npm install -g kagi-cli
pnpm add -g kagi-cli
bun add -g kagi-cli

# homebrew
brew tap Microck/kagi
brew install kagi

# scoop
scoop bucket add kagi https://github.com/Microck/scoop-kagi
scoop install kagi

# AUR (arch linux)
yay -S kagi-cli

auth

run the guided setup:

kagi auth

the wizard is the default setup path. it guides you through:

• Session Link from https://kagi.com/settings/user_details
• API Key from https://kagi.com/api/keys
• Legacy API Token from https://kagi.com/settings/api
• saving into ~/.config/kagi-cli/config.toml
• immediate validation

non-interactive alternative:

add your subscriber session token directly:

how to get it:

1. click the top-right menu icon
2. go into Settings
3. click Account in the left sidebar
4. in Session Link, click Copy

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

add an api key when you want current paid api commands:

how to get it:

1. click the top-right menu icon
2. go into Settings
3. open https://kagi.com/api/keys
4. generate or copy an API key

export KAGI_API_KEY='...'

auth model

credential	what it unlocks
KAGI_SESSION_TOKEN	base search fallback, session-only search options, quick, ask-page, assistant, translate, and summarize --subscriber
KAGI_API_KEY	current /api/v1 Search API and Extract API with Bearer auth
KAGI_API_TOKEN	legacy /api/v0 public summarize, fastgpt, enrich web, and enrich news with Bot auth
none	news, smallweb, auth status, --help

example config:

[auth]
# Full Kagi session-link URL or just the raw token value.
session_token = "https://kagi.com/search?token=kagi_session_demo_1234567890abcdef"

# Current API key for Search API and Extract.
api_key = "kagi_api_key_demo_abcdef1234567890"

# Legacy API token for summarize, fastgpt, and enrich commands.
api_token = "kagi_api_token_demo_abcdef1234567890"

# Base `kagi search` auth preference: "session" or "api".
preferred_auth = "api"

[profiles.work.auth]
session_token = "https://kagi.com/search?token=work_session_demo"
api_key = "kagi_api_key_work_demo"
api_token = "kagi_api_token_work_demo"
preferred_auth = "session"

notes:

• kagi auth is interactive on TTYs and becomes the default onboarding path
• kagi auth set --session-token accepts either the raw token or the full session-link URL
• kagi --profile work ... reads [profiles.work.auth] from the config file (~/.config/kagi-cli/config.toml)
• environment variables override ~/.config/kagi-cli/config.toml
• base kagi search defaults to the session-token path when both credentials are present
• set [auth] preferred_auth = "api" if you want base search to prefer the API path instead
• API-first base search falls back to the session-token path when the API key is rejected, including quota and rate-limit failures
• search --lens, --time, --order, --verbatim, and personalization flags require KAGI_SESSION_TOKEN
• search --region, --from-date, and --to-date use V1 API filters when routed through KAGI_API_KEY
• auth check validates the selected primary credential without using search fallback logic

for the full command-to-token matrix, use the auth-matrix docs page.

command surface

command	purpose
kagi search	search Kagi with json by default, or render as toon, pretty, compact, markdown, or csv
kagi agent	print the embedded agent skill guide for choosing commands, auth paths, and output formats
kagi skills	list and load embedded, version-matched agent skills with skills get kagi as the agent starting point
kagi batch	run multiple searches in parallel with JSON, TOON, compact, pretty, markdown, or csv output and shared filters
kagi auth	launch the auth wizard, or inspect, validate, and save credentials
kagi completion	generate or install shell completions for bash, zsh, fish, or PowerShell
kagi summarize	use the paid public summarizer API or the subscriber summarizer with --subscriber
kagi extract	extract a page's full content as markdown through the current paid API, using KAGI_API_KEY directly
kagi watch	rerun a search on an interval and emit added/removed result URLs
kagi notify	send search or news output to a webhook
kagi history	inspect local command history and aggregate query stats
kagi news	read Kagi News from public JSON endpoints
kagi quick	get a Quick Answer with references
kagi assistant	prompt Kagi Assistant, continue threads, manage thread list/export/delete, and manage custom assistants
kagi ask-page	ask Kagi Assistant about a specific web page
kagi translate	translate text through Kagi Translate
kagi fastgpt	query FastGPT through the paid API
kagi enrich	query Kagi's web and news enrichment indexes
kagi smallweb	fetch the Kagi Small Web feed
kagi mcp	run a stdio MCP server exposing search, summarize, extract, quick-answer, and news tools
kagi site-pref	manage local domain preferences that filter/reorder CLI search output
kagi lens	list, inspect, create, update, enable, disable, and delete search lenses
kagi bang custom	list, inspect, create, update, and delete custom bangs
kagi redirect	list, inspect, create, update, enable, disable, and delete redirect rules

for automation, stdout stays JSON by default. Use --format toon for token-efficient structured output in LLM context. --format pretty only changes rendering for humans.

shell completion

install completions automatically for your detected shell:

kagi completion install
kagi completion install --shell fish

or generate a completion script and install it yourself:

# 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

kagi --generate-completion <shell> remains available as a shortcut for script generation.

see the installation guide for platform-specific setup details.

examples

use search as part of a shell pipeline:

kagi search "what is mullvad"

switch the same command to terminal-readable output:

kagi search --format pretty "how do i exit vim"

scope search to one of your lenses:

kagi search --lens 2 "developer documentation"

prefix a search with one of your configured snaps:

kagi search --snap reddit "rust async runtime"

run a filtered search against the subscriber web-product path:

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

use explicit date bounds instead of a preset time window:

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

force personalized search on or off for one request:

kagi search --personalized "best cafes nearby"
kagi search --no-personalized "best cafes nearby"

render search results without jq:

kagi search "rust crates" --template '{{rank}}. {{title}} - {{url}}'

summarize the top search results in one command:

kagi search "rust async runtime tradeoffs" --follow 3

watch for search result changes:

kagi watch "kagi-cli release" --interval 600 --count 6

run a few searches in parallel:

kagi batch "rust programming" "python tutorial" "go language"

read batch queries from stdin:

printf 'rust\npython\ngo\n' | kagi batch --format compact

change batch output format for shell pipelines:

kagi batch "rust" "python" "go" --format compact

continue research with assistant:

kagi assistant "plan a focused research session in the terminal"
kagi assistant --stream "write a short implementation plan"
kagi assistant --stream --stream-output json "write a short implementation plan"

run assistant with a saved assistant profile and markdown output:

kagi assistant --assistant research --format markdown "summarize the latest rust release"

attach local files to an assistant prompt:

kagi assistant --attach ./a.jpg --attach ./b.pdf "tell me everything about this pdf"

use assistant as a terminal chat client:

kagi assistant repl --model gpt-5-4-nano --export ./assistant-transcript.json

ask assistant about a page directly:

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

list or export Assistant threads:

kagi assistant thread list
kagi assistant thread export <THREAD_ID>

kagi assistant thread list automatically follows Kagi's pagination cursor so large chat histories are returned in one response.

manage custom assistants:

kagi assistant custom list
kagi assistant custom get "Release Notes"
kagi assistant custom create "Release Notes" --model gpt-5-4-nano --web-access --lens 2 --instructions "Focus on release diffs and migration notes."
kagi assistant custom update "Release Notes" --bang-trigger relnotes --no-personalized

get a quick answer with references:

kagi quick --format pretty "what is rust"

translate text and keep all text-mode extras:

kagi translate "Bonjour tout le monde"

plain kagi translate "..." means --from auto --to en.

translate from stdin:

echo "Bonjour tout le monde" | kagi translate --to ja

translate to a specific target language:

kagi translate "Bonjour tout le monde" --to ja

translate only the core text result:

kagi translate "Bonjour tout le monde" --no-alternatives --no-word-insights --no-suggestions --no-alignments

use the subscriber summarizer:

kagi summarize --subscriber --url https://kagi.com --summary-type keypoints --length digest

summarize a stream of URLs:

cat urls.txt | kagi summarize --filter --subscriber --length digest

use the paid api summarizer:

kagi summarize --url https://example.com --engine cecil

get a faster factual answer through the paid api:

kagi fastgpt "what changed in rust 1.86?"

query enrichment indexes:

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

inspect account-level search settings:

kagi lens list
kagi bang custom list
kagi redirect list

inspect or change one lens, bang, or redirect rule:

```bash kagi lens get "Default" kagi lens update "Default" --description "primary search profile" kagi bang custom create "Docs" --trigger docs --template "https://docs.rs/releases/search?query=%s" kagi bang custom update docs --shortcut-