Skip to main content

​
Output Contract

This page documents the current CLI output behavior as implemented in the repo.

​
Core Rules

  1. Most commands print pretty-formatted JSON to stdout on success.
  2. kagi search, kagi batch, and kagi quick support human-readable output via format flags.
  3. Errors are plain text on stderr and exit with status code 1.
  4. Output shapes differ by command. There is no single universal response envelope.

​
Success Shapes

{
  "data": [
    {
      "t": 0,
      "rank": 1,
      "title": "Result Title",
      "url": "https://example.com",
      "snippet": "Description...",
      "published": "2026-03-16T00:00:00Z"
    }
  ]
}

​
kagi batch

Default JSON output uses a structured envelope: 
{
  "queries": ["rust", "go"],
  "results": [
    {
      "data": [
        {
          "t": 0,
          "rank": 1,
          "title": "Result Title",
          "url": "https://example.com",
          "snippet": "Description...",
          "published": "2026-03-16T00:00:00Z"
        }
      ]
    }
  ]
}

​
kagi summarize

Public API mode: 
{
  "meta": {
    "id": "1",
    "node": "us-east",
    "ms": 10
  },
  "data": {
    "output": "summary text",
    "tokens": 42
  }
}
Subscriber mode: 
{
  "meta": {
    "version": "202603091651.stage.c128588",
    "trace": "abc123"
  },
  "data": {
    "thread_id": "thread-1",
    "state": "done",
    "output": "summary text",
    "markdown": "summary text"
  }
}

​
kagi news

{
  "latest_batch": {
    "id": "batch-123",
    "created_at": "2026-03-16T00:00:00Z"
  },
  "category": {
    "category_id": "tech",
    "category_name": "Technology"
  },
  "stories": [],
  "total_stories": "20",
  "domains": [],
  "read_count": 1234
}
kagi news --list-categories and kagi news --chaos return different JSON shapes with category metadata or chaos metadata.

​
kagi assistant

{
  "meta": {
    "version": "202603091651.stage.c128588",
    "trace": "trace-123"
  },
  "thread": {
    "id": "thread-1",
    "title": "Greeting",
    "created_at": "2026-03-16T06:19:07Z"
  },
  "message": {
    "id": "msg-1",
    "thread_id": "thread-1",
    "created_at": "2026-03-16T06:19:07Z",
    "state": "done",
    "prompt": "Hello",
    "markdown": "Hi"
  }
}

​
kagi quick

{
  "meta": {
    "version": "202603171911.stage.707e740",
    "trace": "trace-123"
  },
  "query": "what is rust",
  "lens": null,
  "message": {
    "id": "msg-1",
    "thread_id": "thread-1",
    "created_at": "2026-03-19T00:00:00Z",
    "state": "done",
    "prompt": "what is rust",
    "html": "<p>Rust is a systems programming language.</p>",
    "markdown": "Rust is a systems programming language."
  },
  "references": {
    "markdown": "[^1]: [Rust](https://www.rust-lang.org/) (26%)",
    "items": [
      {
        "index": 1,
        "title": "Rust",
        "domain": "www.rust-lang.org",
        "url": "https://www.rust-lang.org/",
        "contribution_pct": 26
      }
    ]
  },
  "followup_questions": [
    "Why is Rust memory-safe?"
  ]
}

​
kagi fastgpt

{
  "meta": {
    "id": "1",
    "node": "us-east",
    "ms": 10
  },
  "data": {
    "output": "answer text",
    "tokens": 12,
    "references": []
  }
}

​
kagi enrich

{
  "meta": {
    "id": "1",
    "node": "us-east",
    "ms": 10
  },
  "data": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "snippet": "Description...",
      "published": "2026-03-16T00:00:00Z"
    }
  ]
}

​
kagi smallweb

{
  "xml": "<?xml version=\"1.0\"?><rss>...</rss>"
}

​
Pretty Search Output

kagi search --format pretty renders results like this: 
1. Result Title
   https://example.com

   Description...
If the result set is empty, the CLI prints: 
No results found.

​
Pretty Quick Output

kagi quick --format pretty renders: 
Quick Answer

Rust is a systems programming language...

References

1. Learn (35%)
   https://www.rust-lang.org/learn

​
Error Behavior

Errors are plain text on stderr. Typical examples: 
Config error: missing credentials: set KAGI_API_TOKEN or KAGI_SESSION_TOKEN (env), or add [auth] api_token/session_token to .kagi.toml
Auth error: invalid or expired Kagi session token
Network error: request to Kagi timed out

​
jq Examples

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

# FastGPT answer text
kagi fastgpt "What is Rust?" | jq -r '.data.output'

# Assistant markdown reply
kagi assistant "Hello" | jq -r '.message.markdown'

# Quick Answer markdown reply
kagi quick "what is rust" | jq -r '.message.markdown'

# Quick Answer references
kagi quick "what is rust" | jq -r '.references.items[].url'

# Subscriber summary text
kagi summarize --subscriber --url https://example.com | jq -r '.data.output'

# Small Web raw feed
kagi smallweb | jq -r '.xml'