feat(assistant): add ask-page command

README.md

@@ -15,7 +15,7 @@
 
 ---
 
-`kagi` is a terminal CLI for Kagi that gives you command-line access to search, lenses, assistant, 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, lenses, ask-page, assistant, 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 your existing Kagi session-link URL. paste it into `kagi auth set --session-token` and the CLI extracts the token for you. if you also use Kagi's paid API, add `KAGI_API_TOKEN` and the public API commands are available too.
 
@@ -101,7 +101,7 @@ export KAGI_API_TOKEN='...'
 
 | credential | what it unlocks |
 | --- | --- |
-| `KAGI_SESSION_TOKEN` | base search, `search --lens`, `assistant`, `summarize --subscriber` |
+| `KAGI_SESSION_TOKEN` | base search, `search --lens`, `ask-page`, `assistant`, `summarize --subscriber` |
 | `KAGI_API_TOKEN` | public `summarize`, `fastgpt`, `enrich web`, `enrich news` |
 | none | `news`, `smallweb`, `auth status`, `--help` |
 
@@ -139,6 +139,7 @@ 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 assistant` | prompt Kagi Assistant, continue threads, and manage thread list/export/delete with a subscriber session token |
+| `kagi ask-page` | ask Kagi Assistant about a specific web page |
 | `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 |
@@ -200,6 +201,12 @@ continue research with assistant:
 kagi assistant "plan a focused research session in the terminal"
 ```
 
+ask assistant about a page directly:
+
+```bash
+kagi ask-page https://rust-lang.org/ "What is this page about?"
+```
+
 list or export Assistant threads:
 
 ```bash
@@ -234,10 +241,12 @@ 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 the subscriber summarizer, assistant, and public news feed:
+if you want a quick feel for the cli before installing it, this is the kind of output you get from ask-page, the subscriber summarizer, assistant, and the public news feed:
 
 ![summarize demo](images/demos/summarize.gif)
 
+![ask-page demo](images/demos/ask-page.gif)
+
 ![assistant demo](images/demos/assistant.gif)
 
 ![news demo](images/demos/news.gif)

docs/commands/ask-page.mdx

@@ -0,0 +1,140 @@
+---
+title: "ask-page"
+description: "Complete reference for *kagi* ask-page command - ask Kagi Assistant about a specific web page."
+---
+
+# `kagi ask-page`
+
+Ask Kagi Assistant about a specific web page and return the new thread plus the answer as JSON.
+
+![Ask Page demo](/images/demos/ask-page.gif)
+
+## Synopsis
+
+```bash
+kagi ask-page <URL> <QUESTION>
+```
+
+## Description
+
+The `kagi ask-page` command starts a new Assistant thread focused on one page URL. It mirrors the live Kagi web flow used by “Continue in Assistant” from search results, but packages it as a direct CLI command.
+
+The response includes:
+
+- stream metadata
+- the normalized source URL and question
+- the created Assistant thread
+- the Assistant reply payload
+
+Use this command when you want page-specific follow-up without manually pasting the URL into a browser Assistant session.
+
+## Authentication
+
+**Required:** `KAGI_SESSION_TOKEN`
+
+This command uses the subscriber Assistant web-product flow.
+
+## Arguments
+
+### `<URL>` (Required)
+
+Absolute page URL to discuss.
+
+Constraints:
+
+- must be an absolute `http` or `https` URL
+- empty values are rejected
+
+Examples:
+
+```bash
+kagi ask-page https://rust-lang.org/ "What is this page about?"
+kagi ask-page https://kagi.com "Summarize the main product pitch"
+```
+
+### `<QUESTION>` (Required)
+
+Question to ask about the page.
+
+Examples:
+
+```bash
+kagi ask-page https://rust-lang.org/ "What learning resources does this page link to?"
+kagi ask-page https://example.com "Give me the core claim in one sentence"
+```
+
+## Output Format
+
+```json
+{
+  "meta": {
+    "version": "202603171911.stage.707e740",
+    "trace": "trace-123"
+  },
+  "source": {
+    "url": "https://rust-lang.org/",
+    "question": "What is this page about?"
+  },
+  "thread": {
+    "id": "thread-1",
+    "title": "Rust Programming Language Website",
+    "created_at": "2026-03-19T17:58:59Z"
+  },
+  "message": {
+    "id": "msg-1",
+    "thread_id": "thread-1",
+    "state": "done",
+    "prompt": "https://rust-lang.org/\nWhat is this page about?",
+    "markdown": "This page is about the Rust programming language."
+  }
+}
+```
+
+## Examples
+
+### Basic Usage
+
+```bash
+kagi ask-page https://rust-lang.org/ "What is this page about?"
+```
+
+### Extract Only the Answer
+
+```bash
+kagi ask-page https://rust-lang.org/ "What is this page about?" \
+  | jq -r '.message.markdown'
+```
+
+### Continue the Thread in Assistant
+
+```bash
+THREAD_ID=$(
+  kagi ask-page https://rust-lang.org/ "What is this page about?" \
+    | jq -r '.thread.id'
+)
+
+kagi assistant --thread-id "$THREAD_ID" "What learning resources does it mention?"
+```
+
+### Save a Page Analysis
+
+```bash
+kagi ask-page https://example.com "Summarize the main argument" > page-analysis.json
+```
+
+## Error Cases
+
+Typical configuration errors:
+
+```text
+Config error: ask-page URL cannot be empty
+Config error: invalid ask-page URL: relative URL without a base
+Config error: ask-page URL must use http or https, got `file`
+Config error: ask-page question cannot be empty
+```
+
+## Notes
+
+- `ask-page` always starts a new Assistant thread in this version.
+- For follow-up questions, continue the returned thread with `kagi assistant --thread-id ...`.
+- The Assistant response keeps the combined prompt in `message.prompt`, while `source.url` and `source.question` preserve the original CLI inputs separately.

