`kagi assistant`

Prompt Kagi Assistant, continue an existing thread, use a saved assistant profile, and manage both Assistant threads and custom assistants from the terminal.

Synopsis

kagi assistant [OPTIONS] <QUERY>
kagi assistant thread list
kagi assistant thread get <THREAD_ID>
kagi assistant thread delete <THREAD_ID>
kagi assistant thread export <THREAD_ID> [--format markdown|json]
kagi assistant custom list
kagi assistant custom get <ID_OR_NAME>
kagi assistant custom create <NAME> [OPTIONS]
kagi assistant custom update <ID_OR_NAME> [OPTIONS]
kagi assistant custom delete <ID_OR_NAME>

Authentication

Required: KAGI_SESSION_TOKEN The Assistant feature uses Kagi’s authenticated web-product flow, not the paid public API token path.

Prompt Mode

Use prompt mode to start a new thread or continue an existing one:

kagi assistant "plan a focused research session in the terminal"
kagi assistant --thread-id <THREAD_ID> "turn that into a 3-item checklist"

Prompt Arguments

`<QUERY>`

The prompt to send to Kagi Assistant.

`--thread-id <THREAD_ID>`

Continue an existing Assistant thread.

`--assistant <ASSISTANT>`

Use a saved assistant by exact name, profile id, or invoke-profile slug.

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

`--format <FORMAT>`

Output format for prompt mode. Possible values:

json - pretty JSON
pretty - terminal-friendly thread id, message id, and reply content
compact - minified JSON
markdown - only the assistant reply content

kagi assistant --format pretty "What changed in Rust 1.86?"
kagi assistant --format markdown "Write a release summary"

`--no-color`

Disable ANSI colors in --format pretty.

`--model <MODEL>`

Override the model slug for a single prompt.

kagi assistant --model gpt-5-mini "reply with only the model name"

`--lens <LENS_ID>`

Override the Assistant lens id for a single prompt. This is the Assistant profile lens_id, not the search-command lens index used by kagi search --lens.

`--web-access`

`--no-web-access`

Force internet access on or off for a single prompt.

`--personalized`

`--no-personalized`

Force Kagi personalizations on or off for a single prompt.

Thread Subcommands

`kagi assistant thread list`

List Assistant threads for the current account.

kagi assistant thread list | jq -r '.threads[].id'

`kagi assistant thread get <THREAD_ID>`

Fetch one thread with its messages.

kagi assistant thread get "$THREAD_ID"

`kagi assistant thread delete <THREAD_ID>`

Delete one thread.

kagi assistant thread delete "$THREAD_ID"

`kagi assistant thread export <THREAD_ID>`

Export one thread as markdown to stdout.

kagi assistant thread export "$THREAD_ID"

`kagi assistant thread export <THREAD_ID> --format json`

Return the thread as structured JSON instead of markdown. This emits the same envelope shape as thread get.

kagi assistant thread export "$THREAD_ID" --format json

Custom Assistant Subcommands

`kagi assistant custom list`

List built-in and custom assistants visible to the current account.

kagi assistant custom list | jq -r '.[] | "\(.name) \(.invoke_profile)"'

`kagi assistant custom get <ID_OR_NAME>`

Fetch one custom assistant definition by id or exact name.

kagi assistant custom get "Release Notes"

`kagi assistant custom create <NAME>`

Create a custom assistant. Supported options:

--bang-trigger <TRIGGER> - optional trigger without the leading !
--web-access / --no-web-access
--lens <LENS_ID>
--personalized / --no-personalized
--model <MODEL>
--instructions <TEXT>

kagi assistant custom create "Release Notes" \
  --bang-trigger release \
  --model gpt-5-mini \
  --web-access \
  --instructions "Summarize release posts with a changelog-first bias."

`kagi assistant custom update <ID_OR_NAME>`

Update a custom assistant by id or exact name.

kagi assistant custom update "Release Notes" \
  --no-web-access \
  --instructions "Stay strictly within the supplied text."

`kagi assistant custom delete <ID_OR_NAME>`

Delete a custom assistant by id or exact name.

kagi assistant custom delete "Release Notes"

Output Contract

Prompt mode returns:

{
  "meta": {
    "version": "202603171911.stage.707e740",
    "trace": "trace-123"
  },
  "thread": {
    "id": "thread-1",
    "title": "Greeting",
    "ack": "2026-03-16T06:19:07Z",
    "created_at": "2026-03-16T06:19:07Z",
    "expires_at": "2026-03-16T07:19:07Z",
    "saved": false,
    "shared": false,
    "branch_id": "00000000-0000-4000-0000-000000000000",
    "tag_ids": []
  },
  "message": {
    "id": "msg-1",
    "thread_id": "thread-1",
    "created_at": "2026-03-16T06:19:07Z",
    "branch_list": [],
    "state": "done",
    "prompt": "Hello",
    "reply_html": "<p>Hi</p>",
    "markdown": "Hi",
    "references_markdown": null,
    "metadata_html": "<li>meta</li>",
    "documents": [],
    "profile": {
      "model": "ki_quick",
      "model_name": "Quick"
    },
    "trace_id": "trace-message-1"
  }
}

