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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: copa-cli
-Version: 0.4.0
+Version: 0.7.0
 Summary: Command Palette — smart command tracking, ranking, and sharing for your shell
 Author: Mark Stanford
 License-Expression: MIT
@@ -46,17 +46,22 @@ Copa tracks the commands you run, ranks them by frequency and recency, and gives
 - **LLM descriptions** — `copa fix --auto` uses Claude or ollama to generate descriptions for undescribed commands
 - **Script protocol** — `#@ Description:` / `#@ Usage:` / `#@ Purpose:` / `#@ Flag:` headers in your scripts are auto-detected by `copa scan` across all `$PATH` directories
 - **Flag documentation** — document command flags with descriptions; flags are searchable, visible in the preview pane, and preserved in `.copa` exports
+- **Inline suggestions** — ghost text appears as you type; Tab accepts or opens a completion menu with the suggestion highlighted
 - **Groups & Ctrl+G** — organize commands by project, device, or workflow; assign groups inline from the fzf palette with Ctrl+G
+- **Bulk operations** — Ctrl+B enters select mode for batch group assignment, batch deletion, or batch LLM description
 - **Sharing & `copa create`** — export/import command sets as `.copa` JSON files; `copa create` scaffolds a `.copa` file from an existing group
 - **Set filtering** — scope list, search, and fzf to a specific shared set with `--set`
 - **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
@@ -82,24 +87,47 @@ pip install -e .
 pip install copa-cli[ollama]
 ```
 
-### Shell integration (required)
+### Setup
+
+Run the interactive setup wizard:
+
+```bash
+copa setup
+```
+
+This walks you through everything:
+1. Checks that **fzf** is installed (tells you how to install if missing)
+2. Creates the Copa database (`~/.copa/copa.db`)
+3. Adds shell integration to your `~/.zshrc` (prompts for confirmation)
+4. Optionally imports your zsh history
 
-Add this line to your `~/.zshrc`:
+Then activate Copa in your current terminal:
 
 ```bash
-eval "$(copa init zsh)"
+source ~/.zshrc
 ```
 
-Then restart your shell or run `source ~/.zshrc`. This does three things:
+### What shell integration does
+
+The `eval "$(copa init zsh)"` line added to your `.zshrc` does three things:
 
 1. **Records every command you run** — a `precmd` hook silently calls `copa _record` in the background after each command, building up frequency and recency data with zero latency impact.
 2. **Replaces Ctrl+R** — the default zsh reverse-history-search is replaced with Copa's fzf-powered command palette (see below).
 3. **Supplements tab completion** — Copa registers as a completer so that any command gets completion candidates from your Copa database. The behavior is configurable (`fallback`, `hybrid`, `always`, or `never`) — see [Tab Completion](#tab-completion).
 
-Initialize the database:
+### Manual setup
+
+If you prefer to set up manually instead of using `copa setup`:
 
 ```bash
