README.md

---

kagi is a terminal CLI for Kagi that gives you command-line access to search, quick answers, lenses, ask-page, assistant, translate, summarization, feeds, and paid API commands. 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 or API Token, get the official instructions inline, paste the credential, save it to ./.kagi.toml, and validate it immediately. if you also use Kagi's paid API, the same wizard can add that too.

documentation | npm | github

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, and feeds
• add KAGI_API_TOKEN only when you want the paid public API 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 Token from https://kagi.com/settings/api
• saving into ./.kagi.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 token when you want the paid public api commands:

how to get it:

1. click the top-right menu icon
2. go into Settings
3. click Advanced in the left sidebar
4. go into Open API Portal
5. under API Token, click Generate New Token

export KAGI_API_TOKEN='...'

auth model

credential	what it unlocks
KAGI_SESSION_TOKEN	base search fallback, search --lens, filtered search, quick, ask-page, assistant, translate, summarize --subscriber
KAGI_API_TOKEN	public summarize, fastgpt, enrich web, enrich news
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"

# Paid API token for summarize, fastgpt, and enrich commands.
api_token = "kagi_api_demo_abcdef1234567890"

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

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
• environment variables override .kagi.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
• search --lens and all runtime search filters require KAGI_SESSION_TOKEN
• 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, optional live filters, or --format pretty for terminal output
kagi batch	run multiple searches in parallel with JSON, compact, pretty, markdown, or csv output and shared filters
kagi auth	launch the auth wizard, or inspect, validate, and save credentials
kagi summarize	use the paid public summarizer API or the subscriber summarizer with --subscriber
kagi news	read Kagi News from public JSON endpoints
kagi quick	get a Quick Answer with references
kagi assistant	prompt Kagi Assistant, continue threads, and manage thread list/export/delete
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

for automation, stdout stays JSON by default. --format pretty only changes rendering for humans.

shell completion

generate a completion script and install it with your shell of choice:

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

# zsh
kagi --generate-completion zsh > ~/.zsh/completion/_kagi

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

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"

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

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

run a few searches in parallel:

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

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"

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>

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

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"

what it looks like

if you want a quick feel for the cli before installing it, this is the kind of output you get from auth setup, quick answer, translate, ask-page, the subscriber summarizer, assistant, and the public news feed:

building from source

if you are working on the cli itself, build from a local checkout:

git clone https://github.com/Microck/kagi-cli.git
cd kagi-cli
cargo build --release
./target/release/kagi --help

for the fuller install matrix and platform-specific setup, use the installation guide.

documentation

• installation guide
• quickstart guide
• authentication guide
• workflows

disclaimer

this project is unofficial and not affiliated with, endorsed by, or connected to Kagi Inc. it is an independent, community-built tool.

license

mit license