thread list returns:

{
  "meta": {
    "version": "202603171911.stage.707e740",
    "trace": "trace-123"
  },
  "tags": [],
  "threads": [
    {
      "id": "thread-1",
      "title": "Greeting",
      "url": "/assistant/thread-1",
      "snippet": "Hello",
      "saved": false,
      "shared": false,
      "tag_ids": []
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false,
    "count": 1,
    "total_counts": {
      "all": 1
    }
  }
}

custom list returns an array of assistant summaries:

[
  {
    "id": "assistant-1",
    "name": "Research",
    "invoke_profile": "research",
    "model": "gpt-5-mini",
    "bang_trigger": "research",
    "internet_access": true,
    "built_in": false,
    "edit_url": "/assistant/custom-assistants/assistant-1"
  }
]

Examples

Start a thread, capture the id, continue it, then export it:

RESPONSE=$(kagi assistant --model gpt-5-mini "plan a calm terminal research session in 3 bullets")
THREAD_ID=$(printf '%s' "$RESPONSE" | jq -r '.thread.id')

printf '%s\n' "$RESPONSE" | jq -r '.message.markdown'
kagi assistant --thread-id "$THREAD_ID" "turn that into a 3-item checklist" | jq -r '.message.markdown'
kagi assistant thread export "$THREAD_ID"

Use a saved assistant profile with terminal-readable output:

kagi assistant \
  --assistant research \
  --format pretty \
  --no-personalized \
  "What changed in Rust 1.86?"

List custom assistants and inspect one:

kagi assistant custom list | jq -r '.[] | "\(.name) \(.model)"'
kagi assistant custom get "Research"

Notes

Prompt mode now supports json, pretty, compact, and markdown.
thread export defaults to markdown because that is the natural terminal transcript format.
assistant custom list includes built-in assistants as well as user-created ones.
File-upload Assistant flows are intentionally out of scope in this CLI today.

Core Commands

Content & Feeds

AI & Enrichment

Settings

assistant

`kagi assistant`

Synopsis

Authentication

Prompt Mode

Prompt Arguments

`<QUERY>`

`--thread-id <THREAD_ID>`

`--assistant <ASSISTANT>`

`--format <FORMAT>`

`--no-color`

`--model <MODEL>`

`--lens <LENS_ID>`

`--web-access`

`--no-web-access`

`--personalized`

`--no-personalized`

Thread Subcommands

`kagi assistant thread list`

`kagi assistant thread get <THREAD_ID>`

`kagi assistant thread delete <THREAD_ID>`

`kagi assistant thread export <THREAD_ID>`

`kagi assistant thread export <THREAD_ID> --format json`

Custom Assistant Subcommands

`kagi assistant custom list`

`kagi assistant custom get <ID_OR_NAME>`

`kagi assistant custom create <NAME>`

`kagi assistant custom update <ID_OR_NAME>`

`kagi assistant custom delete <ID_OR_NAME>`

Output Contract

Examples

Notes

See Also

Core Commands

Content & Feeds

AI & Enrichment

Settings

Documentation Index

​kagi assistant

​Synopsis

​Authentication

​Prompt Mode

​Prompt Arguments

​<QUERY>

​--thread-id <THREAD_ID>

​--assistant <ASSISTANT>

​--format <FORMAT>

​--no-color

​--model <MODEL>

​--lens <LENS_ID>

​--web-access

​--no-web-access

​--personalized

​--no-personalized

​Thread Subcommands

​kagi assistant thread list

​kagi assistant thread get <THREAD_ID>

​kagi assistant thread delete <THREAD_ID>

​kagi assistant thread export <THREAD_ID>

​kagi assistant thread export <THREAD_ID> --format json

​Custom Assistant Subcommands

​kagi assistant custom list

​kagi assistant custom get <ID_OR_NAME>

​kagi assistant custom create <NAME>

​kagi assistant custom update <ID_OR_NAME>

​kagi assistant custom delete <ID_OR_NAME>

​Output Contract

​Examples

​Notes

​See Also

`kagi assistant`

Synopsis

Authentication

Prompt Mode

Prompt Arguments

`<QUERY>`

`--thread-id <THREAD_ID>`

`--assistant <ASSISTANT>`

`--format <FORMAT>`

`--no-color`

`--model <MODEL>`

`--lens <LENS_ID>`

`--web-access`

`--no-web-access`

`--personalized`

`--no-personalized`

Thread Subcommands

`kagi assistant thread list`

`kagi assistant thread get <THREAD_ID>`

`kagi assistant thread delete <THREAD_ID>`

`kagi assistant thread export <THREAD_ID>`

`kagi assistant thread export <THREAD_ID> --format json`

Custom Assistant Subcommands

`kagi assistant custom list`

`kagi assistant custom get <ID_OR_NAME>`

`kagi assistant custom create <NAME>`

`kagi assistant custom update <ID_OR_NAME>`

`kagi assistant custom delete <ID_OR_NAME>`

Output Contract

Examples

Notes

See Also