-copa _init
+# Add shell integration to ~/.zshrc
+echo 'eval "$(copa init zsh)"' >> ~/.zshrc
+
+# Activate in current terminal
+source ~/.zshrc
+
+# Import your history (optional)
+copa sync
 ```
 
 ## Ctrl+R — fzf Command Palette
@@ -148,11 +176,40 @@ While the fzf palette is open, these keys are available:
 | **Ctrl+N** | Cycle group | Cycles through groups: (all) → group1 → group2 → ... → (all) |
 | **Ctrl+D** | Describe | Generate/edit a description using LLM (with tty-aware input) |
 | **Ctrl+F** | Edit flags | Add flag documentation to the highlighted command |
+| **Ctrl+B** | Select mode | Enter multi-select for bulk operations (see below) |
 | **Ctrl+H** | Toggle header | Show/hide the key hints for more screen space |
 | **ESC** | Cancel/back | In scope/group mode: returns to command list. Otherwise: closes fzf |
 
 Keybindings are configurable via `~/.copa/config.toml`. See [Configuration](#configuration).
 
+### Select mode (bulk operations)
+
+Press **Ctrl+B** from the Ctrl+R palette to enter **select mode**. This opens a new fzf view with multi-select enabled:
+
+- **Tab** toggles selection on individual commands
+- **Ctrl+R** cycles modes (all → frequent → recent) just like the main palette
+- **Enter** confirms your selection and shows the batch action menu
+- **ESC** cancels and returns to your prompt
+
+After selecting commands, Copa shows a batch action menu:
+
+```
+Selected 5 command(s).
+  g = assign group
+  d = delete
+  a = auto-describe (LLM)
+  q = cancel
+Action:
+```
+
+| Action | What it does |
+|--------|-------------|
+| **g** | Assign all selected commands to a group (or clear their group) |
+| **d** | Delete all selected commands (with confirmation) |
+| **a** | Auto-generate descriptions for all selected commands using your configured LLM backend |
+
+This is useful for organizing large command sets — select 20 undescribed commands and batch-describe them, or move a set of related commands into a group in one step.
+
 ### Preview pane
 
 The right side shows a detail card for the highlighted command: full description, usage, purpose, flag documentation, score breakdown, frequency, last used, source, group, shared set, and tags.
@@ -210,9 +267,85 @@ 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
+
+Copa supports two Tab behaviors when a suggestion is showing:
+
+**Menu select** (`tab_accept = 2`, default):
+1. Press **Tab** — ghost text clears, a completion menu opens with the Copa suggestion highlighted at the top, alongside native completions below
+2. Press **Tab** or **Space** — accepts the highlighted item
+3. Press **Escape** — cancels the menu, restores your original text
+4. Use **arrow keys** to navigate if you want a different completion
+
+This gives you a chance to see alternatives before committing. The Copa suggestion is always the first item in the menu.
+
+**Inline accept** (`tab_accept = 1`):
+- Press **Tab** — the suggestion is accepted directly into your command line. One keystroke, done.
+
+### Completion menu navigation
+
+When the completion menu is open (from Tab in `tab_accept = 2` mode or from normal tab completion):
+
+| Key | Action |
+|-----|--------|
+| **Tab** | Accept the highlighted completion |
+| **Space** | Accept the highlighted completion |
+| **Escape** | Cancel — dismiss menu, restore original text |
+| **Arrow keys** | Navigate between completions |
+
+### 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)
+color = 242          # ghost text color (256-color palette, default: 242 mid-grey)
+```
+
+The `color` value is a [256-color palette](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) number. Some useful values: `240` (darker grey), `242` (default mid-grey), `245` (lighter grey), `8` (bright black), `244` (light grey).
+
+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 +355,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 +498,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 +506,37 @@ 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 |
+| [`npm.copa`](examples/npm.copa) | Node.js package management |
+| [`network.copa`](examples/network.copa) | Network diagnostics |
+| [`curl-http.copa`](examples/curl-http.copa) | HTTP requests and API testing |
+| [`ssh-remote.copa`](examples/ssh-remote.copa) | SSH, SCP, and remote server management |
+| [`adb.copa`](examples/adb.copa) | Android Debug Bridge |
+| [`aws.copa`](examples/aws.copa) | AWS CLI cloud infrastructure |
+| [`terraform.copa`](examples/terraform.copa) | Terraform infrastructure-as-code |
+| [`k8s.copa`](examples/k8s.copa) | Kubernetes cluster management |
+| [`systemd.copa`](examples/systemd.copa) | Linux service management |
+| [`sysadmin.copa`](examples/sysadmin.copa) | System administration |
+| [`process-monitoring.copa`](examples/process-monitoring.copa) | Process management and debugging |
+| [`disk-files.copa`](examples/disk-files.copa) | Disk usage and file management |
+| [`tmux.copa`](examples/tmux.copa) | Terminal multiplexer sessions |
+| [`homebrew.copa`](examples/homebrew.copa) | Homebrew package manager (macOS) |
+
+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:
@@ -474,24 +647,66 @@ group = "ctrl-g"            # assign group (inline modal)
 flags = "ctrl-f"            # edit flags
 filter_group = "ctrl-s"     # scope by group (inline modal)
 cycle_group = "ctrl-n"      # cycle through groups
+select = "ctrl-b"           # enter select mode (bulk operations)
 toggle_header = "ctrl-h"    # show/hide key hints
 
 # Tab completion behavior
 [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
+color = 242                 # ghost text color (256-color palette)
+
+# 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
 
 | Command | Purpose |
 |---------|---------|
+| `copa setup` | Interactive setup wizard |
 | `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 +718,8 @@ 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 reset` | Wipe database and start fresh (keeps config) |
+| `copa uninstall` | Remove Copa data and show cleanup steps |
 
 ## How Scoring Works