docs/demos.md

@@ -9,6 +9,7 @@ The demo scripts build the local debug binary, expose it as `kagi` through `/tmp
 - `docs/demo-assets/search.gif`
 - `docs/demo-assets/summarize.gif`
 - `docs/demo-assets/news.gif`
+- `docs/demo-assets/ask-page.gif`
 - `docs/demo-assets/assistant.gif`
 
 ## Regenerate
@@ -20,10 +21,12 @@ The current demo commands are:
 - `kagi search --format pretty "obsidian cli daily notes workflow"`
 - `kagi summarize --subscriber --url https://mullvad.net/en/browser | jq -M ...`
 - `kagi news --category tech --limit 1 | jq -M ...`
+- `kagi ask-page https://rust-lang.org/ "What is this page about in one sentence?" | jq -M ...`
+- `kagi assistant "plan a private obsidian workflow for cafe work. give me 3 setup tips and a short checklist." | jq -M ...`
 - `RESPONSE=$(kagi assistant --model gpt-5-mini "..."); THREAD_ID=...; kagi assistant --thread-id "$THREAD_ID" "..."; kagi assistant thread export "$THREAD_ID"`
 
 ```bash
-chmod +x scripts/demo-search.sh scripts/demo-summarize.sh scripts/demo-news.sh scripts/demo-assistant.sh
+chmod +x scripts/demo-search.sh scripts/demo-summarize.sh scripts/demo-news.sh scripts/demo-ask-page.sh scripts/demo-assistant.sh
 
 mkdir -p docs/demo-assets /tmp/kagi-demos
 
@@ -33,11 +36,13 @@ agg --version
 KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-search.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/search.cast
 KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-summarize.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/summarize.cast
 asciinema rec -c ./scripts/demo-news.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/news.cast
+KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-ask-page.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/ask-page.cast
 KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-assistant.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/assistant.cast
 
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/search.cast docs/demo-assets/search.gif
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/summarize.cast docs/demo-assets/summarize.gif
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/news.cast docs/demo-assets/news.gif
+agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/ask-page.cast docs/demo-assets/ask-page.gif
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/assistant.cast docs/demo-assets/assistant.gif
 ```
 

docs/docs.json

