Skip to main content

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.

​
kagi search

Search Kagi and return structured results in JSON or human-readable format. Search demo

​
Synopsis

kagi search [OPTIONS] <QUERY>

​
Description

kagi search is the main search command. By default it emits JSON for scripts and agents. Use --format pretty for terminal reading. There are now two search modes:
  • Base search uses your configured base-search auth preference. By default this repo prefers the subscriber session path. If you set [auth.preferred_auth] = "api", base search uses the Search API first and can fall back to the subscriber web-product path on API auth rejection.
  • Filtered search uses Kagi’s authenticated HTML/session search path and requires KAGI_SESSION_TOKEN.
This matters because the Kagi Search API is still base-search only in this CLI. As soon as you add live search filters like --lens, --region, --time, --order, --verbatim, or --personalized, the request becomes session-only. --snap works in either mode. It simply prefixes your query with a snap shortcut before the request is built.

​
Authentication

Default: KAGI_SESSION_TOKEN Optional API-first mode: set [auth.preferred_auth] = "api" Plain base search keeps the existing repo behavior:
  • default session-first search when a session token is available
  • API-first only when you explicitly configure [auth.preferred_auth] = "api"
  • session fallback only when the API path was selected first and rejected
Required: KAGI_SESSION_TOKEN Any of these flags make the request session-only:
  • --lens
  • --region
  • --time
  • --from-date
  • --to-date
  • --order
  • --verbatim
  • --personalized
  • --no-personalized

​
Options

​
<QUERY> (Required)

The search query string. 
kagi search "rust programming language"
kagi search "site:github.com rust cli"

​
--format <FORMAT>

Output format. Possible values:
  • json - pretty JSON
  • compact - minified JSON
  • pretty - terminal-friendly output
  • markdown - markdown list output
  • csv - CSV table output

​
--no-color

Disable ANSI colors in --format pretty.

​
--snap <SNAP>

Prefix the query with a snap shortcut. reddit becomes @reddit QUERY. Values may be supplied with or without the leading @. 
kagi search --snap reddit "rust async runtime"
kagi search --snap @map "coffee near london bridge"

​
--lens <INDEX>

Scope search to one of your enabled Kagi lenses. 
kagi search --lens 2 "developer documentation"

​
--region <REGION>

Restrict results to a Kagi region code such as us, gb, jp, or no_region. 
kagi search --region us "rust conferences"
kagi search --region no_region "rust ownership"

​
--time <WINDOW>

Restrict results to a recent update window. Possible values:
  • day
  • week
  • month
  • year
kagi search --time week "rust release notes"

​
--from-date <YYYY-MM-DD>

Restrict results to pages updated on or after the given date.

​
--to-date <YYYY-MM-DD>

Restrict results to pages updated on or before the given date. 
kagi search --from-date 2026-01-01 --to-date 2026-03-01 "rust compiler"
Important: --time cannot be combined with --from-date or --to-date.

​
--order <ORDER>

Reorder results using Kagi’s live HTML search sort options. Possible values:
  • default
  • recency
  • website
  • trackers
kagi search --order recency "rust changelog"

​
--verbatim

Enable verbatim search for this request. 
kagi search --verbatim "\"rust async runtime\""

​
--personalized

Force personalized search on for this request.

​
--no-personalized

Force personalized search off for this request. 
kagi search --no-personalized "rust web framework"

​
Not Supported as Runtime Flags

safe_search is currently an account setting, not a search-time flag in this CLI. Configure it in the Kagi web settings instead of expecting kagi search to override it per request.

​
Output Format

The search response shape is unchanged: 
{
  "data": [
    {
      "t": 0,
      "rank": 1,
      "title": "Rust Programming Language",
      "url": "https://www.rust-lang.org",
      "snippet": "A language empowering everyone to build reliable and efficient software.",
      "published": null
    }
  ]
}

​
Examples

kagi search "rust programming language"

kagi search --snap reddit "rust async runtime"

​
Human-readable output

kagi search --format pretty "rust programming language"

kagi search --region us --format pretty "rust conferences"

​
Recent results

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

​
Custom date range

kagi search --from-date 2026-01-01 --to-date 2026-03-01 "rust async runtime"

​
Verbatim plus personalization control

kagi search --verbatim --no-personalized "\"rust book ownership\""

​
Lens plus filters

kagi search --lens 2 --region us --time year "developer documentation"

​
Processing Results

# Extract URLs
kagi search "rust" | jq -r '.data[].url'

# Get first result
kagi search "rust" | jq -r '.data[0].title'

# Human-readable markdown
kagi search --format markdown "rust ownership"

​
Exit Codes

CodeMeaning
0Success
1Error - see stderr

​
Common Errors

  • search filters require KAGI_SESSION_TOKEN - you used runtime filters without a session token
  • search --time cannot be combined with --from-date or --to-date - choose a preset window or a custom date range
  • search --from-date must use YYYY-MM-DD format - dates must be zero-padded ISO dates
  • lens 'foo' must be a numeric index - lens values are numeric Kagi lens indices
  • kagi batch - run multiple searches with the same search filters and optional --snap
  • kagi lens - manage reusable search scopes
  • kagi assistant - continue research with Kagi Assistant
  • kagi auth - inspect which token path will be used

​
See Also