feat(cli): add auth fallback, completion install, and assistant streaming

README.md

@@ -157,6 +157,7 @@ notes:
 - environment variables override `.kagi.toml`
 - base `kagi search` defaults to the session-token path when both credentials are present
 - set `[auth] preferred_auth = "api"` if you want base search to prefer the API path instead
+- API-first base search falls back to the session-token path when the API key is rejected, including quota and rate-limit failures
 - `search --lens`, `--time`, `--order`, `--verbatim`, and personalization flags require `KAGI_SESSION_TOKEN`
 - `search --region`, `--from-date`, and `--to-date` use V1 API filters when routed through `KAGI_API_KEY`
 - `auth check` validates the selected primary credential without using search fallback logic
@@ -170,6 +171,7 @@ for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.
 | `kagi search` | search Kagi with `json` by default, or render as `toon`, `pretty`, `compact`, `markdown`, or `csv` |
 | `kagi batch` | run multiple searches in parallel with JSON, TOON, compact, pretty, markdown, or csv output and shared filters |
 | `kagi auth` | launch the auth wizard, or inspect, validate, and save credentials |
+| `kagi completion` | generate or install shell completions for bash, zsh, fish, or PowerShell |
 | `kagi summarize` | use the paid public summarizer API or the subscriber summarizer with `--subscriber` |
 | `kagi extract` | extract a page's full content as markdown through the current paid API, using `KAGI_API_KEY` directly |
 | `kagi watch` | rerun a search on an interval and emit added/removed result URLs |
@@ -193,22 +195,31 @@ for automation, stdout stays JSON by default. Use `--format toon` for token-effi
 
 ## shell completion
 
-generate a completion script and install it with your shell of choice:
+install completions automatically for your detected shell:
+
+```bash
+kagi completion install
+kagi completion install --shell fish
+```
+
+or generate a completion script and install it yourself:
 
 ```bash
 # bash
-kagi --generate-completion bash > ~/.local/share/bash-completion/completions/kagi
+kagi completion generate bash > ~/.local/share/bash-completion/completions/kagi
 
 # zsh
-kagi --generate-completion zsh > ~/.zsh/completion/_kagi
+kagi completion generate zsh > ~/.zsh/completions/_kagi
 
 # fish
-kagi --generate-completion fish > ~/.config/fish/completions/kagi.fish
+kagi completion generate fish > ~/.config/fish/completions/kagi.fish
 
 # powershell
-kagi --generate-completion powershell >> $PROFILE
+kagi completion generate powershell >> $PROFILE
 ```
 