@@ -84,6 +84,7 @@
           {
             "group": "AI & Enrichment",
             "pages": [
+              "commands/ask-page",
               "commands/assistant",
               "commands/fastgpt",
               "commands/enrich"

docs/guides/quickstart.mdx

@@ -174,6 +174,9 @@ kagi search --lens 2 "developer documentation"
 # Test Assistant
 kagi assistant "What are the key features of Rust?"
 
+# Ask Assistant about a page
+kagi ask-page https://rust-lang.org/ "What is this page about?"
+
 # List Assistant threads
 kagi assistant thread list
 
@@ -185,6 +188,10 @@ kagi summarize --subscriber --url https://www.rust-lang.org --summary-type keypo
 
 ![Assistant command demo](/images/demos/assistant.gif)
 
+**Ask Page Demo:**
+
+![Ask Page command demo](/images/demos/ask-page.gif)
+
 **Subscriber Summarize Demo:**
 
 ![Summarize command demo](/images/demos/summarize.gif)

docs/index.mdx

@@ -50,6 +50,7 @@ Unlock the full potential of your Kagi subscription:
 - **Lens-Aware Search**: Use your custom Kagi lenses directly from the command line.
 
 - **Assistant Integration**: Prompt Kagi Assistant programmatically, continue conversations, and manage threads across sessions.
+- **Ask Page**: Start a page-focused Assistant thread directly from one URL and one question.
 
 - **Subscriber Features**: Access subscriber-only capabilities like the web-based Summarizer with full control over output length and style.
 
@@ -79,6 +80,7 @@ Two credential types serve different purposes:
 - **FastGPT**: Quick answers powered by Kagi's FastGPT API
 - **Enrichment**: Query specialized web and news indexes
 - **Assistant**: Full conversation support with thread continuation and thread management
+- **Ask Page**: Page-focused Assistant questions with structured output
 
 ### Public Feeds
 
@@ -107,6 +109,7 @@ flowchart TB
         web2["assistant"]
         web3["summarize --subscriber"]
         web4["search (session)"]
+        web5["ask-page"]
     end
 
     subgraph PublicFeeds["Public Feeds (No Auth)"]

docs/llms.txt

@@ -19,6 +19,7 @@
 - [summarize](https://kagi.micr.dev/commands/summarize): Complete reference for *kagi* summarize command - summarize URLs and text using subscriber or public API modes.
 - [news](https://kagi.micr.dev/commands/news): Complete reference for *kagi* news command - fetch Kagi News from public JSON endpoints with category filtering.
 - [smallweb](https://kagi.micr.dev/commands/smallweb): Complete reference for *kagi* smallweb command - fetch the Kagi Small Web feed of independent websites.
+- [ask-page](https://kagi.micr.dev/commands/ask-page): Complete reference for *kagi* ask-page command - ask Kagi Assistant about a specific web page.
 - [assistant](https://kagi.micr.dev/commands/assistant): Complete reference for *kagi* assistant command - interact with Kagi AI Assistant programmatically.
 - [fastgpt](https://kagi.micr.dev/commands/fastgpt): Complete reference for *kagi* fastgpt command - get quick answers using Kagi's FastGPT API.
 - [enrich](https://kagi.micr.dev/commands/enrich): Complete reference for *kagi* enrich command - query Kagi's enrichment indexes for web and news.

docs/project/demos.mdx

@@ -10,6 +10,7 @@ The docs site ships with recorded terminal GIFs from the repo:
 - search
 - subscriber summarize
 - news
+- ask-page
 - assistant
 
 ## Preview
@@ -30,6 +31,10 @@ The docs site ships with recorded terminal GIFs from the repo:
 
 ![Assistant demo](/images/demos/assistant.gif)
 
+### Ask Page
+
+![Ask Page demo](/images/demos/ask-page.gif)
+
 ## Regenerate
 
 Subscriber demos require `KAGI_SESSION_TOKEN`.
@@ -41,17 +46,20 @@ The current demo commands are:
 - `kagi search --format pretty "obsidian cli daily notes workflow"`
 - `kagi summarize --subscriber --url https://mullvad.net/en/browser | jq -M ...`
 - `kagi news --category tech --limit 1 | jq -M ...`
+- `kagi ask-page https://rust-lang.org/ "What is this page about in one sentence?" | jq -M ...`
+- `kagi assistant "plan a private obsidian workflow for cafe work. give me 3 setup tips and a short checklist." | jq -M ...`
 - `RESPONSE=$(kagi assistant --model gpt-5-mini "..."); THREAD_ID=...; kagi assistant --thread-id "$THREAD_ID" "..."; kagi assistant thread export "$THREAD_ID"`
 
 ```bash
-chmod +x scripts/demo-search.sh scripts/demo-summarize.sh scripts/demo-news.sh scripts/demo-assistant.sh
+chmod +x scripts/demo-search.sh scripts/demo-summarize.sh scripts/demo-news.sh scripts/demo-ask-page.sh scripts/demo-assistant.sh
 
 mkdir -p docs/demo-assets /tmp/kagi-demos
 
 agg --version
 KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-search.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/search.cast
 KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-summarize.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/summarize.cast
 asciinema rec -c ./scripts/demo-news.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/news.cast
+KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-ask-page.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/ask-page.cast
 KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-assistant.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/assistant.cast
 ```
 
@@ -63,5 +71,6 @@ Use the official asciinema `agg` binary when exporting GIFs. On this machine, th
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/search.cast docs/demo-assets/search.gif
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/summarize.cast docs/demo-assets/summarize.gif
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/news.cast docs/demo-assets/news.gif
+agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/ask-page.cast docs/demo-assets/ask-page.gif
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/assistant.cast docs/demo-assets/assistant.gif
 ```

docs/reference/auth-matrix.mdx

@@ -19,6 +19,7 @@ This reference provides a complete mapping of which commands require which authe
 | `summarize` | `KAGI_API_TOKEN` | None | Paid public API |
 | `summarize --subscriber` | `KAGI_SESSION_TOKEN` | None | Subscriber web product |
 | `news` | None | None | Public endpoint |
+| `ask-page` | `KAGI_SESSION_TOKEN` | None | Subscriber feature |
 | `assistant` | `KAGI_SESSION_TOKEN` | None | Subscriber feature |
 | `fastgpt` | `KAGI_API_TOKEN` | None | Paid public API |
 | `enrich web` | `KAGI_API_TOKEN` | None | Paid public API |
@@ -102,6 +103,7 @@ flowchart TD
 
 | Command | Token | Purpose |
 |---------|-------|---------|
+| `ask-page` | `KAGI_SESSION_TOKEN` | Ask Assistant about one page URL |
 | `assistant` | `KAGI_SESSION_TOKEN` | Conversational AI with threads |
 | `fastgpt` | `KAGI_API_TOKEN` | Quick factual answers |
 
@@ -130,7 +132,9 @@ Both `enrich web` and `enrich news` require `KAGI_API_TOKEN`:
 Requires `KAGI_SESSION_TOKEN`:
 
 - ✅ Lens-aware search (`--lens`)
+- ✅ Ask Page (`ask-page`)
 - ✅ Kagi Assistant prompt and thread commands (`assistant`)
+- ✅ Ask Page (`ask-page`)
 - ✅ Subscriber Summarizer (`summarize --subscriber`)
 - ✅ Base search (fallback)
 
@@ -206,6 +210,7 @@ kagi auth set --session-token 'https://kagi.com/search?token=...'
 **Working commands:**
 - ✅ `kagi search "query"` (uses session path)
 - ✅ `kagi search --lens 2 "query"`
+- ✅ `kagi ask-page https://example.com "question"`
 - ✅ `kagi assistant "prompt"`
 - ✅ `kagi summarize --subscriber --url ...`
 - ✅ `kagi news`
@@ -233,6 +238,7 @@ kagi auth set --api-token 'your_api_token'
 
 **Non-working:**
 - ❌ `kagi search --lens 2` - requires session token
+- ❌ `kagi ask-page https://example.com "question"` - requires session token
 - ❌ `kagi assistant` - requires session token
 - ❌ `kagi summarize --subscriber` - requires session token
 
@@ -250,6 +256,7 @@ kagi auth set --session-token '...' --api-token '...'
 - `search`: Uses API (preferred), falls back to session if needed
 - `summarize` without `--subscriber`: Uses API
 - `summarize --subscriber`: Uses session
+- `ask-page`: Uses session
 - `assistant`: Uses session
 - `fastgpt`: Uses API