feat: add Kagi account settings commands and assistant/search parity

README.md

@@ -16,7 +16,7 @@
 
 ---
 
-`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.
+`kagi` is a terminal CLI for Kagi that gives you command-line access to search, quick answers, ask-page, assistant, translate, summarization, feeds, paid API commands, 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` 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.
 
@@ -161,12 +161,15 @@ for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.
 | `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 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 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. `--format pretty` only changes rendering for humans.
 
@@ -207,6 +210,12 @@ scope search to one of your lenses:
 kagi search --lens 2 "developer documentation"
 ```
 
+prefix a search with one of your configured snaps:
+
+```bash
+kagi search --snap reddit "rust async runtime"
+```
+
 run a filtered search against the subscriber web-product path:
 
 ```bash
@@ -231,6 +240,12 @@ continue research with assistant:
 kagi assistant "plan a focused research session in the terminal"
 ```
 
+run assistant with a saved assistant profile and markdown output:
+
+```bash
+kagi assistant --assistant research --format markdown "summarize the latest rust release"
+```
+
 ask assistant about a page directly:
 
 ```bash
@@ -244,6 +259,13 @@ kagi assistant thread list
 kagi assistant thread export <THREAD_ID>
 ```
 
+manage custom assistants:
+
+```bash
+kagi assistant custom list
+kagi assistant custom create "Release Notes" --model gpt-5-mini --web-access
+```
+
 get a quick answer with references:
 
 ```bash
@@ -295,6 +317,14 @@ kagi enrich web "local-first software"
 kagi enrich news "browser privacy"
 ```
 
+inspect account-level search settings:
+
+```bash
+kagi lens list
+kagi bang custom list
+kagi redirect list
+```
+
 ## 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:

docs/api-coverage.md

@@ -1,47 +1,5 @@
 # Kagi API and Product Coverage
 
-## Current support in this CLI
+This repo now keeps the maintained coverage reference in [`docs/reference/coverage.mdx`](./reference/coverage.mdx).
 
-### Implemented
-- **Search / session-token HTML search** - fully implemented and live-verified for base search, lens-aware search, and runtime search filters (`r`, `dr`, `from_date`, `to_date`, `order`, `verbatim`, `personalized`)
-- **Search / official API-token path** - implemented for base search only; if Kagi rejects the API-token search path, base search falls back to session-token search when available
-- **Universal Summarizer API** - implemented on the documented paid public API path
-- **FastGPT API** - implemented on the documented paid public API path
-- **Web and News Enrichment API** - implemented on the documented paid public API path
-- **Small Web RSS feed** - implemented and live-verified
-- **Subscriber web Summarizer** - implemented on the session-token web-product path via `kagi summarize --subscriber ...`
-- **Kagi News public product endpoints** - implemented via `kagi news ...`
-- **Subscriber web Quick Answer flow** - implemented on Kagi's authenticated Quick Answer stream via `kagi quick ...`
-- **Subscriber web Assistant prompt flow** - implemented on Kagi Assistant's authenticated tagged stream via `kagi assistant ...`
-- **Subscriber web Assistant thread list/open/delete/export flows** - implemented on the authenticated Assistant thread endpoints via `kagi assistant thread ...`
-- **Kagi Translate text mode** - implemented via `kagi translate ...` with runtime bootstrap from `KAGI_SESSION_TOKEN`
-
-## Source of truth
-
-According to Kagi's public API docs, the documented API families are:
-- Kagi Search API
-- Web and News Enrichment API
-- Universal Summarizer API
-- FastGPT API
-- Kagi Small Web RSS feed
-
-This CLI also implements non-public or product-only seams:
-- subscriber web Summarizer via Kagi session-token auth
-- subscriber web Quick Answer via Kagi session-token auth
-- subscriber web Assistant prompt flow via Kagi session-token auth
-- subscriber web Assistant thread management via Kagi session-token auth
-- Kagi News product endpoints
-
-## Notes
-
-- Lens support and runtime search filters are not documented on the official Search API. In this CLI they work through Kagi's live HTML/session flow using the `l`, `r`, `dr`, `from_date`, `to_date`, `order`, `verbatim`, and `personalized` query parameters.
-- The official Search API uses `Authorization: Bot <token>` on `https://kagi.com/api/v0/search`.
-- Search API access is still account-gated in practice, and API-token search can also fail for billing reasons.
-- Base-search fallback to session-token search happens on the user-facing `search` command only. `auth check` validates the selected primary credential without fallback.
-- The paid public Summarizer, FastGPT, and Enrichment APIs require `KAGI_API_TOKEN` and sufficient API credit.
-- The subscriber web Summarizer requires `KAGI_SESSION_TOKEN` and uses the authenticated `GET /mother/summary_labs?...` stream path instead of the public `/api/v0/summarize` endpoint.
-- Live verification on March 18, 2026 showed that direct HTTP bootstrap can mint `translate_session` from the same `KAGI_SESSION_TOKEN` by reading the `Set-Cookie` header from `https://translate.kagi.com/`.
-- After bootstrap, the CLI uses normal Rust HTTP requests for `/api/detect`, `/api/translate`, `/api/alternative-translations`, `/api/text-alignments`, `/api/translation-suggestions`, and `/api/word-insights`.
-- Assistant requires `KAGI_SESSION_TOKEN` and currently targets `/assistant/prompt`, `/assistant/thread_list`, `/assistant/thread_open`, `/assistant/thread_delete`, and `/assistant/<thread_id>/download`.
-- Quick Answer requires `KAGI_SESSION_TOKEN` and currently targets `POST /mother/context?q=...` with `Accept: application/vnd.kagi.stream`.
-- News uses `https://news.kagi.com/api/...` JSON endpoints and does not require auth.
+Use that page for the current command surface, auth-path coverage, and notes about intentionally unsupported product seams.

