agent-cli 0.70.2__py3-none-any.whl → 0.72.1__py3-none-any.whl

agent_cli/install/extras.py

@@ -14,7 +14,7 @@ import typer
 
 from agent_cli.cli import app
 from agent_cli.core.deps import EXTRAS as _EXTRAS_META
-from agent_cli.core.utils import console, print_error_message
+from agent_cli.core.utils import console, err_console, print_error_message
 
 # Extract descriptions from the centralized EXTRAS metadata
 EXTRAS: dict[str, str] = {name: desc for name, (desc, _) in _EXTRAS_META.items()}
@@ -69,7 +69,8 @@ def _install_via_uv_tool(extras: list[str], *, quiet: bool = False) -> bool:
     cmd = ["uv", "tool", "install", package_spec, "--force", "--python", python_version]
     if quiet:
         cmd.append("-q")
-    console.print(f"Running: [cyan]{' '.join(cmd)}[/]")
+    # Use stderr for status messages so they don't pollute stdout (e.g., for hotkey notifications)
+    err_console.print(f"Running: [cyan]{' '.join(cmd)}[/]")
     result = subprocess.run(cmd, check=False)
     return result.returncode == 0
 
@@ -118,29 +119,59 @@ def install_extras_programmatic(extras: list[str], *, quiet: bool = False) -> bo
     valid = [e for e in extras if e in available]
     invalid = [e for e in extras if e not in available]
     if invalid:
-        console.print(f"[yellow]Unknown extras (skipped): {', '.join(invalid)}[/]")
+        # Use stderr so warning doesn't pollute stdout (e.g., for hotkey notifications)
+        err_console.print(f"[yellow]Unknown extras (skipped): {', '.join(invalid)}[/]")
     return bool(valid) and _install_extras_impl(valid, quiet=quiet)
 
 
 @app.command("install-extras", rich_help_panel="Installation", no_args_is_help=True)
 def install_extras(
-    extras: Annotated[list[str] | None, typer.Argument(help="Extras to install")] = None,
+    extras: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="Extras to install: `rag`, `memory`, `vad`, `audio`, `piper`, `kokoro`, "
+            "`faster-whisper`, `mlx-whisper`, `wyoming`, `server`, `speed`, `llm`",
+        ),
+    ] = None,
     list_extras: Annotated[
         bool,
-        typer.Option("--list", "-l", help="List available extras"),
+        typer.Option(
+            "--list",
+            "-l",
+            help="Show available extras with descriptions (what each one enables)",
+        ),
     ] = False,
     all_extras: Annotated[
         bool,
-        typer.Option("--all", "-a", help="Install all available extras"),
+        typer.Option("--all", "-a", help="Install all available extras at once"),
     ] = False,
 ) -> None:
-    """Install optional extras (rag, memory, vad, etc.) with pinned versions.
-
-    Examples:
-        - `agent-cli install-extras rag`           # Install RAG dependencies
-        - `agent-cli install-extras memory vad`    # Install multiple extras
-        - `agent-cli install-extras --list`        # Show available extras
-        - `agent-cli install-extras --all`         # Install all extras
+    """Install optional dependencies with pinned, compatible versions.
+
+    Many agent-cli features require optional dependencies. This command installs
+    them with version pinning to ensure compatibility. Dependencies persist
+    across `uv tool upgrade` when installed via `uv tool`.
+
+    **Available extras:**
+    - `rag` - RAG proxy server (ChromaDB, embeddings)
+    - `memory` - Long-term memory proxy (ChromaDB)
+    - `vad` - Voice Activity Detection (silero-vad)
+    - `audio` - Local audio recording/playback
+    - `piper` - Local Piper TTS engine
+    - `kokoro` - Kokoro neural TTS engine
+    - `faster-whisper` - Whisper ASR for CUDA/CPU
+    - `mlx-whisper` - Whisper ASR for Apple Silicon
+    - `wyoming` - Wyoming protocol for ASR/TTS servers
+    - `server` - FastAPI server components
+    - `speed` - Audio speed adjustment
+    - `llm` - LLM framework (pydantic-ai)
+
+    **Examples:**
+
+        agent-cli install-extras rag           # Install RAG dependencies
+        agent-cli install-extras memory vad    # Install multiple extras
+        agent-cli install-extras --list        # Show available extras
+        agent-cli install-extras --all         # Install all extras
 
     """
     available = _available_extras()

agent_cli/install/hotkeys.py

@@ -13,20 +13,31 @@ from agent_cli.install.common import execute_installation_script, get_platform_s
 def install_hotkeys() -> None:
     """Install system-wide hotkeys for agent-cli commands.
 