+`kagi --generate-completion <shell>` remains available as a shortcut for script generation.
+
 see the [installation guide](https://kagi.micr.dev/guides/installation) for platform-specific setup details.
 
 ## examples
@@ -296,6 +307,8 @@ continue research with assistant:
 
 ```bash
 kagi assistant "plan a focused research session in the terminal"
+kagi assistant --stream "write a short implementation plan"
+kagi assistant --stream --stream-output json "write a short implementation plan"
 ```
 
 run assistant with a saved assistant profile and markdown output:

docs/SKILL.md

@@ -180,6 +180,12 @@ kagi assistant --thread-id "<thread-id>" "Give me an example"
 # Use a saved assistant profile with prompt overrides
 kagi assistant --assistant research --model gpt-5-mini --web-access --no-personalized "Summarize the latest Rust release"
 
+# Stream markdown deltas as they arrive
+kagi assistant --stream "Explain quantum computing"
+
+# Stream structured events for scripts
+kagi assistant --stream --stream-output json "Explain quantum computing"
+
 # List threads
 kagi assistant thread list
 
@@ -344,20 +350,27 @@ kagi search "query" --format csv > results.csv
 
 ## Shell Completions
 
+Install completions for the detected shell:
+
+```bash
+kagi completion install
+kagi completion install --shell fish
+```
+
 Generate completion scripts for Bash, Zsh, Fish, and PowerShell:
 
 ```bash
 # Bash
-kagi --generate-completion bash > ~/.local/share/bash-completion/completions/kagi
+kagi completion generate bash > ~/.local/share/bash-completion/completions/kagi
 
 # Zsh
-kagi --generate-completion zsh > ~/.zsh/completion/_kagi
+kagi completion generate zsh > ~/.zsh/completions/_kagi
 
 # Fish
-kagi --generate-completion fish > ~/.config/fish/completions/kagi.fish
+kagi completion generate fish > ~/.config/fish/completions/kagi.fish
 
 # PowerShell
-kagi --generate-completion powershell >> $PROFILE
+kagi completion generate powershell >> $PROFILE
 ```
 
 ## Common Workflows

docs/commands/assistant.mdx

@@ -13,6 +13,7 @@ Prompt Kagi Assistant, continue an existing thread, use a saved assistant profil
 
 ```bash
 kagi assistant [OPTIONS] <QUERY>
+kagi assistant --stream [--stream-output text|json] <QUERY>
 kagi assistant thread list
 kagi assistant thread get <THREAD_ID>
 kagi assistant thread delete <THREAD_ID>
@@ -79,6 +80,29 @@ kagi assistant --format markdown "Write a release summary"
 
 Disable ANSI colors in `--format pretty`.
 
+#### `--stream`
+
+Stream Assistant output as it arrives instead of waiting for the final response. By default this writes incremental markdown deltas to stdout and flushes after each update:
+
+```bash
+kagi assistant --stream "Write a 3-line release note"
+```
+
+Use JSON mode when a script needs structured stream events:
+
+```bash
+kagi assistant --stream --stream-output json "Write a 3-line release note"
+```
+
+#### `--stream-output <MODE>`
+
+Select the streamed output mode. This option requires `--stream`.
+
+Possible values:
+
+- `text` - default, prints only incremental markdown deltas
+- `json` - newline-delimited compact JSON events with `md_delta`, `thread`, `message`, and `meta`
+
 #### `--model <MODEL>`
 
 Override the model slug for a single prompt.

docs/commands/completion.mdx

@@ -0,0 +1,69 @@
+---
+title: "completion"
+description: "Complete reference for *kagi* completion command - generate and install shell completion scripts."
+---
+
+# `kagi completion`
+
+Generate or install shell completion scripts for `kagi`.
+
+## Synopsis
+
+```bash
+kagi completion generate <SHELL>
+kagi completion install [--shell <SHELL>] [--dir <DIR>]
+```
+
+Supported shells:
+
+- `bash`
+- `zsh`
+- `fish`
+- `powershell`
+
+## `kagi completion install`
+
+Install a completion script for your active shell. When `--shell` is omitted, `kagi` detects the shell from environment variables such as `SHELL`.
+
+```bash
+kagi completion install
+```
+
+Choose the shell explicitly when detection is unavailable or when installing for a different shell:
+
+```bash
+kagi completion install --shell bash
+kagi completion install --shell zsh
+kagi completion install --shell fish
+kagi completion install --shell powershell
+```
+
+Default install targets:
+
+| Shell | Target |
+| --- | --- |
+| bash | `$XDG_DATA_HOME/bash-completion/completions/kagi`, or `~/.local/share/bash-completion/completions/kagi` |
+| zsh | `~/.zsh/completions/_kagi` |
+| fish | `$XDG_CONFIG_HOME/fish/completions/kagi.fish`, or `~/.config/fish/completions/kagi.fish` |
+| powershell | `$XDG_CONFIG_HOME/powershell/kagi-completions.ps1`, or `~/.config/powershell/kagi-completions.ps1` |
+
+For zsh, the installer also adds the completion directory to `~/.zshrc` and ensures `compinit` is loaded. For PowerShell, it adds a dot-source line to the standard profile path under the same config directory.
+
+Use `--dir` to write the completion file somewhere else:
+
+```bash
+kagi completion install --shell fish --dir ./completions
+```
+
+## `kagi completion generate`
+
+Print a completion script to stdout without changing any files:
+
+```bash
+kagi completion generate bash > ~/.local/share/bash-completion/completions/kagi
+kagi completion generate zsh > ~/.zsh/completions/_kagi
+kagi completion generate fish > ~/.config/fish/completions/kagi.fish
+kagi completion generate powershell >> $PROFILE
+```
+
+`kagi --generate-completion <SHELL>` is still available as a shortcut for script generation.

docs/commands/search.mdx

@@ -39,7 +39,7 @@ Plain base search keeps the existing repo behavior:
 
 - default session-first search when a session token is available
 - API-first only when you configure `[auth.preferred_auth] = "api"` and provide `KAGI_API_KEY`
-- session fallback only when the API path was selected first and rejected
+- session fallback only when the API path was selected first and rejected, including `429 Too Many Requests` and quota-style API failures
 
 ### Session-Only Search Options
 

docs/guides/installation.mdx

@@ -369,19 +369,31 @@ The binary is statically linked and has no runtime dependencies beyond the Linux
 
 **Shell Completion:**
 
-To enable tab completion, add to your shell configuration:
+To enable tab completion, install a generated completion script for your detected shell:
 
 ```bash
-# Bash (~/.bashrc)
-eval "$(kagi --generate-completion bash)"
+kagi completion install
+```
 
-# Zsh (~/.zshrc)
-eval "$(kagi --generate-completion zsh)"
+You can also choose the shell explicitly:
 
-# Fish (~/.config/fish/config.fish)
-kagi --generate-completion fish | source
+```bash
+kagi completion install --shell bash
+kagi completion install --shell zsh
+kagi completion install --shell fish
+kagi completion install --shell powershell
 ```
 
+For manual installs, write the generated script yourself:
+
+```bash
+kagi completion generate bash > ~/.local/share/bash-completion/completions/kagi
+kagi completion generate zsh > ~/.zsh/completions/_kagi
+kagi completion generate fish > ~/.config/fish/completions/kagi.fish
+```
+
+The older `kagi --generate-completion <shell>` shortcut still prints the generated script to stdout.
+
 ### Windows
 
 **PowerShell Execution Policy:**

docs/llms.txt

@@ -16,6 +16,7 @@
 
 - [search](https://kagi.micr.dev/commands/search): Complete reference for *kagi* search command - syntax, flags, authentication, output formats, and real-world examples.
 - [auth](https://kagi.micr.dev/commands/auth): Complete reference for *kagi* auth command - credential management, validation, and configuration.
+- [completion](https://kagi.micr.dev/commands/completion): Complete reference for *kagi* completion command - generate and install shell completion scripts.
 - [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.

docs/reference/coverage.mdx

@@ -78,6 +78,7 @@ These require no authentication:
 | `batch` | Parallel search with shared search options | API or Session | ✅ |
 | `batch` via stdin | Parallel search from stdin lines | API or Session | ✅ |
 | `auth` | Credential management | None | ✅ |
+| `completion` | Generate and install shell completions | None | Implemented |
 | `--profile` | Named auth profiles from `.kagi.toml` | None | ✅ |
 | `summarize` | Public API summarizer | API | ✅ |
 | `summarize --subscriber` | Web summarizer | Session | ✅ |

docs/reference/output-contract.mdx

@@ -164,6 +164,8 @@ Subscriber mode:
 }
 ```
 
+`kagi assistant --stream` writes incremental markdown deltas to stdout and flushes after each update. `kagi assistant --stream --stream-output json` writes the same stream as newline-delimited compact JSON events with an `md_delta` field plus the current `meta`, `thread`, and `message` snapshot.
+
 ### `kagi assistant custom`
 
 `list` returns an array of assistant summaries:

src/cli.rs

@@ -17,6 +17,15 @@ pub enum CompletionShell {
     PowerShell,
 }
 
+#[derive(Debug, Clone, ValueEnum)]
+/// Output mode for streamed assistant prompt updates.
+pub enum AssistantStreamOutput {
+    /// Write only incremental markdown deltas to stdout.
+    Text,
+    /// Write each stream update as one compact JSON object per line.
+    Json,
+}
+
 #[derive(Debug, Clone, ValueEnum)]
 /// Output format for assistant thread exports.
 pub enum AssistantThreadExportFormat {
@@ -251,6 +260,8 @@ pub enum Commands {
     History(HistoryCommand),
     /// Manage local domain preferences used by CLI search output
     SitePref(SitePrefCommand),
+    /// Generate or install shell completion scripts
+    Completion(CompletionCommand),
     /// Manage Kagi search lenses
     Lens(LensCommand),
     /// Manage custom bangs
@@ -551,6 +562,42 @@ pub struct AuthSetArgs {
     pub session_token: Option<String>,
 }
 
+#[derive(Debug, Args)]
+/// Arguments for the `completion` command group.
+pub struct CompletionCommand {
+    #[command(subcommand)]
+    pub command: CompletionSubcommand,
+}
+
+#[derive(Debug, Subcommand)]
+/// Subcommands for shell completion management.
+pub enum CompletionSubcommand {
+    /// Print a completion script to stdout
+    Generate(CompletionGenerateArgs),
+    /// Install a completion script for the active shell
+    Install(CompletionInstallArgs),
+}
+
+#[derive(Debug, Args)]
+/// Arguments for `completion generate`.
+pub struct CompletionGenerateArgs {
+    /// Shell to generate completions for
+    #[arg(value_name = "SHELL", value_enum)]
+    pub shell: CompletionShell,
+}
+
+#[derive(Debug, Args)]
+/// Arguments for `completion install`.
+pub struct CompletionInstallArgs {
+    /// Shell to install completions for; detected from SHELL when omitted
+    #[arg(long, value_name = "SHELL", value_enum)]
+    pub shell: Option<CompletionShell>,
+
+    /// Override the completion directory
+    #[arg(long, value_name = "DIR")]
+    pub dir: Option<PathBuf>,
+}
+
 #[derive(Debug, Args)]
 /// Arguments for the `summarize` subcommand.
 pub struct SummarizeArgs {
@@ -755,10 +802,14 @@ pub struct AssistantArgs {
     #[arg(long, value_name = "FORMAT", default_value_t = AssistantOutputFormat::Json)]
     pub format: AssistantOutputFormat,
 
-    /// Emit prompt updates as newline-delimited JSON
+    /// Stream prompt updates as text deltas or newline-delimited JSON
     #[arg(long, conflicts_with = "export")]
     pub stream: bool,
 
+    /// Stream output mode used with --stream
+    #[arg(long, value_name = "MODE", value_enum, default_value_t = AssistantStreamOutput::Text, requires = "stream")]
+    pub stream_output: AssistantStreamOutput,
+
     /// Disable colored terminal output (only affects pretty format)
     #[arg(long)]
     pub no_color: bool,