docs/commands/assistant.mdx

@@ -1,11 +1,11 @@
 ---
 title: "assistant"
-description: "Complete reference for *kagi* assistant command - prompt Kagi Assistant and manage Assistant threads."
+description: "Complete reference for *kagi* assistant command - prompt Kagi Assistant, use saved assistants, and manage Assistant threads and custom assistants."
 ---
 
 # `kagi assistant`
 
-Prompt Kagi Assistant, continue an existing thread, and manage thread list, export, and deletion from the terminal.
+Prompt Kagi Assistant, continue an existing thread, use a saved assistant profile, and manage both Assistant threads and custom assistants from the terminal.
 
 ![Assistant demo](/images/demos/assistant.gif)
 
@@ -17,13 +17,18 @@ 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 stream, not the paid public API token path.
+The Assistant feature uses Kagi's authenticated web-product flow, not the paid public API token path.
 
 ## Prompt Mode
 
@@ -44,12 +49,38 @@ The prompt to send to Kagi Assistant.
 
 Continue an existing Assistant thread.
 
+#### `--assistant <ASSISTANT>`
+
+Use a saved assistant by exact name, profile id, or invoke-profile slug.
+
+```bash
+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
+
+```bash
+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.
 
-Example:
-
 ```bash
 kagi assistant --model gpt-5-mini "reply with only the model name"
 ```
@@ -112,6 +143,63 @@ Return the thread as structured JSON instead of markdown. This emits the same en
 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.
+
+```bash
+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.
+
+```bash
+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>`
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+kagi assistant custom delete "Release Notes"
+```
+
 ## Output Contract
 
 Prompt mode returns:
@@ -185,6 +273,23 @@ Prompt mode returns:
 }
 ```
 
+`custom list` returns an array of assistant summaries:
+
+```json
+[
+  {
+    "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:
@@ -198,31 +303,33 @@ kagi assistant --thread-id "$THREAD_ID" "turn that into a 3-item checklist" | jq
 kagi assistant thread export "$THREAD_ID"
 ```
 
-List threads and inspect one:
+Use a saved assistant profile with terminal-readable output:
 
 ```bash
-kagi assistant thread list | jq -r '.threads[] | "\(.id) \(.title)"'
-kagi assistant thread get "$THREAD_ID" | jq '.messages | length'
+kagi assistant \
+  --assistant research \
+  --format pretty \
+  --no-personalized \
+  "What changed in Rust 1.86?"
 ```
 
-Use prompt controls for a one-off request:
+List custom assistants and inspect one:
 
 ```bash
-kagi assistant \
-  --model gpt-5-mini \
-  --web-access \
-  --no-personalized \
-  "What changed in Rust 1.86?"
+kagi assistant custom list | jq -r '.[] | "\(.name) \(.model)"'
+kagi assistant custom get "Research"
 ```
 
 ## Notes
 
-- `kagi assistant` is JSON-first. There is no pretty renderer in this command.
+- Prompt mode now supports `json`, `pretty`, `compact`, and `markdown`.
 - `thread export` defaults to markdown because that is the natural terminal transcript format.
-- `--mode` is intentionally not exposed. The current web app resolves higher-level Assistant profiles client-side, and I did not find a stable request field that would make a trustworthy CLI contract.
+- `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.
 
 ## See Also
 
-- [fastgpt](/commands/fastgpt) - quick answers via the paid public API
+- [search](/commands/search) - search and snap-prefixed discovery
+- [lens](/commands/lens) - manage reusable search scopes
 - [auth-matrix](/reference/auth-matrix) - which commands require which token
 - [output-contract](/reference/output-contract) - JSON shapes and jq examples