-    Sets up the following hotkeys:
+    Sets up three global hotkeys:
 
-    macOS:
-    - Cmd+Shift+R: Toggle voice transcription
-    - Cmd+Shift+A: Autocorrect clipboard text
-    - Cmd+Shift+V: Voice edit clipboard text
+    | Hotkey (macOS / Linux)  | Action                                          |
+    |-------------------------|-------------------------------------------------|
+    | Cmd/Super + Shift + R   | Toggle voice transcription (start/stop)         |
+    | Cmd/Super + Shift + A   | Autocorrect clipboard text (grammar/spelling)   |
+    | Cmd/Super + Shift + V   | Voice edit clipboard text (voice commands)      |
 
-    Linux:
-    - Super+Shift+R: Toggle voice transcription
-    - Super+Shift+A: Autocorrect clipboard text
-    - Super+Shift+V: Voice edit clipboard text
+    **macOS** (fully automatic):
 
-    Note: On macOS, you may need to grant Accessibility permissions to skhd
-    in System Settings → Privacy & Security → Accessibility.
+    1. Installs `skhd` (hotkey daemon) and `terminal-notifier` via Homebrew
+    2. Creates config at `~/.config/skhd/skhdrc`
+    3. Starts skhd as a background service
+    4. May require Accessibility permissions: System Settings → Privacy & Security → Accessibility → enable 'skhd'
+
+    **Linux** (manual DE configuration):
+
+    1. Installs `libnotify` for notifications (if missing)
+    2. Prints binding instructions for your desktop environment
+    3. You manually add hotkeys pointing to the installed scripts
+
+    Supported Linux DEs: Hyprland, Sway, i3, GNOME, KDE, XFCE.
+
+    **Customizing hotkeys** (macOS): Edit `~/.config/skhd/skhdrc` and restart skhd:
+    `skhd --restart-service`
     """
     script_name = get_platform_script("setup-macos-hotkeys.sh", "setup-linux-hotkeys.sh")
     system = platform.system().lower()

agent_cli/install/services.py

@@ -20,13 +20,31 @@ from agent_cli.install.common import (
 def install_services() -> None:
     """Install all required services (Ollama, Whisper, Piper, OpenWakeWord).
 
-    This command installs:
-    - Ollama (local LLM server)
-    - Wyoming Faster Whisper (speech-to-text)
-    - Wyoming Piper (text-to-speech)
-    - Wyoming OpenWakeWord (wake word detection)
+    This command installs the following services:
 
-    The appropriate installation method is used based on your operating system.
+    - **Ollama** - Local LLM server for text processing
+    - **Wyoming Faster Whisper** - Speech-to-text transcription
+    - **Wyoming Piper** - Text-to-speech synthesis
+    - **Wyoming OpenWakeWord** - Wake word detection ("ok nabu", etc.)
+
+    The appropriate installation method is used based on your operating system
+    (Homebrew on macOS, apt/pip on Linux).
+
+    **Requirements:**
+
+    - macOS: Homebrew must be installed
+    - Linux: Requires sudo access for system packages
+
+    **Examples:**
+
+    Install all services:
+        `agent-cli install-services`
+
+    **After installation:**
+
+    1. Start the services: `agent-cli start-services`
+    2. Test transcription: `agent-cli transcribe --list-devices`
+    3. Set up hotkeys (optional): `agent-cli install-hotkeys`
     """
     script_name = get_platform_script("setup-macos.sh", "setup-linux.sh")
 
@@ -46,19 +64,41 @@ def start_services(
     attach: bool = typer.Option(
         True,  # noqa: FBT003
         "--attach/--no-attach",
-        help="Attach to Zellij session after starting",
+        help=(
+            "Attach to the Zellij session after starting. "
+            "With `--no-attach`, services start in background and you can "
+            "reattach later with `zellij attach agent-cli`"
+        ),
     ),
 ) -> None:
     """Start all agent-cli services in a Zellij session.
 
