copa-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{copa_cli-0.4.0 → copa_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copa-cli
-Version: 0.4.0
+Version: 0.6.0
 Summary: Command Palette — smart command tracking, ranking, and sharing for your shell
 Author: Mark Stanford
 License-Expression: MIT
@@ -52,11 +52,14 @@ Copa tracks the commands you run, ranks them by frequency and recency, and gives
 - **MCP server** — expose your commands to Claude Code (or any MCP client)
 - **Zero latency** — precmd hook records usage in the background
 
+> **Note:** Copa requires **zsh**. It is not compatible with bash, fish, or PowerShell.
+
 ## Install
 
 ### Prerequisites
 
 - **Python 3.12+**
+- **zsh** — Copa's shell integration (precmd hooks, ZLE widgets, inline suggestions) is zsh-only
 - **fzf** — required for Ctrl+R command palette
 
 ```bash
@@ -210,9 +213,62 @@ This works automatically once `copa.zsh` is sourced — no extra setup needed. T
 
 Copa's own CLI completions (`copa li<TAB>` → `list`) continue to work as before via Click's built-in completion.
 
+## Inline Suggestions (Ghost Text)
+
+Copa shows grey ghost text after your cursor as you type — the best matching command from your database, ranked by frequency and recency. This works like fish shell's autosuggestions or zsh-autosuggestions, with zero plugin dependencies.
+
+### How it works
+
+As you type, Copa queries its database for commands starting with your current input and displays the highest-scored match as dim grey text after the cursor. The suggestion updates on every keystroke.
+
+```
+$ git pu█sh origin main     ← grey ghost text
+```
+
+### Keybindings
+
+| Key | Suggestion showing | No suggestion |
+|-----|-------------------|---------------|
+| Type chars | Insert char, re-fetch suggestion | Insert char, fetch suggestion |
+| Backspace | Delete char, **latch** (suppress suggestions) | Delete char normally |
+| **Tab** | `tab_accept=1`: accept full suggestion. `tab_accept=2` (default): first Tab highlights suggestion (cyan), second Tab accepts | If latched: unlatch + re-fetch suggestion. Else: normal tab completion |
+| **Down** | Highlight suggestion (enter confirming state) | History navigation |
+| **Right arrow** | Accept one word, re-fetch | Move cursor right |
+| Enter | Clear suggestion, execute | Execute |
+| Esc | Dismiss suggestion | Normal Esc |
+| Up | Clear suggestion, navigate history | History navigation |
+| Ctrl+R | Clear suggestion, open fzf | Open fzf |
+
+### Tab accept mode
+
+By default (`tab_accept = 2`), pressing Tab when a suggestion is showing highlights the ghost text (changes from dim grey to cyan/bold) to indicate it's ready to be accepted. Pressing Tab again accepts it into the buffer. Pressing Esc reverts to dim grey without accepting. This two-step flow gives you a visual confirmation before committing.
+
+Set `tab_accept = 1` to restore the old behavior where a single Tab directly accepts the suggestion.
+
+### Backspace latch
+
+Pressing Backspace clears the current suggestion and **latches** — suppresses further suggestions while you edit. This prevents suggestions from re-appearing as you retype after correcting a mistake. Ctrl+W (backward-kill-word) also latches.
+
+Press **Tab** to unlatch and re-enable suggestions. The next new prompt (Enter) also resets the latch automatically.
+
+### Configuration
+
+```toml
+# ~/.copa/config.toml
+[suggest]
+enabled = true       # set to false to disable inline suggestions
+min_length = 2       # minimum characters before querying (default: 2)
+tab_accept = 2       # 1 = Tab accepts directly, 2 = Tab opens menu first (default)
+```
+
+Inline suggestions are enabled by default. Set `enabled = false` to disable them entirely (zero performance overhead when disabled).
+
 ## Quick Start
 
 ```bash
+# Check your setup
+copa doctor
+
 # Import your shell history
 copa sync
 
@@ -222,15 +278,24 @@ copa add "adb shell cmd bluetooth_manager enable" -d "Enable Bluetooth" -g bluet
 # Add a command with flag documentation
 copa add "flash_all" -d "Flash AOSP build" -f "--wipe: Wipe userdata" -f "-v: Verbose"
 
-# Create a .copa file from a group (or scaffold an empty one)
-copa create -g bluetooth
+# Pin your most important commands to the top
+copa pin 42
+
+# Edit a command's metadata
+copa edit 42 -d "New description" -g mygroup
 
 # List top commands by score
 copa list
 
+# List as JSON (for scripting)
+copa list --json
+
 # Search by keyword
 copa search bluetooth
 
+# Create a .copa file from a group (or scaffold an empty one)
+copa create -g bluetooth
+
 # Auto-promote frequent commands from history
 copa evolve -k 20
 
@@ -356,7 +421,7 @@ copa create -g bluetooth
 copa share export bluetooth -o bluetooth.copa
 ```
 
-Share it with your team (via git, fbsource, or any file share):
+Share it with your team (via git, Slack, or any file share):
 
 ```bash
 copa share load bluetooth.copa
@@ -364,6 +429,27 @@ copa share load /path/to/team/commands.copa
 copa share sync /path/to/team/copa-files/
 ```
 
+### Example shared sets
+
+Copa ships with ready-to-use `.copa` files in the [`examples/`](examples/) directory:
+
+| File | Description |
+|------|-------------|
+| [`git.copa`](examples/git.copa) | Essential Git commands |
+| [`docker.copa`](examples/docker.copa) | Docker container management |
+| [`python-dev.copa`](examples/python-dev.copa) | Python development workflow |
+| [`network.copa`](examples/network.copa) | Network diagnostics |
+| [`adb.copa`](examples/adb.copa) | Android Debug Bridge |
+| [`k8s.copa`](examples/k8s.copa) | Kubernetes cluster management |
+| [`sysadmin.copa`](examples/sysadmin.copa) | System administration |
+
+Load any of them:
+
+```bash
+copa share load examples/git.copa
+copa share load examples/docker.copa
+```
+
 ### Filtering by shared set
 
 Once you've loaded shared sets, you can scope commands to just that set:
@@ -480,6 +566,41 @@ toggle_header = "ctrl-h"    # show/hide key hints
 [completion]
 mode = "fallback"           # fallback | hybrid | always | never
 branding = true             # show "Copa history" group header
+
+# Inline suggestions (ghost text)
+[suggest]
+enabled = true              # set to false to disable
+min_length = 2              # minimum chars before querying
+tab_accept = 2              # 1 = accept directly, 2 = open menu first
+
+# Composition key behavior (continue vs close)
+# "continue" keys re-open fzf so you can chain another command
+# All other composition keys close fzf immediately
+[composition]
+continue = ["pipe", "chain", "redirect"]  # default: |, &&, > re-open fzf
+```
+
+### Composition key behavior
+
+When you press a composition key (like Ctrl-A for `&&`), Copa can either **close fzf** (placing the command + operator in your prompt) or **continue** (appending the operator and re-opening fzf so you can select the next command to chain).
+
+By default, "connector" operators re-open fzf:
+- `pipe` (`|`) — continue
+- `chain` (`&&`) — continue
+- `redirect` (`>`) — continue
+
+And "terminal" operators close fzf:
+- `background` (`&`) — close
+- `merge_output` (`2>&1`) — close
+- `suppress` (`2>/dev/null`) — close
+
+When chaining, the prompt shows your accumulated command: `copa [git pull && ]>`.
+
+To revert to the old behavior (all keys close immediately), set:
+
+```toml
+[composition]
+continue = []
 ```
 
 ## CLI Reference
@@ -487,11 +608,15 @@ branding = true             # show "Copa history" group header
 | Command | Purpose |
 |---------|---------|
 | `copa add "cmd" -d "desc" -g group -f "flag: desc"` | Save a command (with optional flags) |
-| `copa create -g group [-o file]` | Create a .copa file from a group |
-| `copa list [-g group] [-s source] [--set name]` | List by score |
-| `copa search "query" [-g group] [-s source] [--set name]` | FTS search |
+| `copa edit ID [-d desc] [-g group] [-f flags] [--pin]` | Edit a command's metadata |
 | `copa remove ID` | Remove a command |
+| `copa pin ID` | Pin a command to the top |
+| `copa unpin ID` | Unpin a command |
+| `copa list [-g group] [-s source] [--set name] [--json]` | List by score |
+| `copa search "query" [-g group] [--set name] [--json]` | FTS search |
+| `copa create -g group [-o file]` | Create a .copa file from a group |
 | `copa stats` | Usage statistics |
+| `copa doctor` | Check setup and diagnose issues |
 | `copa sync` | Import from zsh history |
 | `copa scan [--dir path]` | Import script metadata from $PATH |
 | `copa evolve [-k 20] [--auto]` | Auto-add frequent commands (with optional LLM descriptions) |
@@ -503,6 +628,7 @@ branding = true             # show "Copa history" group header
 | `copa share list` | List shared sets |
 | `copa share sync DIR` | Sync .copa files from dir |
 | `copa import FILE [-g group]` | Import commands from markdown |
+| `copa uninstall` | Remove Copa data and show cleanup steps |
 
 ## How Scoring Works
 

{copa_cli-0.4.0 → copa_cli-0.6.0}/README.md

@@ -22,11 +22,14 @@ Copa tracks the commands you run, ranks them by frequency and recency, and gives
 - **MCP server** — expose your commands to Claude Code (or any MCP client)
 - **Zero latency** — precmd hook records usage in the background
 
+> **Note:** Copa requires **zsh**. It is not compatible with bash, fish, or PowerShell.
+
 ## Install
 
 ### Prerequisites
 
 - **Python 3.12+**
+- **zsh** — Copa's shell integration (precmd hooks, ZLE widgets, inline suggestions) is zsh-only
 - **fzf** — required for Ctrl+R command palette
 
 ```bash
@@ -180,9 +183,62 @@ This works automatically once `copa.zsh` is sourced — no extra setup needed. T
 
 Copa's own CLI completions (`copa li<TAB>` → `list`) continue to work as before via Click's built-in completion.
 
+## Inline Suggestions (Ghost Text)
+
+Copa shows grey ghost text after your cursor as you type — the best matching command from your database, ranked by frequency and recency. This works like fish shell's autosuggestions or zsh-autosuggestions, with zero plugin dependencies.
+
+### How it works
+
+As you type, Copa queries its database for commands starting with your current input and displays the highest-scored match as dim grey text after the cursor. The suggestion updates on every keystroke.
+
+```
+$ git pu█sh origin main     ← grey ghost text
+```
+
+### Keybindings
+
+| Key | Suggestion showing | No suggestion |
+|-----|-------------------|---------------|
+| Type chars | Insert char, re-fetch suggestion | Insert char, fetch suggestion |
+| Backspace | Delete char, **latch** (suppress suggestions) | Delete char normally |
+| **Tab** | `tab_accept=1`: accept full suggestion. `tab_accept=2` (default): first Tab highlights suggestion (cyan), second Tab accepts | If latched: unlatch + re-fetch suggestion. Else: normal tab completion |
+| **Down** | Highlight suggestion (enter confirming state) | History navigation |
+| **Right arrow** | Accept one word, re-fetch | Move cursor right |
+| Enter | Clear suggestion, execute | Execute |
+| Esc | Dismiss suggestion | Normal Esc |
+| Up | Clear suggestion, navigate history | History navigation |
+| Ctrl+R | Clear suggestion, open fzf | Open fzf |
+
+### Tab accept mode
+
+By default (`tab_accept = 2`), pressing Tab when a suggestion is showing highlights the ghost text (changes from dim grey to cyan/bold) to indicate it's ready to be accepted. Pressing Tab again accepts it into the buffer. Pressing Esc reverts to dim grey without accepting. This two-step flow gives you a visual confirmation before committing.
+
+Set `tab_accept = 1` to restore the old behavior where a single Tab directly accepts the suggestion.
+
+### Backspace latch
+
+Pressing Backspace clears the current suggestion and **latches** — suppresses further suggestions while you edit. This prevents suggestions from re-appearing as you retype after correcting a mistake. Ctrl+W (backward-kill-word) also latches.
+
+Press **Tab** to unlatch and re-enable suggestions. The next new prompt (Enter) also resets the latch automatically.
+
+### Configuration
+
+```toml
+# ~/.copa/config.toml
+[suggest]
+enabled = true       # set to false to disable inline suggestions
+min_length = 2       # minimum characters before querying (default: 2)
+tab_accept = 2       # 1 = Tab accepts directly, 2 = Tab opens menu first (default)
+```
+
+Inline suggestions are enabled by default. Set `enabled = false` to disable them entirely (zero performance overhead when disabled).
+
 ## Quick Start
 
 ```bash
+# Check your setup
+copa doctor
+
 # Import your shell history
 copa sync
 
@@ -192,15 +248,24 @@ copa add "adb shell cmd bluetooth_manager enable" -d "Enable Bluetooth" -g bluet
 # Add a command with flag documentation
 copa add "flash_all" -d "Flash AOSP build" -f "--wipe: Wipe userdata" -f "-v: Verbose"
 
-# Create a .copa file from a group (or scaffold an empty one)
-copa create -g bluetooth
+# Pin your most important commands to the top
+copa pin 42
+
+# Edit a command's metadata
+copa edit 42 -d "New description" -g mygroup
 
 # List top commands by score
 copa list
 
+# List as JSON (for scripting)
+copa list --json
+
 # Search by keyword
 copa search bluetooth
 
+# Create a .copa file from a group (or scaffold an empty one)
+copa create -g bluetooth
+
 # Auto-promote frequent commands from history
 copa evolve -k 20
 
@@ -326,7 +391,7 @@ copa create -g bluetooth
 copa share export bluetooth -o bluetooth.copa
 ```
 
-Share it with your team (via git, fbsource, or any file share):
+Share it with your team (via git, Slack, or any file share):
 
 ```bash
 copa share load bluetooth.copa
@@ -334,6 +399,27 @@ copa share load /path/to/team/commands.copa
 copa share sync /path/to/team/copa-files/
 ```
 
+### Example shared sets
+
+Copa ships with ready-to-use `.copa` files in the [`examples/`](examples/) directory:
+
+| File | Description |
+|------|-------------|
+| [`git.copa`](examples/git.copa) | Essential Git commands |
+| [`docker.copa`](examples/docker.copa) | Docker container management |
+| [`python-dev.copa`](examples/python-dev.copa) | Python development workflow |
+| [`network.copa`](examples/network.copa) | Network diagnostics |
+| [`adb.copa`](examples/adb.copa) | Android Debug Bridge |
+| [`k8s.copa`](examples/k8s.copa) | Kubernetes cluster management |
+| [`sysadmin.copa`](examples/sysadmin.copa) | System administration |
+
+Load any of them:
+
+```bash
+copa share load examples/git.copa
+copa share load examples/docker.copa
+```
+
 ### Filtering by shared set
 
 Once you've loaded shared sets, you can scope commands to just that set:
@@ -450,6 +536,41 @@ toggle_header = "ctrl-h"    # show/hide key hints
 [completion]
 mode = "fallback"           # fallback | hybrid | always | never
 branding = true             # show "Copa history" group header
+
+# Inline suggestions (ghost text)
+[suggest]
+enabled = true              # set to false to disable
+min_length = 2              # minimum chars before querying
+tab_accept = 2              # 1 = accept directly, 2 = open menu first
+
+# Composition key behavior (continue vs close)
+# "continue" keys re-open fzf so you can chain another command
+# All other composition keys close fzf immediately
+[composition]
+continue = ["pipe", "chain", "redirect"]  # default: |, &&, > re-open fzf
+```
+
+### Composition key behavior
+
+When you press a composition key (like Ctrl-A for `&&`), Copa can either **close fzf** (placing the command + operator in your prompt) or **continue** (appending the operator and re-opening fzf so you can select the next command to chain).
+
+By default, "connector" operators re-open fzf:
+- `pipe` (`|`) — continue
+- `chain` (`&&`) — continue
+- `redirect` (`>`) — continue
+
+And "terminal" operators close fzf:
+- `background` (`&`) — close
+- `merge_output` (`2>&1`) — close
+- `suppress` (`2>/dev/null`) — close
+
+When chaining, the prompt shows your accumulated command: `copa [git pull && ]>`.
+
+To revert to the old behavior (all keys close immediately), set:
+
+```toml
+[composition]
+continue = []
 ```
 
 ## CLI Reference
@@ -457,11 +578,15 @@ branding = true             # show "Copa history" group header
 | Command | Purpose |
 |---------|---------|
 | `copa add "cmd" -d "desc" -g group -f "flag: desc"` | Save a command (with optional flags) |
-| `copa create -g group [-o file]` | Create a .copa file from a group |
-| `copa list [-g group] [-s source] [--set name]` | List by score |
-| `copa search "query" [-g group] [-s source] [--set name]` | FTS search |
+| `copa edit ID [-d desc] [-g group] [-f flags] [--pin]` | Edit a command's metadata |
 | `copa remove ID` | Remove a command |
+| `copa pin ID` | Pin a command to the top |
+| `copa unpin ID` | Unpin a command |
+| `copa list [-g group] [-s source] [--set name] [--json]` | List by score |
+| `copa search "query" [-g group] [--set name] [--json]` | FTS search |
+| `copa create -g group [-o file]` | Create a .copa file from a group |
 | `copa stats` | Usage statistics |
+| `copa doctor` | Check setup and diagnose issues |
 | `copa sync` | Import from zsh history |
 | `copa scan [--dir path]` | Import script metadata from $PATH |
 | `copa evolve [-k 20] [--auto]` | Auto-add frequent commands (with optional LLM descriptions) |
@@ -473,6 +598,7 @@ branding = true             # show "Copa history" group header
 | `copa share list` | List shared sets |
 | `copa share sync DIR` | Sync .copa files from dir |
 | `copa import FILE [-g group]` | Import commands from markdown |
+| `copa uninstall` | Remove Copa data and show cleanup steps |
 
 ## How Scoring Works
 

{copa_cli-0.4.0 → copa_cli-0.6.0}/copa/cli.py

@@ -2,14 +2,41 @@
 
 from __future__ import annotations
 
+import json
+import shutil
 import sys
 from pathlib import Path
 
 import click
 
 from .cli_common import complete_group, complete_shared_set, complete_source, get_db
+from .models import Command
 from .scoring import rank_commands
 
+
+def _cmd_to_json(cmd: Command) -> dict:
+    """Convert a Command to a JSON-serializable dict."""
+    d: dict = {
+        "id": cmd.id,
+        "command": cmd.command,
+        "description": cmd.description,
+        "frequency": cmd.frequency,
+        "score": round(cmd.score, 2),
+        "source": cmd.source,
+    }
+    if cmd.group_name:
+        d["group"] = cmd.group_name
+    if cmd.shared_set:
+        d["shared_set"] = cmd.shared_set
+    if cmd.is_pinned:
+        d["pinned"] = True
+    if cmd.tags:
+        d["tags"] = cmd.tags
+    if cmd.flags:
+        d["flags"] = cmd.flags
+    return d
+
+
 # --- Main group ---
 
 
@@ -127,7 +154,15 @@ def add(command: str, description: str, group: str | None, tag: tuple[str, ...],
 @click.option("-s", "--source", default=None, help="Filter by source.", shell_complete=complete_source)
 @click.option("--set", "shared_set", default=None, help="Filter by shared set.", shell_complete=complete_shared_set)
 @click.option("--needs-desc", is_flag=True, help="Show only commands needing description.")
-def list_cmd(group: str | None, limit: int, source: str | None, shared_set: str | None, needs_desc: bool):
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def list_cmd(
+    group: str | None,
+    limit: int,
+    source: str | None,
+    shared_set: str | None,
+    needs_desc: bool,
+    as_json: bool,
+):
     """List commands ranked by score."""
     db = get_db()
     commands = db.list_commands(
@@ -139,7 +174,14 @@ def list_cmd(group: str | None, limit: int, source: str | None, shared_set: str
     )
     ranked = rank_commands(commands)
     if not ranked:
-        click.echo("No commands found.")
+        if as_json:
+            click.echo("[]")
+        else:
+            click.echo("No commands found.")
+        return
+
+    if as_json:
+        click.echo(json.dumps([_cmd_to_json(c) for c in ranked], indent=2))
         return
 
     for cmd in ranked:
@@ -170,13 +212,21 @@ def list_cmd(group: str | None, limit: int, source: str | None, shared_set: str
 @click.option("-s", "--source", default=None, help="Filter by source.", shell_complete=complete_source)
 @click.option("--set", "shared_set", default=None, help="Filter by shared set.", shell_complete=complete_shared_set)
 @click.option("-n", "--limit", default=20, help="Max results.")
-def search(query: str, group: str | None, source: str | None, shared_set: str | None, limit: int):
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def search(query: str, group: str | None, source: str | None, shared_set: str | None, limit: int, as_json: bool):
     """Search commands by keyword (FTS)."""
     db = get_db()
     commands = db.search_commands(query, group_name=group, source=source, shared_set=shared_set, limit=limit)
     ranked = rank_commands(commands)
     if not ranked:
-        click.echo(f"No commands matching '{query}'.")
+        if as_json:
+            click.echo("[]")
+        else:
+            click.echo(f"No commands matching '{query}'.")
+        return
+
+    if as_json:
+        click.echo(json.dumps([_cmd_to_json(c) for c in ranked], indent=2))
         return
 
     for cmd in ranked:
@@ -261,6 +311,148 @@ def scan(directory: str | None):
     click.echo(f"Scanned: {added} scripts added.")
 
 
+# --- pin / unpin ---
+
+
+@cli.command()
+@click.argument("cmd_id", type=int)
+def pin(cmd_id: int):
+    """Pin a command so it always appears at the top."""
+    db = get_db()
+    cmd = db.get_command(cmd_id)
+    if not cmd:
+        click.echo(f"Command {cmd_id} not found.", err=True)
+        sys.exit(1)
+    db.pin_command(cmd_id, True)
+    click.echo(f"Pinned [{cmd_id}]: {cmd.command}")
+
+
+@cli.command()
+@click.argument("cmd_id", type=int)
+def unpin(cmd_id: int):
+    """Unpin a command."""
+    db = get_db()
+    cmd = db.get_command(cmd_id)
+    if not cmd:
+        click.echo(f"Command {cmd_id} not found.", err=True)
+        sys.exit(1)
+    db.pin_command(cmd_id, False)
+    click.echo(f"Unpinned [{cmd_id}]: {cmd.command}")
+
+
+# --- edit ---
+
+
+@cli.command()
+@click.argument("cmd_id", type=int)
+@click.option("-d", "--description", default=None, help="New description.")
+@click.option("-g", "--group", default=None, help="New group name (use '' to clear).", shell_complete=complete_group)
+@click.option("-f", "--flag", multiple=True, help="Flag docs as 'flag: description' (repeatable, replaces all flags).")
+@click.option("-p", "--pin/--no-pin", default=None, help="Pin or unpin the command.")
+def edit(cmd_id: int, description: str | None, group: str | None, flag: tuple[str, ...], pin: bool | None):
+    """Edit a command's metadata by ID."""
+    db = get_db()
+    cmd = db.get_command(cmd_id)
+    if not cmd:
+        click.echo(f"Command {cmd_id} not found.", err=True)
+        sys.exit(1)
+
+    changes = []
+    if description is not None:
+        db.update_description(cmd_id, description)
+        changes.append(f"description: {description}")
+    if group is not None:
+        group_name = group if group else None
+        db.update_group(cmd_id, group_name)
+        changes.append(f"group: {group_name or '(none)'}")
+    if flag:
+        flags: dict[str, str] = {}
+        for f in flag:
+            parts = f.split(":", 1)
+            flag_name = parts[0].strip()
+            flag_desc = parts[1].strip() if len(parts) > 1 else ""
+            flags[flag_name] = flag_desc
+        db.update_flags(cmd_id, flags)
+        changes.append(f"flags: {len(flags)} documented")
+    if pin is not None:
+        db.pin_command(cmd_id, pin)
+        changes.append("pinned" if pin else "unpinned")
+
+    if not changes:
+        click.echo(f"[{cmd_id}] {cmd.command} — nothing to change (use -d, -g, -f, or --pin)")
+        return
+
+    click.echo(f"Updated [{cmd_id}]: {cmd.command}")
+    for c in changes:
+        click.echo(f"  → {c}")
+
+
+# --- doctor ---
+
+
+@cli.command()
+def doctor():
+    """Check Copa setup and diagnose common issues."""
+    ok_mark = click.style("OK", fg="green")
+    warn_mark = click.style("!!", fg="yellow")
+    fail_mark = click.style("FAIL", fg="red")
+
+    click.echo("Copa Doctor\n")
+
+    # 1. Database
+    db_path = Path.home() / ".copa" / "copa.db"
+    if db_path.is_file():
+        size = db_path.stat().st_size
+        click.echo(f"  [{ok_mark}] Database: {db_path} ({size:,} bytes)")
+        db = get_db()
+        s = db.get_stats()
+        click.echo(f"       {s['total_commands']} commands, {s['total_groups']} groups, {s['shared_sets']} shared sets")
+    else:
+        click.echo(f"  [{fail_mark}] Database: not found at {db_path}")
+        click.echo("       Run: copa _init")
+
+    # 2. fzf
+    if shutil.which("fzf"):
+        click.echo(f"  [{ok_mark}] fzf: installed")
+    else:
+        click.echo(f"  [{fail_mark}] fzf: not found")
+        click.echo("       Install: brew install fzf")
+
+    # 3. Shell integration
+    zshrc = Path.home() / ".zshrc"
+    if zshrc.is_file() and "copa init zsh" in zshrc.read_text():
+        click.echo(f"  [{ok_mark}] Shell integration: found in ~/.zshrc")
+    else:
+        click.echo(f"  [{warn_mark}] Shell integration: not detected in ~/.zshrc")
+        click.echo('       Add: eval "$(copa init zsh)"')
+
+    # 4. LLM backend
+    if db_path.is_file():
+        db = get_db()
+        backend = db.get_meta("llm_backend")
+        if backend:
+            click.echo(f"  [{ok_mark}] LLM backend: {backend}")
+            if backend == "ollama":
+                model = db.get_meta("ollama_model") or "llama3.2:3b"
+                click.echo(f"       Model: {model}")
+        else:
+            click.echo(f"  [{warn_mark}] LLM backend: not configured")
+            click.echo("       Run: copa configure")
+
+    # 5. Completion mode
+    config_path = Path.home() / ".copa" / "config.toml"
+    if config_path.is_file():
+        from .config import load_config
+
+        cfg = load_config(config_path)
+        mode = cfg.get("_completion_mode", "fallback")
+        click.echo(f"  [{ok_mark}] Completion mode: {mode}")
+    else:
+        click.echo(f"  [{ok_mark}] Completion mode: fallback (default)")
+
+    click.echo()
+
+
 # --- Register extracted command modules ---
 
 from . import cli_internal, cli_llm, cli_share