-    This starts:
-    - Ollama (LLM server)
-    - Wyoming Faster Whisper (speech-to-text)
-    - Wyoming Piper (text-to-speech)
-    - Wyoming OpenWakeWord (wake word detection)
+    Starts these services, each in its own Zellij pane:
+
+    - **Ollama** - LLM server (port 11434)
+    - **Wyoming Whisper** - Speech-to-text (port 10300)
+    - **Wyoming Piper** - Text-to-speech (port 10200)
+    - **Wyoming OpenWakeWord** - Wake word detection (port 10400)
+
+    Services run in a Zellij terminal multiplexer session named `agent-cli`.
+    If a session already exists, the command attaches to it instead of
+    starting new services.
+
+    **Keyboard shortcuts:**
+    - `Ctrl-O d` - Detach (keeps services running in background)
+    - `Ctrl-Q` - Quit (stops all services)
+    - `Alt + arrows` - Navigate between panes
+
+    **Examples:**
+
+    Start services and attach:
+        `agent-cli start-services`
+
+    Start in background (for scripts or automation):
+        `agent-cli start-services --no-attach`
 
-    Services run in a Zellij terminal multiplexer session named 'agent-cli'.
-    Use Ctrl-Q to quit or Ctrl-O d to detach from the session.
+    Reattach to running services:
+        `zellij attach agent-cli`
     """
     try:
         script_path = get_script_path("start-all-services.sh")

agent_cli/opts.py

@@ -2,12 +2,15 @@
 
 import copy
 from pathlib import Path
+from typing import Literal
 
 import typer
 from typer.models import OptionInfo
 
 from agent_cli.constants import DEFAULT_OPENAI_EMBEDDING_MODEL, DEFAULT_OPENAI_MODEL
 
+LogLevel = Literal["debug", "info", "warning", "error"]
+
 
 def with_default(option: OptionInfo, default: str) -> OptionInfo:
     """Create a copy of a typer Option with a different default value."""
@@ -20,18 +23,21 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo:
 LLM_PROVIDER: str = typer.Option(
     "ollama",
     "--llm-provider",
+    envvar="LLM_PROVIDER",
     help="The LLM provider to use ('ollama', 'openai', 'gemini').",
     rich_help_panel="Provider Selection",
 )
 ASR_PROVIDER: str = typer.Option(
     "wyoming",
     "--asr-provider",
+    envvar="ASR_PROVIDER",
     help="The ASR provider to use ('wyoming', 'openai', 'gemini').",
     rich_help_panel="Provider Selection",
 )
 TTS_PROVIDER: str = typer.Option(
     "wyoming",
     "--tts-provider",
+    envvar="TTS_PROVIDER",
     help="The TTS provider to use ('wyoming', 'openai', 'kokoro', 'gemini').",
     rich_help_panel="Provider Selection",
 )
@@ -41,19 +47,22 @@ TTS_PROVIDER: str = typer.Option(
 LLM: bool = typer.Option(
     False,  # noqa: FBT003
     "--llm/--no-llm",
-    help="Use an LLM to process the transcript.",
+    help="Clean up transcript with LLM: fix errors, add punctuation, remove filler words. "
+    "Uses `--extra-instructions` if set (via CLI or config file).",
     rich_help_panel="LLM Configuration",
 )
 # Ollama (local service)
 LLM_OLLAMA_MODEL: str = typer.Option(
     "gemma3:4b",
     "--llm-ollama-model",
+    envvar="LLM_OLLAMA_MODEL",
     help="The Ollama model to use. Default is gemma3:4b.",
     rich_help_panel="LLM: Ollama",
 )
 LLM_OLLAMA_HOST: str = typer.Option(
     "http://localhost:11434",
     "--llm-ollama-host",
+    envvar="LLM_OLLAMA_HOST",
     help="The Ollama server host. Default is http://localhost:11434.",
     rich_help_panel="LLM: Ollama",
 )
@@ -61,6 +70,7 @@ LLM_OLLAMA_HOST: str = typer.Option(
 LLM_OPENAI_MODEL: str = typer.Option(
     DEFAULT_OPENAI_MODEL,
     "--llm-openai-model",
+    envvar="LLM_OPENAI_MODEL",
     help="The OpenAI model to use for LLM tasks.",
     rich_help_panel="LLM: OpenAI-compatible",
 )
@@ -82,6 +92,7 @@ OPENAI_BASE_URL: str | None = typer.Option(
 LLM_GEMINI_MODEL: str = typer.Option(
     "gemini-3-flash-preview",
     "--llm-gemini-model",
+    envvar="LLM_GEMINI_MODEL",
     help="The Gemini model to use for LLM tasks.",
     rich_help_panel="LLM: Gemini",
 )
@@ -104,19 +115,19 @@ EMBEDDING_MODEL: str = typer.Option(
 INPUT_DEVICE_INDEX: int | None = typer.Option(
     None,
     "--input-device-index",
-    help="Index of the audio input device to use.",
+    help="Audio input device index (see `--list-devices`). Uses system default if omitted.",
     rich_help_panel="Audio Input",
 )
 INPUT_DEVICE_NAME: str | None = typer.Option(
     None,
     "--input-device-name",
-    help="Device name keywords for partial matching.",
+    help="Select input device by name substring (e.g., `MacBook` or `USB`).",
     rich_help_panel="Audio Input",
 )
 LIST_DEVICES: bool = typer.Option(
     False,  # noqa: FBT003
     "--list-devices",
-    help="List available audio input and output devices and exit.",
+    help="List available audio devices with their indices and exit.",
     is_eager=True,
     rich_help_panel="Audio Input",
 )
@@ -124,12 +135,14 @@ LIST_DEVICES: bool = typer.Option(
 ASR_WYOMING_IP: str = typer.Option(
     "localhost",
     "--asr-wyoming-ip",
+    envvar="ASR_WYOMING_IP",
     help="Wyoming ASR server IP address.",
     rich_help_panel="Audio Input: Wyoming",
 )
 ASR_WYOMING_PORT: int = typer.Option(
     10300,
     "--asr-wyoming-port",
+    envvar="ASR_WYOMING_PORT",
     help="Wyoming ASR server port.",
     rich_help_panel="Audio Input: Wyoming",
 )
@@ -137,18 +150,21 @@ ASR_WYOMING_PORT: int = typer.Option(
 ASR_OPENAI_MODEL: str = typer.Option(
     "whisper-1",
     "--asr-openai-model",
+    envvar="ASR_OPENAI_MODEL",
     help="The OpenAI model to use for ASR (transcription).",
     rich_help_panel="Audio Input: OpenAI-compatible",
 )
 ASR_OPENAI_BASE_URL: str | None = typer.Option(
     None,
     "--asr-openai-base-url",
+    envvar="ASR_OPENAI_BASE_URL",
     help="Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898).",
     rich_help_panel="Audio Input: OpenAI-compatible",
 )
 ASR_OPENAI_PROMPT: str | None = typer.Option(
     None,
     "--asr-openai-prompt",
+    envvar="ASR_OPENAI_PROMPT",
     help="Custom prompt to guide transcription (optional).",
     rich_help_panel="Audio Input: OpenAI-compatible",
 )
@@ -156,6 +172,7 @@ ASR_OPENAI_PROMPT: str | None = typer.Option(
 ASR_GEMINI_MODEL: str = typer.Option(
     "gemini-3-flash-preview",
     "--asr-gemini-model",
+    envvar="ASR_GEMINI_MODEL",
     help="The Gemini model to use for ASR (transcription).",
     rich_help_panel="Audio Input: Gemini",
 )
@@ -165,7 +182,7 @@ ASR_GEMINI_MODEL: str = typer.Option(
 WAKE_SERVER_IP: str = typer.Option(
     "localhost",
     "--wake-server-ip",
-    help="Wyoming wake word server IP address.",
+    help="Wyoming wake word server IP (requires wyoming-openwakeword or similar).",
     rich_help_panel="Wake Word",
 )
 WAKE_SERVER_PORT: int = typer.Option(
@@ -177,7 +194,7 @@ WAKE_SERVER_PORT: int = typer.Option(
 WAKE_WORD: str = typer.Option(
     "ok_nabu",
     "--wake-word",
-    help="Name of wake word to detect (e.g., 'ok_nabu', 'hey_jarvis').",
+    help="Wake word to detect. Common options: `ok_nabu`, `hey_jarvis`, `alexa`. Must match a model loaded in your wake word server.",
     rich_help_panel="Wake Word",
 )
 
@@ -199,13 +216,13 @@ TTS_SPEED: float = typer.Option(
 OUTPUT_DEVICE_INDEX: int | None = typer.Option(
     None,
     "--output-device-index",
-    help="Index of the audio output device to use for TTS.",
+    help="Audio output device index (see `--list-devices` for available devices).",
     rich_help_panel="Audio Output",
 )
 OUTPUT_DEVICE_NAME: str | None = typer.Option(
     None,
     "--output-device-name",
-    help="Output device name keywords for partial matching.",
+    help="Partial match on device name (e.g., 'speakers', 'headphones').",
     rich_help_panel="Audio Output",
 )
 # Wyoming (local service)
@@ -249,7 +266,7 @@ TTS_OPENAI_MODEL: str = typer.Option(
 TTS_OPENAI_VOICE: str = typer.Option(
     "alloy",
     "--tts-openai-voice",
-    help="The voice to use for OpenAI-compatible TTS.",
+    help="Voice for OpenAI TTS (alloy, echo, fable, onyx, nova, shimmer).",
     rich_help_panel="Audio Output: OpenAI-compatible",
 )
 TTS_OPENAI_BASE_URL: str | None = typer.Option(
@@ -299,21 +316,19 @@ TTS_GEMINI_VOICE: str = typer.Option(
 STOP: bool = typer.Option(
     False,  # noqa: FBT003
     "--stop",
-    help="Stop any running background process.",
+    help="Stop any running instance of this command.",
     rich_help_panel="Process Management",
 )
 STATUS: bool = typer.Option(
     False,  # noqa: FBT003
     "--status",
-    help="Check if a background process is running.",
+    help="Check if an instance is currently running.",
     rich_help_panel="Process Management",
 )
 TOGGLE: bool = typer.Option(
     False,  # noqa: FBT003
     "--toggle",
-    help="Toggle the background process on/off. "
-    "If the process is running, it will be stopped. "
-    "If the process is not running, it will be started.",
+    help="Start if not running, stop if running. Ideal for hotkey binding.",
     rich_help_panel="Process Management",
 )
 
@@ -348,13 +363,15 @@ CLIPBOARD: bool = typer.Option(
     help="Copy result to clipboard.",
     rich_help_panel="General Options",
 )
-LOG_LEVEL: str = typer.Option(
-    "WARNING",
+LOG_LEVEL: LogLevel = typer.Option(
+    "warning",
     "--log-level",
+    envvar="LOG_LEVEL",
     help="Set logging level.",
     case_sensitive=False,
     rich_help_panel="General Options",
 )
+SERVER_LOG_LEVEL: LogLevel = with_default(LOG_LEVEL, "info")
 LOG_FILE: str | None = typer.Option(
     None,
     "--log-file",
@@ -371,19 +388,20 @@ QUIET: bool = typer.Option(
 JSON_OUTPUT: bool = typer.Option(
     False,  # noqa: FBT003
     "--json",
-    help="Output result as JSON for automation. Implies --quiet and --no-clipboard.",
+    help="Output result as JSON (implies `--quiet` and `--no-clipboard`).",
     rich_help_panel="General Options",
 )
 SAVE_FILE: Path | None = typer.Option(
     None,
     "--save-file",
-    help="Save TTS response audio to WAV file.",
+    help="Save audio to WAV file instead of playing through speakers.",
     rich_help_panel="General Options",
 )
 TRANSCRIPTION_LOG: Path | None = typer.Option(
     None,
     "--transcription-log",
-    help="Path to log transcription results with timestamps, hostname, model, and raw output.",
+    help="Append transcripts to JSONL file (timestamp, hostname, model, raw/processed text). "
+    "Recent entries provide context for LLM cleanup.",
     rich_help_panel="General Options",
 )
 
@@ -399,18 +417,21 @@ SERVER_HOST: str = typer.Option(
 FROM_FILE: Path | None = typer.Option(
     None,
     "--from-file",
-    help="Transcribe audio from a file (supports wav, mp3, m4a, ogg, flac, aac, webm). Requires ffmpeg for non-WAV formats with Wyoming provider.",
+    help="Transcribe from audio file instead of microphone. "
+    "Supports wav, mp3, m4a, ogg, flac, aac, webm. "
+    "Requires `ffmpeg` for non-WAV formats with Wyoming.",
     rich_help_panel="Audio Recovery",
 )
 LAST_RECORDING: int = typer.Option(
     0,
     "--last-recording",
-    help="Transcribe a saved recording. Use 1 for most recent, 2 for second-to-last, etc. Use 0 to disable (default).",
+    help="Re-transcribe a saved recording (1=most recent, 2=second-to-last, etc). "
+    "Useful after connection failures or to retry with different options.",
     rich_help_panel="Audio Recovery",
 )
 SAVE_RECORDING: bool = typer.Option(
     True,  # noqa: FBT003
     "--save-recording/--no-save-recording",
-    help="Save the audio recording to disk for recovery.",
+    help="Save recordings to ~/.cache/agent-cli/ for `--last-recording` recovery.",
     rich_help_panel="Audio Recovery",
 )