From a5eed15090120ece436d4ff2187609cbe2f39772 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:25:13 -0800 Subject: [PATCH 01/24] feat(docs): add docs_gen module for auto-generating option tables Add a new `agent_cli.docs_gen` module that introspects Typer commands and generates Markdown documentation tables. This integrates with markdown-code-runner to keep documentation in sync with code. Key functions: - `all_options_for_docs(cmd)`: Generate complete options tables grouped by panel - `options_table(cmd, panel)`: Generate table for specific command/panel - `env_vars_table()`: Generate environment variables documentation - `provider_matrix()`: Generate provider comparison table - `config_example(cmd)`: Generate example TOML configuration Benefits: - Single source of truth: opts.py definitions auto-generate docs - No drift between CLI help and documentation - CI-friendly: can validate docs match code Also updates docs/commands/transcribe.md as an example of the new auto-generation approach using markdown-code-runner hidden code blocks. --- agent_cli/docs_gen.py | 462 ++++++++++++++++++++++++++++++++++++ docs/commands/transcribe.md | 139 ++++++----- 2 files changed, 538 insertions(+), 63 deletions(-) create mode 100644 agent_cli/docs_gen.py diff --git a/agent_cli/docs_gen.py b/agent_cli/docs_gen.py new file mode 100644 index 000000000..3abf2baf2 --- /dev/null +++ b/agent_cli/docs_gen.py @@ -0,0 +1,462 @@ +"""Documentation generators for markdown-code-runner integration. + +This module provides functions to introspect Typer commands and generate +Markdown documentation. Use with markdown-code-runner to auto-generate +options tables in documentation. + +Example usage in Markdown files: + + + + + + ...auto-generated table... + +""" + +from __future__ import annotations + +from typing import Any, get_origin + +import click +from typer.main import get_command + +from agent_cli import opts +from agent_cli.cli import app + + +def _get_type_str(annotation: Any) -> str: + """Convert a type annotation to a readable string.""" + if annotation is None: + return "str" + + # Handle Optional types (Union[X, None]) + origin = get_origin(annotation) + if origin is type(None): + return "None" + + # Get the base type name + if hasattr(annotation, "__name__"): + return annotation.__name__.upper() + if hasattr(annotation, "__origin__"): + # Handle generic types like Optional[str] + args = getattr(annotation, "__args__", ()) + non_none_args = [a for a in args if a is not type(None)] + if non_none_args: + return _get_type_str(non_none_args[0]) + return str(annotation).replace("typing.", "").upper() + + +def _format_default(default: Any) -> str: + """Format a default value for display.""" + if default is None: + return "-" + if isinstance(default, bool): + return str(default).lower() + if isinstance(default, str) and default == "": + return '""' + return str(default) + + +def _get_click_command(command_path: str) -> click.Command | None: + """Get a Click command from a path like 'transcribe' or 'memory.proxy'.""" + parts = command_path.split(".") + click_app = get_command(app) + + cmd: click.Command | click.Group = click_app + for part in parts: + if isinstance(cmd, click.Group): + cmd = cmd.commands.get(part) # type: ignore[assignment] + if cmd is None: + return None + else: + return None + return cmd + + +def _extract_options_from_click(cmd: click.Command) -> list[dict[str, Any]]: + """Extract options from a Click command.""" + options = [] + for param in cmd.params: + if isinstance(param, click.Option): + # Get the primary option name (longest one, usually --foo) + opt_names = [n for n in param.opts if n.startswith("--")] + if not opt_names: + opt_names = param.opts + primary_name = max(opt_names, key=len) if opt_names else param.name + + # Handle boolean flags + if param.is_flag and param.secondary_opts: + # e.g., --llm/--no-llm + primary_name = f"{opt_names[0]}/{param.secondary_opts[0]}" + + # Get panel from rich_help_panel or use default + panel = getattr(param, "rich_help_panel", None) or "Options" + + options.append( + { + "name": primary_name, + "type": param.type.name.upper() if hasattr(param.type, "name") else "TEXT", + "default": _format_default(param.default), + "help": param.help or "", + "panel": panel, + "envvar": param.envvar[0] if param.envvar else None, + "required": param.required, + "is_flag": param.is_flag, + }, + ) + return options + + +def get_command_options(command_path: str) -> list[dict[str, Any]]: + """Extract all options from a Typer command. + + Args: + command_path: Command path like "transcribe" or "memory.proxy" + + Returns: + List of option dictionaries with keys: + - name: Option flag (e.g., "--input-device-index") + - type: Type string (e.g., "INTEGER", "TEXT") + - default: Default value or "-" if none + - help: Help text + - panel: Rich help panel name for grouping + - envvar: Environment variable name if any + - required: Whether the option is required + - is_flag: Whether it's a boolean flag + + """ + cmd = _get_click_command(command_path) + if cmd is None: + return [] + return _extract_options_from_click(cmd) + + +def options_table( + command_path: str, + panel: str | None = None, + *, + include_type: bool = True, + include_default: bool = True, +) -> str: + """Generate a Markdown table of options for a command. + + Args: + command_path: Command path like "transcribe" or "memory.proxy" + panel: Filter to specific rich_help_panel, or None for all + include_type: Include the Type column + include_default: Include the Default column + + Returns: + Markdown table string + + """ + options = get_command_options(command_path) + if panel: + options = [o for o in options if o["panel"] == panel] + + if not options: + return f"*No options found for panel '{panel}'*" if panel else "*No options found*" + + # Build header + header_parts = ["Option"] + if include_type: + header_parts.append("Type") + if include_default: + header_parts.append("Default") + header_parts.append("Description") + + header = "| " + " | ".join(header_parts) + " |" + separator = "|" + "|".join("-" * (len(p) + 2) for p in header_parts) + "|" + + lines = [header, separator] + + for opt in options: + row_parts = [f"`{opt['name']}`"] + if include_type: + row_parts.append(opt["type"]) + if include_default: + default = opt["default"] + row_parts.append(f"`{default}`" if default != "-" else "-") + row_parts.append(opt["help"]) + lines.append("| " + " | ".join(row_parts) + " |") + + return "\n".join(lines) + + +def options_by_panel( + command_path: str, + *, + include_type: bool = True, + include_default: bool = True, + heading_level: int = 3, +) -> str: + """Generate options tables grouped by panel. + + Args: + command_path: Command path like "transcribe" or "memory.proxy" + include_type: Include the Type column + include_default: Include the Default column + heading_level: Markdown heading level for panel names + + Returns: + Markdown string with sectioned tables + + """ + options = get_command_options(command_path) + if not options: + return "*No options found*" + + # Group by panel, preserving order + panels: dict[str, list[dict[str, Any]]] = {} + for opt in options: + panel = opt["panel"] + if panel not in panels: + panels[panel] = [] + panels[panel].append(opt) + + heading_prefix = "#" * heading_level + output = [] + + for panel, panel_opts in panels.items(): + output.append(f"{heading_prefix} {panel}\n") + + # Build table for this panel + header_parts = ["Option"] + if include_type: + header_parts.append("Type") + if include_default: + header_parts.append("Default") + header_parts.append("Description") + + header = "| " + " | ".join(header_parts) + " |" + separator = "|" + "|".join("-" * (len(p) + 2) for p in header_parts) + "|" + + output.append(header) + output.append(separator) + + for opt in panel_opts: + row_parts = [f"`{opt['name']}`"] + if include_type: + row_parts.append(opt["type"]) + if include_default: + default = opt["default"] + row_parts.append(f"`{default}`" if default != "-" else "-") + row_parts.append(opt["help"]) + output.append("| " + " | ".join(row_parts) + " |") + + output.append("") # Blank line between panels + + return "\n".join(output) + + +def list_commands() -> list[str]: + """List all available commands including subcommands. + + Returns: + List of command paths like ["transcribe", "memory.proxy", "memory.add"] + + """ + click_app = get_command(app) + commands = [] + + def _walk(cmd: click.Command | click.Group, prefix: str = "") -> None: + if isinstance(cmd, click.Group): + for name, subcmd in cmd.commands.items(): + path = f"{prefix}.{name}" if prefix else name + if isinstance(subcmd, click.Group): + _walk(subcmd, path) + else: + commands.append(path) + elif prefix: + commands.append(prefix) + + _walk(click_app) + return sorted(commands) + + +def env_vars_table() -> str: + """Generate a table of all environment variables. + + Returns: + Markdown table of environment variables and descriptions + + """ + lines = [ + "| Variable | Description |", + "|----------|-------------|", + ] + + seen = set() + for name in dir(opts): + if name.startswith("_"): + continue + obj = getattr(opts, name) + if hasattr(obj, "envvar") and obj.envvar: + envvar = obj.envvar + if envvar not in seen: + seen.add(envvar) + help_text = getattr(obj, "help", "") or "" + lines.append(f"| `{envvar}` | {help_text} |") + + return "\n".join(lines) + + +def provider_matrix() -> str: + """Generate provider comparison matrix. + + Returns: + Markdown table comparing local vs cloud providers + + """ + return """| Capability | Local (Default) | Cloud Options | +|------------|-----------------|---------------| +| **LLM** | Ollama (`ollama`) | OpenAI (`openai`), Gemini (`gemini`) | +| **ASR** (Speech-to-Text) | Wyoming/Faster Whisper (`wyoming`) | OpenAI Whisper (`openai`) | +| **TTS** (Text-to-Speech) | Wyoming/Piper (`wyoming`), Kokoro (`kokoro`) | OpenAI TTS (`openai`) | +| **Wake Word** | Wyoming/openWakeWord | - |""" + + +def commands_table(category: str | None = None) -> str: + """Generate a table of available commands. + + Args: + category: Filter by category (voice, text, ai, install, config) or None for all + + Returns: + Markdown table of commands + + """ + # Define command metadata + command_info = { + "transcribe": ("Speech-to-text", "Record voice → text in clipboard", "voice"), + "transcribe-daemon": ("Continuous transcription", "Background VAD service", "voice"), + "speak": ("Text-to-speech", "Read text aloud", "voice"), + "voice-edit": ("Voice-powered editor", "Edit clipboard with voice", "voice"), + "assistant": ("Wake word assistant", "Hands-free voice interaction", "voice"), + "chat": ("Conversational AI", "Voice chat with tools", "voice"), + "autocorrect": ("Grammar & spelling", "Fix text from clipboard", "text"), + "rag-proxy": ("RAG server", "Chat with documents", "ai"), + "memory.proxy": ("Long-term memory", "Persistent conversation memory", "ai"), + "memory.add": ("Add memories", "Directly add facts to memory", "ai"), + "server": ("Transcription server", "HTTP API for transcription", "ai"), + "install-services": ("Install services", "Set up AI services", "install"), + "install-hotkeys": ("Install hotkeys", "Set up system hotkeys", "install"), + "start-services": ("Start services", "Launch all services", "install"), + "config": ("Configuration", "Manage config files", "config"), + } + + if category: + commands = {k: v for k, v in command_info.items() if v[2] == category} + else: + commands = command_info + + if not commands: + return "*No commands found*" + + lines = [ + "| Command | Purpose | Use Case |", + "|---------|---------|----------|", + ] + + for cmd, (purpose, use_case, _) in commands.items(): + # Convert command path to link + doc_path = cmd.replace(".", "/") + lines.append(f"| [`{cmd}`]({doc_path}.md) | {purpose} | {use_case} |") + + return "\n".join(lines) + + +def config_example(command_path: str | None = None) -> str: + """Generate example TOML configuration for a command. + + Args: + command_path: Command path or None for defaults section + + Returns: + TOML configuration snippet + + """ + if command_path is None: + # Generate defaults section + return """[defaults] +# Provider defaults (can be overridden per command) +# llm_provider = "ollama" +# asr_provider = "wyoming" +# tts_provider = "wyoming" + +# API keys (or use environment variables) +# openai_api_key = "sk-..." +# gemini_api_key = "..." + +# Audio devices +# input_device_index = 1 +# output_device_index = 0""" + + options = get_command_options(command_path) + if not options: + return f"# No configurable options for {command_path}" + + section = command_path.replace(".", "-") + lines = [f"[{section}]"] + + for opt in options: + # Skip process management and meta options + if opt["panel"] in ("Process Management Options",): + continue + + # Convert flag name to config key + key = opt["name"].lstrip("-").replace("-", "_").split("/")[0] + default = opt["default"] + help_text = opt["help"] + + # Format the value appropriately + if default == "-": + value = '""' if opt["type"] == "TEXT" else "null" + lines.append(f"# {key} = {value} # {help_text}") + elif opt["type"] == "TEXT": + lines.append(f'# {key} = "{default}" # {help_text}') + elif opt["type"] in ("INTEGER", "FLOAT") or opt["is_flag"]: + lines.append(f"# {key} = {default} # {help_text}") + else: + lines.append(f"# {key} = {default} # {help_text}") + + return "\n".join(lines) + + +def all_options_for_docs(command_path: str) -> str: + """Generate complete options documentation for a command page. + + This is the main function to use in docs/commands/*.md files. + It generates all options grouped by panel with proper formatting. + + Args: + command_path: Command path like "transcribe" or "memory.proxy" + + Returns: + Complete Markdown options section + + """ + return options_by_panel( + command_path, + include_type=False, # Types are often obvious and clutter the table + include_default=True, + heading_level=3, + ) + + +if __name__ == "__main__": + # Demo: print options for transcribe command + print("=== Available Commands ===") + for cmd in list_commands(): + print(f" {cmd}") + print() + + print("=== transcribe options by panel ===") + print(options_by_panel("transcribe")) + + print("\n=== Environment Variables ===") + print(env_vars_table()) + + print("\n=== Provider Matrix ===") + print(provider_matrix()) diff --git a/docs/commands/transcribe.md b/docs/commands/transcribe.md index 89dfec60b..6d2f6af36 100644 --- a/docs/commands/transcribe.md +++ b/docs/commands/transcribe.md @@ -43,92 +43,105 @@ agent-cli transcribe --last-recording 1 ## Options -### Audio Configuration - -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of the audio input device | -| `--input-device-name` | Device name keywords for partial matching | -| `--list-devices` | List available audio devices and exit | + + + + + + +### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--extra-instructions` | - | Additional instructions for the LLM to process the transcription. | ### Audio Recovery -| Option | Description | Default | -|--------|-------------|---------| -| `--from-file PATH` | Transcribe from a saved WAV file | - | -| `--last-recording N` | Transcribe Nth most recent recording (1=latest) | `0` | -| `--save-recording` / `--no-save-recording` | Save audio for recovery | `true` | +| Option | Default | Description | +|--------|---------|-------------| +| `--from-file` | - | Transcribe audio from a saved WAV file instead of recording. | +| `--last-recording` | `0` | Transcribe a saved recording. Use 1 for most recent, 2 for second-to-last, etc. Use 0 to disable (default). | +| `--save-recording/--no-save-recording` | `true` | Save the audio recording to disk for recovery. | ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | + +### ASR (Audio) Configuration + +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### Wyoming (Local) Configuration +### ASR (Audio) Configuration: Wyoming (local) -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### OpenAI ASR Configuration +### ASR (Audio) Configuration: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | -| `--asr-openai-base-url` | Custom Whisper server URL | - | -| `--asr-openai-prompt` | Custom prompt to guide transcription | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | +| `--asr-openai-base-url` | - | Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898). | +| `--asr-openai-prompt` | - | Custom prompt to guide transcription (optional). | -### LLM (Ollama, local) +### LLM Configuration: Ollama (local) -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (OpenAI) +### LLM Configuration: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### LLM (Gemini) +### LLM Configuration: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### LLM Cleanup +### LLM Configuration -| Option | Description | Default | -|--------|-------------|---------| -| `--llm` / `--no-llm` | Use LLM to process transcript | `false` | -| `--extra-instructions` | Additional LLM instructions | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm/--no-llm` | `false` | Use an LLM to process the transcript. | -### Process Management +### Process Management Options -| Option | Description | -|--------|-------------| -| `--stop` | Stop running background process | -| `--status` | Check if background process is running | -| `--toggle` | Toggle background process on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | 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. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--clipboard` / `--no-clipboard` | Copy result to clipboard | `true` | -| `--transcription-log PATH` | Log transcriptions with timestamps | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--clipboard/--no-clipboard` | `true` | Copy result to clipboard. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | +| `--transcription-log` | - | Path to log transcription results with timestamps, hostname, model, and raw output. | + + ## Workflow Integration From 0184d94cdb678afb5cd731f0b7ae3dcea6de24d3 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:31:56 -0800 Subject: [PATCH 02/24] refactor(opts): simplify rich_help_panel names for cleaner docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Simplify verbose panel names: - "ASR (Audio) Configuration" → "Audio Input" - "TTS (Text-to-Speech) Configuration" → "Audio Output" - "LLM Configuration: Ollama (local)" → "LLM: Ollama" - "Process Management Options" → "Process Management" - "Wake Word Options" → "Wake Word" Also group --extra-instructions with --llm under "LLM Configuration" panel for better logical organization. Regenerate docs/commands/transcribe.md with cleaner section headers. --- agent_cli/agents/transcribe.py | 1 + agent_cli/opts.py | 72 +++++++++++++++++----------------- docs/commands/transcribe.md | 24 +++++------- 3 files changed, 47 insertions(+), 50 deletions(-) diff --git a/agent_cli/agents/transcribe.py b/agent_cli/agents/transcribe.py index 555d05b8d..a78723784 100644 --- a/agent_cli/agents/transcribe.py +++ b/agent_cli/agents/transcribe.py @@ -415,6 +415,7 @@ def transcribe( # noqa: PLR0912 None, "--extra-instructions", help="Additional instructions for the LLM to process the transcription.", + rich_help_panel="LLM Configuration", ), from_file: Path | None = opts.FROM_FILE, last_recording: int = opts.LAST_RECORDING, diff --git a/agent_cli/opts.py b/agent_cli/opts.py index 71af47216..d736b4bf7 100644 --- a/agent_cli/opts.py +++ b/agent_cli/opts.py @@ -49,48 +49,48 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: "gemma3:4b", "--llm-ollama-model", help="The Ollama model to use. Default is gemma3:4b.", - rich_help_panel="LLM Configuration: Ollama (local)", + rich_help_panel="LLM: Ollama", ) LLM_OLLAMA_HOST: str = typer.Option( "http://localhost:11434", "--llm-ollama-host", help="The Ollama server host. Default is http://localhost:11434.", - rich_help_panel="LLM Configuration: Ollama (local)", + rich_help_panel="LLM: Ollama", ) # OpenAI LLM_OPENAI_MODEL: str = typer.Option( DEFAULT_OPENAI_MODEL, "--llm-openai-model", help="The OpenAI model to use for LLM tasks.", - rich_help_panel="LLM Configuration: OpenAI", + rich_help_panel="LLM: OpenAI", ) OPENAI_API_KEY: str | None = typer.Option( None, "--openai-api-key", help="Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable.", envvar="OPENAI_API_KEY", - rich_help_panel="LLM Configuration: OpenAI", + rich_help_panel="LLM: OpenAI", ) OPENAI_BASE_URL: str | None = typer.Option( None, "--openai-base-url", help="Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1).", envvar="OPENAI_BASE_URL", - rich_help_panel="LLM Configuration: OpenAI", + rich_help_panel="LLM: OpenAI", ) # Gemini LLM_GEMINI_MODEL: str = typer.Option( "gemini-2.5-flash", "--llm-gemini-model", help="The Gemini model to use for LLM tasks.", - rich_help_panel="LLM Configuration: Gemini", + rich_help_panel="LLM: Gemini", ) GEMINI_API_KEY: str | None = typer.Option( None, "--gemini-api-key", help="Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable.", envvar="GEMINI_API_KEY", - rich_help_panel="LLM Configuration: Gemini", + rich_help_panel="LLM: Gemini", ) EMBEDDING_MODEL: str = typer.Option( DEFAULT_OPENAI_EMBEDDING_MODEL, @@ -105,52 +105,52 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: None, "--input-device-index", help="Index of the audio input device to use.", - rich_help_panel="ASR (Audio) Configuration", + rich_help_panel="Audio Input", ) INPUT_DEVICE_NAME: str | None = typer.Option( None, "--input-device-name", help="Device name keywords for partial matching.", - rich_help_panel="ASR (Audio) Configuration", + 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.", is_eager=True, - rich_help_panel="ASR (Audio) Configuration", + rich_help_panel="Audio Input", ) # Wyoming (local service) ASR_WYOMING_IP: str = typer.Option( "localhost", "--asr-wyoming-ip", help="Wyoming ASR server IP address.", - rich_help_panel="ASR (Audio) Configuration: Wyoming (local)", + rich_help_panel="Audio Input: Wyoming", ) ASR_WYOMING_PORT: int = typer.Option( 10300, "--asr-wyoming-port", help="Wyoming ASR server port.", - rich_help_panel="ASR (Audio) Configuration: Wyoming (local)", + rich_help_panel="Audio Input: Wyoming", ) # OpenAI ASR_OPENAI_MODEL: str = typer.Option( "whisper-1", "--asr-openai-model", help="The OpenAI model to use for ASR (transcription).", - rich_help_panel="ASR (Audio) Configuration: OpenAI", + rich_help_panel="Audio Input: OpenAI", ) ASR_OPENAI_BASE_URL: str | None = typer.Option( None, "--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="ASR (Audio) Configuration: OpenAI", + rich_help_panel="Audio Input: OpenAI", ) ASR_OPENAI_PROMPT: str | None = typer.Option( None, "--asr-openai-prompt", help="Custom prompt to guide transcription (optional).", - rich_help_panel="ASR (Audio) Configuration: OpenAI", + rich_help_panel="Audio Input: OpenAI", ) @@ -159,19 +159,19 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: "localhost", "--wake-server-ip", help="Wyoming wake word server IP address.", - rich_help_panel="Wake Word Options", + rich_help_panel="Wake Word", ) WAKE_SERVER_PORT: int = typer.Option( 10400, "--wake-server-port", help="Wyoming wake word server port.", - rich_help_panel="Wake Word Options", + rich_help_panel="Wake Word", ) WAKE_WORD: str = typer.Option( "ok_nabu", "--wake-word", help="Name of wake word to detect (e.g., 'ok_nabu', 'hey_jarvis').", - rich_help_panel="Wake Word Options", + rich_help_panel="Wake Word", ) @@ -181,75 +181,75 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: False, # noqa: FBT003 "--tts/--no-tts", help="Enable text-to-speech for responses.", - rich_help_panel="TTS (Text-to-Speech) Configuration", + rich_help_panel="Audio Output", ) TTS_SPEED: float = typer.Option( 1.0, "--tts-speed", help="Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed).", - rich_help_panel="TTS (Text-to-Speech) Configuration", + rich_help_panel="Audio Output", ) OUTPUT_DEVICE_INDEX: int | None = typer.Option( None, "--output-device-index", help="Index of the audio output device to use for TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration", + rich_help_panel="Audio Output", ) OUTPUT_DEVICE_NAME: str | None = typer.Option( None, "--output-device-name", help="Output device name keywords for partial matching.", - rich_help_panel="TTS (Text-to-Speech) Configuration", + rich_help_panel="Audio Output", ) # Wyoming (local service) TTS_WYOMING_IP: str = typer.Option( "localhost", "--tts-wyoming-ip", help="Wyoming TTS server IP address.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) TTS_WYOMING_PORT: int = typer.Option( 10200, "--tts-wyoming-port", help="Wyoming TTS server port.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) TTS_WYOMING_VOICE: str | None = typer.Option( None, "--tts-wyoming-voice", help="Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium').", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) TTS_WYOMING_LANGUAGE: str | None = typer.Option( None, "--tts-wyoming-language", help="Language for Wyoming TTS (e.g., 'en_US').", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) TTS_WYOMING_SPEAKER: str | None = typer.Option( None, "--tts-wyoming-speaker", help="Speaker name for Wyoming TTS voice.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Wyoming (local)", + rich_help_panel="Audio Output: Wyoming", ) # OpenAI TTS_OPENAI_MODEL: str = typer.Option( "tts-1", "--tts-openai-model", help="The OpenAI model to use for TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration: OpenAI", + rich_help_panel="Audio Output: OpenAI", ) TTS_OPENAI_VOICE: str = typer.Option( "alloy", "--tts-openai-voice", help="The voice to use for OpenAI TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration: OpenAI", + rich_help_panel="Audio Output: OpenAI", ) TTS_OPENAI_BASE_URL: str | None = typer.Option( None, "--tts-openai-base-url", help="Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy).", - rich_help_panel="TTS (Text-to-Speech) Configuration: OpenAI", + rich_help_panel="Audio Output: OpenAI", ) @@ -258,19 +258,19 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: "kokoro", "--tts-kokoro-model", help="The Kokoro model to use for TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Kokoro", + rich_help_panel="Audio Output: Kokoro", ) TTS_KOKORO_VOICE: str = typer.Option( "af_sky", "--tts-kokoro-voice", help="The voice to use for Kokoro TTS.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Kokoro", + rich_help_panel="Audio Output: Kokoro", ) TTS_KOKORO_HOST: str = typer.Option( "http://localhost:8880/v1", "--tts-kokoro-host", help="The base URL for the Kokoro API.", - rich_help_panel="TTS (Text-to-Speech) Configuration: Kokoro", + rich_help_panel="Audio Output: Kokoro", ) @@ -279,13 +279,13 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: False, # noqa: FBT003 "--stop", help="Stop any running background process.", - rich_help_panel="Process Management Options", + rich_help_panel="Process Management", ) STATUS: bool = typer.Option( False, # noqa: FBT003 "--status", help="Check if a background process is running.", - rich_help_panel="Process Management Options", + rich_help_panel="Process Management", ) TOGGLE: bool = typer.Option( False, # noqa: FBT003 @@ -293,7 +293,7 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: 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.", - rich_help_panel="Process Management Options", + rich_help_panel="Process Management", ) # --- General Options --- diff --git a/docs/commands/transcribe.md b/docs/commands/transcribe.md index 6d2f6af36..1ef938ddb 100644 --- a/docs/commands/transcribe.md +++ b/docs/commands/transcribe.md @@ -49,11 +49,12 @@ agent-cli transcribe --last-recording 1 -### Options +### LLM Configuration | Option | Default | Description | |--------|---------|-------------| | `--extra-instructions` | - | Additional instructions for the LLM to process the transcription. | +| `--llm/--no-llm` | `false` | Use an LLM to process the transcript. | ### Audio Recovery @@ -70,7 +71,7 @@ agent-cli transcribe --last-recording 1 | `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | | `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | -### ASR (Audio) Configuration +### Audio Input | Option | Default | Description | |--------|---------|-------------| @@ -78,14 +79,14 @@ agent-cli transcribe --last-recording 1 | `--input-device-name` | - | Device name keywords for partial matching. | | `--list-devices` | `false` | List available audio input and output devices and exit. | -### ASR (Audio) Configuration: Wyoming (local) +### Audio Input: Wyoming | Option | Default | Description | |--------|---------|-------------| | `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | | `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### ASR (Audio) Configuration: OpenAI +### Audio Input: OpenAI | Option | Default | Description | |--------|---------|-------------| @@ -93,14 +94,14 @@ agent-cli transcribe --last-recording 1 | `--asr-openai-base-url` | - | Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898). | | `--asr-openai-prompt` | - | Custom prompt to guide transcription (optional). | -### LLM Configuration: Ollama (local) +### LLM: Ollama | Option | Default | Description | |--------|---------|-------------| | `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | | `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM Configuration: OpenAI +### LLM: OpenAI | Option | Default | Description | |--------|---------|-------------| @@ -108,20 +109,14 @@ agent-cli transcribe --last-recording 1 | `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | | `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### LLM Configuration: Gemini +### LLM: Gemini | Option | Default | Description | |--------|---------|-------------| | `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | | `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### LLM Configuration - -| Option | Default | Description | -|--------|---------|-------------| -| `--llm/--no-llm` | `false` | Use an LLM to process the transcript. | - -### Process Management Options +### Process Management | Option | Default | Description | |--------|---------|-------------| @@ -141,6 +136,7 @@ agent-cli transcribe --last-recording 1 | `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | | `--transcription-log` | - | Path to log transcription results with timestamps, hostname, model, and raw output. | + ## Workflow Integration From 179c4c6a75655f7cfcf6e28f44214162e8751695 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 3 Jan 2026 08:33:18 +0000 Subject: [PATCH 03/24] Update README.md --- README.md | 133 +++++++++++++++++++++++++++--------------------------- 1 file changed, 67 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 7b6efc50b..ed932715d 100644 --- a/README.md +++ b/README.md @@ -465,7 +465,7 @@ the `[defaults]` section of your configuration file. │ 'gemini'). │ │ [default: ollama] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -473,7 +473,7 @@ the `[defaults]` section of your configuration file. │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -484,7 +484,7 @@ the `[defaults]` section of your configuration file. │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ @@ -545,9 +545,14 @@ the `[defaults]` section of your configuration file. Wyoming ASR Client for streaming microphone audio to a transcription server. ╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --extra-instructions TEXT Additional instructions for the LLM to │ -│ process the transcription. │ -│ --help -h Show this message and exit. │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ +│ --extra-instructions TEXT Additional instructions for the │ +│ LLM to process the transcription. │ +│ --llm --no-llm Use an LLM to process the │ +│ transcript. │ +│ [default: no-llm] │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Audio Recovery ─────────────────────────────────────────────────────────────╮ │ --from-file PATH Transcribe audio from a │ @@ -571,20 +576,20 @@ the `[defaults]` section of your configuration file. │ 'gemini'). │ │ [default: ollama] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ @@ -594,7 +599,7 @@ the `[defaults]` section of your configuration file. │ --asr-openai-prompt TEXT Custom prompt to guide transcription │ │ (optional). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -602,7 +607,7 @@ the `[defaults]` section of your configuration file. │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -613,18 +618,14 @@ the `[defaults]` section of your configuration file. │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ │ the GEMINI_API_KEY environment variable. │ │ [env var: GEMINI_API_KEY] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ -│ --llm --no-llm Use an LLM to process the transcript. │ -│ [default: no-llm] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -763,20 +764,20 @@ uv tool install "agent-cli[vad]" │ 'gemini'). │ │ [default: ollama] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ @@ -786,7 +787,7 @@ uv tool install "agent-cli[vad]" │ --asr-openai-prompt TEXT Custom prompt to guide transcription │ │ (optional). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -794,7 +795,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -805,7 +806,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ @@ -816,7 +817,7 @@ uv tool install "agent-cli[vad]" │ --llm --no-llm Use an LLM to process the transcript. │ │ [default: no-llm] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ ╰──────────────────────────────────────────────────────────────────────────────╯ @@ -883,7 +884,7 @@ uv tool install "agent-cli[vad]" │ 'kokoro'). │ │ [default: wyoming] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration ─────────────────────────────────────────╮ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ │ --output-device-index INTEGER Index of the audio output device to │ │ use for TTS. │ │ --output-device-name TEXT Output device name keywords for │ @@ -893,7 +894,7 @@ uv tool install "agent-cli[vad]" │ speed). │ │ [default: 1.0] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Wyoming (local) ────────────────────────╮ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ │ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ │ [default: localhost] │ │ --tts-wyoming-port INTEGER Wyoming TTS server port. │ @@ -904,7 +905,7 @@ uv tool install "agent-cli[vad]" │ 'en_US'). │ │ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: OpenAI ─────────────────────────────────╮ +╭─ Audio Output: OpenAI ───────────────────────────────────────────────────────╮ │ --tts-openai-model TEXT The OpenAI model to use for TTS. │ │ [default: tts-1] │ │ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ @@ -913,7 +914,7 @@ uv tool install "agent-cli[vad]" │ API (e.g., http://localhost:8000/v1 for a │ │ proxy). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Kokoro ─────────────────────────────────╮ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ │ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ │ [default: kokoro] │ │ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ @@ -921,7 +922,7 @@ uv tool install "agent-cli[vad]" │ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ │ [default: http://localhost:8880/v1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --list-devices List available audio input and output devices and │ │ exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ @@ -935,7 +936,7 @@ uv tool install "agent-cli[vad]" │ --print-args Print the command line arguments, including │ │ variables taken from the configuration file. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -1007,25 +1008,25 @@ uv tool install "agent-cli[vad]" │ 'kokoro'). │ │ [default: wyoming] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -1033,7 +1034,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -1044,14 +1045,14 @@ uv tool install "agent-cli[vad]" │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ │ the GEMINI_API_KEY environment variable. │ │ [env var: GEMINI_API_KEY] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration ─────────────────────────────────────────╮ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ │ --tts --no-tts Enable text-to-speech for │ │ responses. │ │ [default: no-tts] │ @@ -1064,7 +1065,7 @@ uv tool install "agent-cli[vad]" │ 0.5 = half speed). │ │ [default: 1.0] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Wyoming (local) ────────────────────────╮ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ │ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ │ [default: localhost] │ │ --tts-wyoming-port INTEGER Wyoming TTS server port. │ @@ -1075,7 +1076,7 @@ uv tool install "agent-cli[vad]" │ 'en_US'). │ │ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: OpenAI ─────────────────────────────────╮ +╭─ Audio Output: OpenAI ───────────────────────────────────────────────────────╮ │ --tts-openai-model TEXT The OpenAI model to use for TTS. │ │ [default: tts-1] │ │ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ @@ -1084,7 +1085,7 @@ uv tool install "agent-cli[vad]" │ API (e.g., http://localhost:8000/v1 for a │ │ proxy). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Kokoro ─────────────────────────────────╮ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ │ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ │ [default: kokoro] │ │ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ @@ -1092,7 +1093,7 @@ uv tool install "agent-cli[vad]" │ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ │ [default: http://localhost:8880/v1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -1171,7 +1172,7 @@ uv tool install "agent-cli[vad]" │ 'kokoro'). │ │ [default: wyoming] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Wake Word Options ──────────────────────────────────────────────────────────╮ +╭─ Wake Word ──────────────────────────────────────────────────────────────────╮ │ --wake-server-ip TEXT Wyoming wake word server IP address. │ │ [default: localhost] │ │ --wake-server-port INTEGER Wyoming wake word server port. │ @@ -1180,25 +1181,25 @@ uv tool install "agent-cli[vad]" │ 'ok_nabu', 'hey_jarvis'). │ │ [default: ok_nabu] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -1206,7 +1207,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -1217,14 +1218,14 @@ uv tool install "agent-cli[vad]" │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ │ the GEMINI_API_KEY environment variable. │ │ [env var: GEMINI_API_KEY] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration ─────────────────────────────────────────╮ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ │ --tts --no-tts Enable text-to-speech for │ │ responses. │ │ [default: no-tts] │ @@ -1237,7 +1238,7 @@ uv tool install "agent-cli[vad]" │ 0.5 = half speed). │ │ [default: 1.0] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Wyoming (local) ────────────────────────╮ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ │ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ │ [default: localhost] │ │ --tts-wyoming-port INTEGER Wyoming TTS server port. │ @@ -1248,7 +1249,7 @@ uv tool install "agent-cli[vad]" │ 'en_US'). │ │ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: OpenAI ─────────────────────────────────╮ +╭─ Audio Output: OpenAI ───────────────────────────────────────────────────────╮ │ --tts-openai-model TEXT The OpenAI model to use for TTS. │ │ [default: tts-1] │ │ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ @@ -1257,7 +1258,7 @@ uv tool install "agent-cli[vad]" │ API (e.g., http://localhost:8000/v1 for a │ │ proxy). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Kokoro ─────────────────────────────────╮ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ │ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ │ [default: kokoro] │ │ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ @@ -1265,7 +1266,7 @@ uv tool install "agent-cli[vad]" │ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ │ [default: http://localhost:8880/v1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -1351,20 +1352,20 @@ uv tool install "agent-cli[vad]" │ 'kokoro'). │ │ [default: wyoming] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration ──────────────────────────────────────────────────╮ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ │ --input-device-index INTEGER Index of the audio input device to use. │ │ --input-device-name TEXT Device name keywords for partial │ │ matching. │ │ --list-devices List available audio input and output │ │ devices and exit. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: Wyoming (local) ─────────────────────────────────╮ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ │ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ │ [default: localhost] │ │ --asr-wyoming-port INTEGER Wyoming ASR server port. │ │ [default: 10300] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ ASR (Audio) Configuration: OpenAI ──────────────────────────────────────────╮ +╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ │ --asr-openai-model TEXT The OpenAI model to use for ASR │ │ (transcription). │ │ [default: whisper-1] │ @@ -1374,7 +1375,7 @@ uv tool install "agent-cli[vad]" │ --asr-openai-prompt TEXT Custom prompt to guide transcription │ │ (optional). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Ollama (local) ──────────────────────────────────────────╮ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ │ --llm-ollama-model TEXT The Ollama model to use. Default is │ │ gemma3:4b. │ │ [default: gemma3:4b] │ @@ -1382,7 +1383,7 @@ uv tool install "agent-cli[vad]" │ http://localhost:11434. │ │ [default: http://localhost:11434] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ │ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ │ [default: gpt-5-mini] │ │ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ @@ -1393,14 +1394,14 @@ uv tool install "agent-cli[vad]" │ http://localhost:8080/v1). │ │ [env var: OPENAI_BASE_URL] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: Gemini ──────────────────────────────────────────────────╮ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ │ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ │ [default: gemini-2.5-flash] │ │ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ │ the GEMINI_API_KEY environment variable. │ │ [env var: GEMINI_API_KEY] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration ─────────────────────────────────────────╮ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ │ --tts --no-tts Enable text-to-speech for │ │ responses. │ │ [default: no-tts] │ @@ -1413,7 +1414,7 @@ uv tool install "agent-cli[vad]" │ 0.5 = half speed). │ │ [default: 1.0] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Wyoming (local) ────────────────────────╮ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ │ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ │ [default: localhost] │ │ --tts-wyoming-port INTEGER Wyoming TTS server port. │ @@ -1424,7 +1425,7 @@ uv tool install "agent-cli[vad]" │ 'en_US'). │ │ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: OpenAI ─────────────────────────────────╮ +╭─ Audio Output: OpenAI ───────────────────────────────────────────────────────╮ │ --tts-openai-model TEXT The OpenAI model to use for TTS. │ │ [default: tts-1] │ │ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ @@ -1433,7 +1434,7 @@ uv tool install "agent-cli[vad]" │ API (e.g., http://localhost:8000/v1 for a │ │ proxy). │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ TTS (Text-to-Speech) Configuration: Kokoro ─────────────────────────────────╮ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ │ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ │ [default: kokoro] │ │ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ @@ -1441,7 +1442,7 @@ uv tool install "agent-cli[vad]" │ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ │ [default: http://localhost:8880/v1] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management Options ─────────────────────────────────────────────────╮ +╭─ Process Management ─────────────────────────────────────────────────────────╮ │ --stop Stop any running background process. │ │ --status Check if a background process is running. │ │ --toggle Toggle the background process on/off. If the process is │ @@ -1532,7 +1533,7 @@ uv tool install "agent-cli[vad]" │ insufficient. │ │ [default: rag-tools] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ │ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ │ (e.g., for llama-server: │ │ http://localhost:8080/v1). │ @@ -1686,7 +1687,7 @@ The `memory proxy` command is the core feature—a middleware server that gives │ [default: │ │ git-versioning] │ ╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration: OpenAI ──────────────────────────────────────────────────╮ +╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ │ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ │ (e.g., for llama-server: │ │ http://localhost:8080/v1). │ From 0ad7923d70925aa66bf3337a76654191602466dd Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:44:28 -0800 Subject: [PATCH 04/24] refactor(docs_gen): make helper functions private and add tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename internal functions to private: get_command_options, options_table, options_by_panel, list_commands → _prefixed versions - Add comprehensive test suite with 36 tests covering all public and private functions --- agent_cli/docs_gen.py | 77 +++-------- tests/test_docs_gen.py | 286 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 303 insertions(+), 60 deletions(-) create mode 100644 tests/test_docs_gen.py diff --git a/agent_cli/docs_gen.py b/agent_cli/docs_gen.py index 3abf2baf2..138526008 100644 --- a/agent_cli/docs_gen.py +++ b/agent_cli/docs_gen.py @@ -5,9 +5,9 @@ options tables in documentation. Example usage in Markdown files: - - - + + + ...auto-generated table... @@ -108,50 +108,23 @@ def _extract_options_from_click(cmd: click.Command) -> list[dict[str, Any]]: return options -def get_command_options(command_path: str) -> list[dict[str, Any]]: - """Extract all options from a Typer command. - - Args: - command_path: Command path like "transcribe" or "memory.proxy" - - Returns: - List of option dictionaries with keys: - - name: Option flag (e.g., "--input-device-index") - - type: Type string (e.g., "INTEGER", "TEXT") - - default: Default value or "-" if none - - help: Help text - - panel: Rich help panel name for grouping - - envvar: Environment variable name if any - - required: Whether the option is required - - is_flag: Whether it's a boolean flag - - """ +def _get_command_options(command_path: str) -> list[dict[str, Any]]: + """Extract all options from a Typer command.""" cmd = _get_click_command(command_path) if cmd is None: return [] return _extract_options_from_click(cmd) -def options_table( +def _options_table( command_path: str, panel: str | None = None, *, include_type: bool = True, include_default: bool = True, ) -> str: - """Generate a Markdown table of options for a command. - - Args: - command_path: Command path like "transcribe" or "memory.proxy" - panel: Filter to specific rich_help_panel, or None for all - include_type: Include the Type column - include_default: Include the Default column - - Returns: - Markdown table string - - """ - options = get_command_options(command_path) + """Generate a Markdown table of options for a command.""" + options = _get_command_options(command_path) if panel: options = [o for o in options if o["panel"] == panel] @@ -184,26 +157,15 @@ def options_table( return "\n".join(lines) -def options_by_panel( +def _options_by_panel( command_path: str, *, include_type: bool = True, include_default: bool = True, heading_level: int = 3, ) -> str: - """Generate options tables grouped by panel. - - Args: - command_path: Command path like "transcribe" or "memory.proxy" - include_type: Include the Type column - include_default: Include the Default column - heading_level: Markdown heading level for panel names - - Returns: - Markdown string with sectioned tables - - """ - options = get_command_options(command_path) + """Generate options tables grouped by panel.""" + options = _get_command_options(command_path) if not options: return "*No options found*" @@ -250,13 +212,8 @@ def options_by_panel( return "\n".join(output) -def list_commands() -> list[str]: - """List all available commands including subcommands. - - Returns: - List of command paths like ["transcribe", "memory.proxy", "memory.add"] - - """ +def _list_commands() -> list[str]: + """List all available commands including subcommands.""" click_app = get_command(app) commands = [] @@ -393,7 +350,7 @@ def config_example(command_path: str | None = None) -> str: # input_device_index = 1 # output_device_index = 0""" - options = get_command_options(command_path) + options = _get_command_options(command_path) if not options: return f"# No configurable options for {command_path}" @@ -437,7 +394,7 @@ def all_options_for_docs(command_path: str) -> str: Complete Markdown options section """ - return options_by_panel( + return _options_by_panel( command_path, include_type=False, # Types are often obvious and clutter the table include_default=True, @@ -448,12 +405,12 @@ def all_options_for_docs(command_path: str) -> str: if __name__ == "__main__": # Demo: print options for transcribe command print("=== Available Commands ===") - for cmd in list_commands(): + for cmd in _list_commands(): print(f" {cmd}") print() print("=== transcribe options by panel ===") - print(options_by_panel("transcribe")) + print(_options_by_panel("transcribe")) print("\n=== Environment Variables ===") print(env_vars_table()) diff --git a/tests/test_docs_gen.py b/tests/test_docs_gen.py new file mode 100644 index 000000000..addea298e --- /dev/null +++ b/tests/test_docs_gen.py @@ -0,0 +1,286 @@ +"""Tests for the docs_gen module.""" + +from __future__ import annotations + +from agent_cli.docs_gen import ( + _format_default, + _get_command_options, + _list_commands, + _options_by_panel, + _options_table, + all_options_for_docs, + commands_table, + config_example, + env_vars_table, + provider_matrix, +) + +# --- Tests for _format_default --- + + +def test_format_default_none_returns_dash() -> None: + """Test that None returns a dash.""" + assert _format_default(None) == "-" + + +def test_format_default_bool_true() -> None: + """Test that True returns lowercase 'true'.""" + assert _format_default(True) == "true" + + +def test_format_default_bool_false() -> None: + """Test that False returns lowercase 'false'.""" + assert _format_default(False) == "false" + + +def test_format_default_empty_string() -> None: + """Test that empty string returns quoted empty string.""" + assert _format_default("") == '""' + + +def test_format_default_string_value() -> None: + """Test that string values are returned as-is.""" + assert _format_default("hello") == "hello" + + +def test_format_default_integer_value() -> None: + """Test that integer values are converted to string.""" + assert _format_default(42) == "42" + + +# --- Tests for _get_command_options --- + + +def test_get_command_options_transcribe() -> None: + """Test that transcribe command options are extracted.""" + options = _get_command_options("transcribe") + assert len(options) > 0 + for opt in options: + assert "name" in opt + assert "type" in opt + assert "default" in opt + assert "help" in opt + assert "panel" in opt + + +def test_get_command_options_nonexistent() -> None: + """Test that nonexistent command returns empty list.""" + options = _get_command_options("nonexistent") + assert options == [] + + +def test_get_command_options_subcommand() -> None: + """Test that subcommand options are extracted.""" + options = _get_command_options("memory.proxy") + assert len(options) > 0 + + +# --- Tests for _options_table --- + + +def test_options_table_generates_markdown() -> None: + """Test that options_table generates valid markdown table.""" + table = _options_table("transcribe") + assert "|" in table + assert "Option" in table + assert "Description" in table + + +def test_options_table_filter_by_panel() -> None: + """Test that panel filtering works.""" + table = _options_table("transcribe", panel="LLM Configuration") + assert "--llm" in table + assert "--asr-wyoming-ip" not in table + + +def test_options_table_nonexistent_panel() -> None: + """Test that nonexistent panel returns appropriate message.""" + table = _options_table("transcribe", panel="Nonexistent Panel") + assert "No options found" in table + + +def test_options_table_include_type_false() -> None: + """Test that include_type=False excludes Type column.""" + table = _options_table("transcribe", include_type=False) + lines = table.split("\n") + header = lines[0] + assert "Option" in header + assert "Default" in header + assert "Description" in header + + +# --- Tests for _options_by_panel --- + + +def test_options_by_panel_groups() -> None: + """Test that options are grouped by panel with headers.""" + result = _options_by_panel("transcribe") + assert "### " in result or "## " in result + + +def test_options_by_panel_heading_level() -> None: + """Test that heading level parameter works.""" + result = _options_by_panel("transcribe", heading_level=2) + assert "## " in result + + +def test_options_by_panel_nonexistent_command() -> None: + """Test that nonexistent command returns appropriate message.""" + result = _options_by_panel("nonexistent") + assert "No options found" in result + + +# --- Tests for _list_commands --- + + +def test_list_commands_returns_list() -> None: + """Test that list_commands returns a list.""" + commands = _list_commands() + assert isinstance(commands, list) + assert len(commands) > 0 + + +def test_list_commands_includes_known() -> None: + """Test that known commands are in the list.""" + commands = _list_commands() + assert "transcribe" in commands + assert "speak" in commands + + +def test_list_commands_includes_subcommands() -> None: + """Test that subcommands are included.""" + commands = _list_commands() + assert any("memory" in cmd for cmd in commands) + + +def test_list_commands_sorted() -> None: + """Test that commands are sorted alphabetically.""" + commands = _list_commands() + assert commands == sorted(commands) + + +# --- Tests for all_options_for_docs --- + + +def test_all_options_for_docs_complete() -> None: + """Test that all_options_for_docs generates complete documentation.""" + result = all_options_for_docs("transcribe") + assert len(result) > 100 + assert "###" in result + assert "|" in result + + +def test_all_options_for_docs_includes_panels() -> None: + """Test that expected panels are included.""" + result = all_options_for_docs("transcribe") + assert "LLM Configuration" in result + assert "Audio Input" in result + assert "General Options" in result + + +def test_all_options_for_docs_nonexistent() -> None: + """Test that nonexistent command returns appropriate message.""" + result = all_options_for_docs("nonexistent") + assert "No options found" in result + + +# --- Tests for env_vars_table --- + + +def test_env_vars_table_generates() -> None: + """Test that env_vars_table generates valid table.""" + table = env_vars_table() + assert "|" in table + assert "Variable" in table + assert "Description" in table + + +def test_env_vars_table_includes_known() -> None: + """Test that known env vars are included.""" + table = env_vars_table() + assert "OPENAI_API_KEY" in table + assert "GEMINI_API_KEY" in table + + +# --- Tests for provider_matrix --- + + +def test_provider_matrix_generates() -> None: + """Test that provider_matrix generates valid table.""" + table = provider_matrix() + assert "|" in table + assert "Capability" in table + + +def test_provider_matrix_includes_providers() -> None: + """Test that known providers are included.""" + table = provider_matrix() + assert "ollama" in table + assert "openai" in table + assert "wyoming" in table + + +# --- Tests for commands_table --- + + +def test_commands_table_generates() -> None: + """Test that commands_table generates valid table.""" + table = commands_table() + assert "|" in table + assert "Command" in table + assert "Purpose" in table + + +def test_commands_table_includes_known() -> None: + """Test that known commands are included.""" + table = commands_table() + assert "transcribe" in table + assert "speak" in table + + +def test_commands_table_filter_by_category() -> None: + """Test that category filtering works.""" + table = commands_table(category="voice") + assert "transcribe" in table + assert "speak" in table + assert "install-services" not in table + + +def test_commands_table_nonexistent_category() -> None: + """Test that nonexistent category returns appropriate message.""" + table = commands_table(category="nonexistent") + assert "No commands found" in table + + +def test_commands_table_generates_links() -> None: + """Test that commands_table generates markdown links.""" + table = commands_table() + assert ".md)" in table + + +# --- Tests for config_example --- + + +def test_config_example_defaults() -> None: + """Test that config_example generates defaults section.""" + config = config_example() + assert "[defaults]" in config + assert "llm_provider" in config + + +def test_config_example_command() -> None: + """Test that config_example generates command section.""" + config = config_example("transcribe") + assert "[transcribe]" in config + + +def test_config_example_nonexistent() -> None: + """Test that nonexistent command returns appropriate message.""" + config = config_example("nonexistent") + assert "No configurable options" in config + + +def test_config_example_subcommand_section() -> None: + """Test that subcommand dots are replaced with dashes in section name.""" + config = config_example("memory.proxy") + assert "[memory-proxy]" in config From d3386f0323b8bbee2b9db6a28337c07cc90eb34d Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:52:27 -0800 Subject: [PATCH 05/24] docs(assistant): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using docs_gen.all_options_for_docs(). --- docs/commands/assistant.md | 180 +++++++++++++++++++------------------ 1 file changed, 92 insertions(+), 88 deletions(-) diff --git a/docs/commands/assistant.md b/docs/commands/assistant.md index 115b51b5f..cd06e8a2b 100644 --- a/docs/commands/assistant.md +++ b/docs/commands/assistant.md @@ -41,124 +41,128 @@ agent-cli assistant --wake-server-ip 192.168.1.100 --wake-server-port 10400 ## Options -### Wake Word Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `--wake-word` | Wake word name (e.g., 'ok_nabu', 'hey_jarvis') | `ok_nabu` | -| `--wake-server-ip` | Wyoming wake word server IP | `localhost` | -| `--wake-server-port` | Wyoming wake word server port | `10400` | - + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | -| `--tts-provider` | TTS provider: `wyoming`, `openai`, `kokoro` | `wyoming` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | +| `--tts-provider` | `wyoming` | The TTS provider to use ('wyoming', 'openai', 'kokoro'). | -### Audio Input +### Wake Word -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of audio input device | -| `--input-device-name` | Input device name keywords | -| `--list-devices` | List available devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--wake-server-ip` | `localhost` | Wyoming wake word server IP address. | +| `--wake-server-port` | `10400` | Wyoming wake word server port. | +| `--wake-word` | `ok_nabu` | Name of wake word to detect (e.g., 'ok_nabu', 'hey_jarvis'). | -### ASR (Wyoming, local) +### Audio Input -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### ASR (OpenAI) +### Audio Input: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### LLM (Ollama, local) +### Audio Input: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | -### LLM (OpenAI) +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (Gemini) +### LLM: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### TTS Options (General) +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--tts` / `--no-tts` | Enable text-to-speech responses | `false` | -| `--tts-speed` | Speech speed multiplier | `1.0` | -| `--output-device-index` | Index of audio output device | - | -| `--output-device-name` | Output device name keywords | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### TTS (Wyoming, local) +### Audio Output -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-wyoming-ip` | Wyoming TTS server IP | `localhost` | -| `--tts-wyoming-port` | Wyoming TTS server port | `10200` | -| `--tts-wyoming-voice` | Voice name for Wyoming TTS | - | -| `--tts-wyoming-language` | Language for Wyoming TTS | - | -| `--tts-wyoming-speaker` | Speaker name for Wyoming TTS voice | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts/--no-tts` | `false` | Enable text-to-speech for responses. | +| `--output-device-index` | - | Index of the audio output device to use for TTS. | +| `--output-device-name` | - | Output device name keywords for partial matching. | +| `--tts-speed` | `1.0` | Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed). | -### TTS (OpenAI) +### Audio Output: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-openai-model` | OpenAI TTS model | `tts-1` | -| `--tts-openai-voice` | OpenAI voice | `alloy` | -| `--tts-openai-base-url` | Custom OpenAI-compatible URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-wyoming-ip` | `localhost` | Wyoming TTS server IP address. | +| `--tts-wyoming-port` | `10200` | Wyoming TTS server port. | +| `--tts-wyoming-voice` | - | Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium'). | +| `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | +| `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### TTS (Kokoro) +### Audio Output: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-kokoro-model` | Kokoro model | `kokoro` | -| `--tts-kokoro-voice` | Kokoro voice | `af_sky` | -| `--tts-kokoro-host` | Kokoro API URL | `http://localhost:8880/v1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-openai-model` | `tts-1` | The OpenAI model to use for TTS. | +| `--tts-openai-voice` | `alloy` | The voice to use for OpenAI TTS. | +| `--tts-openai-base-url` | - | Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy). | -### Output Options +### Audio Output: Kokoro -| Option | Description | Default | -|--------|-------------|---------| -| `--clipboard` / `--no-clipboard` | Copy result to clipboard | `true` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-kokoro-model` | `kokoro` | The Kokoro model to use for TTS. | +| `--tts-kokoro-voice` | `af_sky` | The voice to use for Kokoro TTS. | +| `--tts-kokoro-host` | `http://localhost:8880/v1` | The base URL for the Kokoro API. | ### Process Management -| Option | Description | -|--------|-------------| -| `--stop` | Stop running assistant | -| `--status` | Check if assistant is running | -| `--toggle` | Toggle assistant on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | 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. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--save-file PATH` | Save TTS response audio to WAV file | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--save-file` | - | Save TTS response audio to WAV file. | +| `--clipboard/--no-clipboard` | `true` | Copy result to clipboard. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Available Wake Words From 558bde80199eea19c6dc3cf6ce3bb00dbce9c483 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:53:15 -0800 Subject: [PATCH 06/24] docs(autocorrect): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using docs_gen.all_options_for_docs(). --- docs/commands/autocorrect.md | 61 +++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 26 deletions(-) diff --git a/docs/commands/autocorrect.md b/docs/commands/autocorrect.md index 5c1ba739f..a21387893 100644 --- a/docs/commands/autocorrect.md +++ b/docs/commands/autocorrect.md @@ -34,43 +34,52 @@ agent-cli autocorrect "this text has an eror" ## Options + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | -### Ollama Configuration +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### OpenAI Configuration +### LLM: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### Gemini Configuration +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Workflow Integration From 12f05bb74d67e263f49842d412d5c43b78717155 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:54:21 -0800 Subject: [PATCH 07/24] docs(chat): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using docs_gen.all_options_for_docs(). --- docs/commands/chat.md | 175 ++++++++++++++++++++++-------------------- 1 file changed, 92 insertions(+), 83 deletions(-) diff --git a/docs/commands/chat.md b/docs/commands/chat.md index d7ff126b6..ab057d945 100644 --- a/docs/commands/chat.md +++ b/docs/commands/chat.md @@ -43,119 +43,128 @@ agent-cli chat --last-n-messages 100 --history-dir ~/.my-chat-history ## Options + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | -| `--tts-provider` | TTS provider: `wyoming`, `openai`, `kokoro` | `wyoming` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | +| `--tts-provider` | `wyoming` | The TTS provider to use ('wyoming', 'openai', 'kokoro'). | ### Audio Input -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of audio input device | -| `--input-device-name` | Input device name keywords | -| `--list-devices` | List available devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### ASR (Wyoming, local) +### Audio Input: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### ASR (OpenAI) +### Audio Input: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | -| `--asr-openai-base-url` | Custom Whisper server URL | - | -| `--asr-openai-prompt` | Custom prompt to guide transcription | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | +| `--asr-openai-base-url` | - | Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898). | +| `--asr-openai-prompt` | - | Custom prompt to guide transcription (optional). | -### LLM (Ollama, local) +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (OpenAI) +### LLM: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### LLM (Gemini) +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### TTS Options (General) +### Audio Output -| Option | Description | Default | -|--------|-------------|---------| -| `--tts` / `--no-tts` | Enable text-to-speech responses | `false` | -| `--tts-speed` | Speech speed multiplier | `1.0` | -| `--output-device-index` | Index of audio output device | - | -| `--output-device-name` | Output device name keywords | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts/--no-tts` | `false` | Enable text-to-speech for responses. | +| `--output-device-index` | - | Index of the audio output device to use for TTS. | +| `--output-device-name` | - | Output device name keywords for partial matching. | +| `--tts-speed` | `1.0` | Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed). | -### TTS (Wyoming, local) +### Audio Output: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-wyoming-ip` | Wyoming TTS server IP | `localhost` | -| `--tts-wyoming-port` | Wyoming TTS server port | `10200` | -| `--tts-wyoming-voice` | Voice name for Wyoming TTS | - | -| `--tts-wyoming-language` | Language for Wyoming TTS | - | -| `--tts-wyoming-speaker` | Speaker name for Wyoming TTS voice | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-wyoming-ip` | `localhost` | Wyoming TTS server IP address. | +| `--tts-wyoming-port` | `10200` | Wyoming TTS server port. | +| `--tts-wyoming-voice` | - | Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium'). | +| `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | +| `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### TTS (OpenAI) +### Audio Output: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-openai-model` | OpenAI TTS model | `tts-1` | -| `--tts-openai-voice` | OpenAI voice | `alloy` | -| `--tts-openai-base-url` | Custom OpenAI-compatible URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-openai-model` | `tts-1` | The OpenAI model to use for TTS. | +| `--tts-openai-voice` | `alloy` | The voice to use for OpenAI TTS. | +| `--tts-openai-base-url` | - | Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy). | -### TTS (Kokoro) +### Audio Output: Kokoro -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-kokoro-model` | Kokoro model | `kokoro` | -| `--tts-kokoro-voice` | Kokoro voice | `af_sky` | -| `--tts-kokoro-host` | Kokoro API URL | `http://localhost:8880/v1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-kokoro-model` | `kokoro` | The Kokoro model to use for TTS. | +| `--tts-kokoro-voice` | `af_sky` | The voice to use for Kokoro TTS. | +| `--tts-kokoro-host` | `http://localhost:8880/v1` | The base URL for the Kokoro API. | -### History Options +### Process Management -| Option | Description | Default | -|--------|-------------|---------| -| `--history-dir PATH` | Directory for conversation history | `~/.config/agent-cli/history` | -| `--last-n-messages N` | Number of messages to include (0 = disable) | `50` | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | 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. | -### Process Management +### History Options -| Option | Description | -|--------|-------------| -| `--stop` | Stop running chat | -| `--status` | Check if chat is running | -| `--toggle` | Toggle chat on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--history-dir` | `~/.config/agent-cli/history` | Directory to store conversation history. | +| `--last-n-messages` | `50` | Number of messages to include in the conversation history. Set to 0 to disable history. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--save-file PATH` | Save TTS audio to WAV file | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--save-file` | - | Save TTS response audio to WAV file. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Available Tools From 4dd791204f576737d7938815cba035b620e9c3bb Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:55:12 -0800 Subject: [PATCH 08/24] docs(speak): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using docs_gen.all_options_for_docs(). --- docs/commands/speak.md | 100 +++++++++++++++++++++++------------------ 1 file changed, 57 insertions(+), 43 deletions(-) diff --git a/docs/commands/speak.md b/docs/commands/speak.md index 5c84fa619..5dc9ce26a 100644 --- a/docs/commands/speak.md +++ b/docs/commands/speak.md @@ -38,65 +38,79 @@ agent-cli speak --list-devices ## Options + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-provider` | TTS provider: `wyoming`, `openai`, `kokoro` | `wyoming` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-provider` | `wyoming` | The TTS provider to use ('wyoming', 'openai', 'kokoro'). | ### Audio Output -| Option | Description | -|--------|-------------| -| `--output-device-index` | Index of audio output device | -| `--output-device-name` | Device name keywords for matching | -| `--tts-speed` | Speech speed multiplier (1.0 = normal) | -| `--list-devices` | List available audio devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--output-device-index` | - | Index of the audio output device to use for TTS. | +| `--output-device-name` | - | Output device name keywords for partial matching. | +| `--tts-speed` | `1.0` | Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed). | -### Wyoming (Local) Configuration +### Audio Output: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-wyoming-ip` | Wyoming TTS server IP | `localhost` | -| `--tts-wyoming-port` | Wyoming TTS server port | `10200` | -| `--tts-wyoming-voice` | Voice name (e.g., 'en_US-lessac-medium') | - | -| `--tts-wyoming-language` | Language (e.g., 'en_US') | - | -| `--tts-wyoming-speaker` | Speaker name for multi-speaker voices | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-wyoming-ip` | `localhost` | Wyoming TTS server IP address. | +| `--tts-wyoming-port` | `10200` | Wyoming TTS server port. | +| `--tts-wyoming-voice` | - | Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium'). | +| `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | +| `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### OpenAI Configuration +### Audio Output: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-openai-model` | OpenAI TTS model | `tts-1` | -| `--tts-openai-voice` | OpenAI voice | `alloy` | -| `--tts-openai-base-url` | Custom OpenAI-compatible URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-openai-model` | `tts-1` | The OpenAI model to use for TTS. | +| `--tts-openai-voice` | `alloy` | The voice to use for OpenAI TTS. | +| `--tts-openai-base-url` | - | Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy). | -### Kokoro Configuration +### Audio Output: Kokoro -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-kokoro-model` | Kokoro model | `kokoro` | -| `--tts-kokoro-voice` | Kokoro voice | `af_sky` | -| `--tts-kokoro-host` | Kokoro API URL | `http://localhost:8880/v1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-kokoro-model` | `kokoro` | The Kokoro model to use for TTS. | +| `--tts-kokoro-voice` | `af_sky` | The voice to use for Kokoro TTS. | +| `--tts-kokoro-host` | `http://localhost:8880/v1` | The base URL for the Kokoro API. | -### Process Management +### Audio Input -| Option | Description | -|--------|-------------| -| `--stop` | Stop running TTS process | -| `--status` | Check if TTS process is running | -| `--toggle` | Toggle TTS process on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--list-devices` | `false` | List available audio input and output devices and exit. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--save-file PATH` | Save TTS response audio to WAV file | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--save-file` | - | Save TTS response audio to WAV file. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + +### Process Management + +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | 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. | + + + ## Available Voices From 8df27e76c92e66413c6565f659eab6d862a7a3a6 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:56:58 -0800 Subject: [PATCH 09/24] docs(transcribe-daemon): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using all_options_for_docs() function. --- docs/commands/transcribe-daemon.md | 140 +++++++++++++++-------------- 1 file changed, 72 insertions(+), 68 deletions(-) diff --git a/docs/commands/transcribe-daemon.md b/docs/commands/transcribe-daemon.md index 6969418e4..e2bb1dce0 100644 --- a/docs/commands/transcribe-daemon.md +++ b/docs/commands/transcribe-daemon.md @@ -52,98 +52,102 @@ agent-cli transcribe-daemon --silence-threshold 1.5 ## Options -### VAD Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `-r`, `--role` | Role name for logging (e.g., 'meeting', 'notes') | `user` | -| `-s`, `--silence-threshold` | Seconds of silence to end a segment | `1.0` | -| `-m`, `--min-segment` | Minimum speech duration in seconds | `0.25` | -| `--vad-threshold` | Speech detection threshold (0.0-1.0) | `0.3` | - -### Audio Storage - -| Option | Description | Default | -|--------|-------------|---------| -| `--save-audio` / `--no-save-audio` | Save audio segments as MP3 | `true` | -| `--audio-dir PATH` | Directory for MP3 files | `~/.config/agent-cli/audio` | -| `-t`, `--transcription-log PATH` | JSON Lines log file | `~/.config/agent-cli/transcriptions.jsonl` | -| `--clipboard` / `--no-clipboard` | Copy each transcription to clipboard | `false` | + + + + + + +### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--role` | `user` | Role name for logging (e.g., 'meeting', 'notes', 'user'). | +| `--silence-threshold` | `1.0` | Seconds of silence to end a speech segment. | +| `--min-segment` | `0.25` | Minimum speech duration in seconds to trigger a segment. | +| `--vad-threshold` | `0.3` | VAD speech detection threshold (0.0-1.0). Higher = more aggressive filtering. | +| `--save-audio/--no-save-audio` | `true` | Save audio segments as MP3 files. | +| `--audio-dir` | - | Directory for MP3 files. Default: ~/.config/agent-cli/audio | +| `--transcription-log` | - | JSON Lines log file path. Default: ~/.config/agent-cli/transcriptions.jsonl | +| `--clipboard/--no-clipboard` | `false` | Copy each transcription to clipboard. | ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | ### Audio Input -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of audio input device | -| `--input-device-name` | Input device name keywords | -| `--list-devices` | List available devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### ASR (Wyoming, local) +### Audio Input: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### ASR (OpenAI) +### Audio Input: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | -| `--asr-openai-base-url` | Custom Whisper server URL | - | -| `--asr-openai-prompt` | Custom prompt to guide transcription | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | +| `--asr-openai-base-url` | - | Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898). | +| `--asr-openai-prompt` | - | Custom prompt to guide transcription (optional). | -### LLM (Ollama, local) +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (OpenAI) +### LLM: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### LLM (Gemini) +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### LLM Cleanup +### LLM Configuration -| Option | Description | Default | -|--------|-------------|---------| -| `--llm` / `--no-llm` | Use LLM to process transcript | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm/--no-llm` | `false` | Use an LLM to process the transcript. | ### Process Management -| Option | Description | -|--------|-------------| -| `--stop` | Stop running daemon | -| `--status` | Check if daemon is running | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Output Files From fbdaa86ad449633280dd806645c053d988743de0 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:57:51 -0800 Subject: [PATCH 10/24] docs(voice-edit): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using all_options_for_docs() function. --- docs/commands/voice-edit.md | 166 ++++++++++++++++++------------------ 1 file changed, 85 insertions(+), 81 deletions(-) diff --git a/docs/commands/voice-edit.md b/docs/commands/voice-edit.md index 5adbb2ba0..7f7742591 100644 --- a/docs/commands/voice-edit.md +++ b/docs/commands/voice-edit.md @@ -45,116 +45,120 @@ agent-cli voice-edit --stop ## Options + + + + + + ### Provider Selection -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-provider` | ASR provider: `wyoming`, `openai` | `wyoming` | -| `--llm-provider` | LLM provider: `ollama`, `openai`, `gemini` | `ollama` | -| `--tts-provider` | TTS provider: `wyoming`, `openai`, `kokoro` | `wyoming` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai'). | +| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). | +| `--tts-provider` | `wyoming` | The TTS provider to use ('wyoming', 'openai', 'kokoro'). | ### Audio Input -| Option | Description | -|--------|-------------| -| `--input-device-index` | Index of audio input device | -| `--input-device-name` | Input device name keywords | -| `--list-devices` | List available devices | +| Option | Default | Description | +|--------|---------|-------------| +| `--input-device-index` | - | Index of the audio input device to use. | +| `--input-device-name` | - | Device name keywords for partial matching. | +| `--list-devices` | `false` | List available audio input and output devices and exit. | -### ASR (Wyoming, local) +### Audio Input: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-wyoming-ip` | Wyoming ASR server IP | `localhost` | -| `--asr-wyoming-port` | Wyoming ASR server port | `10300` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | +| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### ASR (OpenAI) +### Audio Input: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--asr-openai-model` | OpenAI ASR model | `whisper-1` | +| Option | Default | Description | +|--------|---------|-------------| +| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). | -### LLM (Ollama, local) +### LLM: Ollama -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-ollama-model` | Ollama model to use | `gemma3:4b` | -| `--llm-ollama-host` | Ollama server URL | `http://localhost:11434` | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | +| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM (OpenAI) +### LLM: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-openai-model` | OpenAI model to use | `gpt-5-mini` | -| `--openai-api-key` | OpenAI API key (or set `OPENAI_API_KEY`) | - | -| `--openai-base-url` | Custom OpenAI-compatible API URL (or set `OPENAI_BASE_URL`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | -### LLM (Gemini) +### LLM: Gemini -| Option | Description | Default | -|--------|-------------|---------| -| `--llm-gemini-model` | Gemini model to use | `gemini-2.5-flash` | -| `--gemini-api-key` | Gemini API key (or set `GEMINI_API_KEY`) | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--llm-gemini-model` | `gemini-2.5-flash` | The Gemini model to use for LLM tasks. | +| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. | -### TTS Options (General) +### Audio Output -| Option | Description | Default | -|--------|-------------|---------| -| `--tts` / `--no-tts` | Enable text-to-speech response | `false` | -| `--tts-speed` | Speech speed multiplier | `1.0` | -| `--output-device-index` | Index of audio output device | - | -| `--output-device-name` | Output device name keywords | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts/--no-tts` | `false` | Enable text-to-speech for responses. | +| `--output-device-index` | - | Index of the audio output device to use for TTS. | +| `--output-device-name` | - | Output device name keywords for partial matching. | +| `--tts-speed` | `1.0` | Speech speed multiplier (1.0 = normal, 2.0 = twice as fast, 0.5 = half speed). | -### TTS (Wyoming, local) +### Audio Output: Wyoming -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-wyoming-ip` | Wyoming TTS server IP | `localhost` | -| `--tts-wyoming-port` | Wyoming TTS server port | `10200` | -| `--tts-wyoming-voice` | Voice name for Wyoming TTS | - | -| `--tts-wyoming-language` | Language for Wyoming TTS | - | -| `--tts-wyoming-speaker` | Speaker name for Wyoming TTS voice | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-wyoming-ip` | `localhost` | Wyoming TTS server IP address. | +| `--tts-wyoming-port` | `10200` | Wyoming TTS server port. | +| `--tts-wyoming-voice` | - | Voice name to use for Wyoming TTS (e.g., 'en_US-lessac-medium'). | +| `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | +| `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### TTS (OpenAI) +### Audio Output: OpenAI -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-openai-model` | OpenAI TTS model | `tts-1` | -| `--tts-openai-voice` | OpenAI voice | `alloy` | -| `--tts-openai-base-url` | Custom OpenAI-compatible URL | - | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-openai-model` | `tts-1` | The OpenAI model to use for TTS. | +| `--tts-openai-voice` | `alloy` | The voice to use for OpenAI TTS. | +| `--tts-openai-base-url` | - | Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy). | -### TTS (Kokoro) +### Audio Output: Kokoro -| Option | Description | Default | -|--------|-------------|---------| -| `--tts-kokoro-model` | Kokoro model | `kokoro` | -| `--tts-kokoro-voice` | Kokoro voice | `af_sky` | -| `--tts-kokoro-host` | Kokoro API URL | `http://localhost:8880/v1` | - -### Output Options - -| Option | Description | Default | -|--------|-------------|---------| -| `--clipboard` / `--no-clipboard` | Copy result to clipboard | `true` | +| Option | Default | Description | +|--------|---------|-------------| +| `--tts-kokoro-model` | `kokoro` | The Kokoro model to use for TTS. | +| `--tts-kokoro-voice` | `af_sky` | The voice to use for Kokoro TTS. | +| `--tts-kokoro-host` | `http://localhost:8880/v1` | The base URL for the Kokoro API. | ### Process Management -| Option | Description | -|--------|-------------| -| `--stop` | Stop running background process | -| `--status` | Check if process is running | -| `--toggle` | Toggle process on/off | +| Option | Default | Description | +|--------|---------|-------------| +| `--stop` | `false` | Stop any running background process. | +| `--status` | `false` | Check if a background process is running. | +| `--toggle` | `false` | 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. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--save-file PATH` | Save TTS response audio to WAV file | - | -| `--log-level` | Set logging level | `WARNING` | -| `--log-file PATH` | Path to a file to write logs to | - | -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--save-file` | - | Save TTS response audio to WAV file. | +| `--clipboard/--no-clipboard` | `true` | Copy result to clipboard. | +| `--log-level` | `WARNING` | Set logging level. | +| `--log-file` | - | Path to a file to write logs to. | +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Hotkey Integration From 31228185fc5797a0525f8bac1025e6a847c11c9f Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:58:51 -0800 Subject: [PATCH 11/24] docs(memory): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using all_options_for_docs() function for both memory.proxy and memory.add subcommands. --- docs/commands/memory.md | 117 ++++++++++++++++++++++++---------------- 1 file changed, 71 insertions(+), 46 deletions(-) diff --git a/docs/commands/memory.md b/docs/commands/memory.md index a1544a526..eb408b2fd 100644 --- a/docs/commands/memory.md +++ b/docs/commands/memory.md @@ -63,41 +63,55 @@ agent-cli chat --openai-base-url http://localhost:8100/v1 --llm-provider openai ### Options -#### Memory Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `--memory-path PATH` | Path to memory store | `./memory_db` | -| `--default-top-k N` | Memories to retrieve per query | `5` | -| `--max-entries N` | Max entries per conversation | `500` | -| `--mmr-lambda FLOAT` | MMR lambda (0-1): relevance vs diversity | `0.7` | -| `--recency-weight FLOAT` | Recency score weight (0-1) | `0.2` | -| `--score-threshold FLOAT` | Min semantic relevance threshold | `0.35` | -| `--summarization` / `--no-summarization` | Enable fact extraction & summaries | `true` | -| `--git-versioning` / `--no-git-versioning` | Enable git commits for changes | `true` | - -#### LLM Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `--openai-base-url` | OpenAI-compatible API URL | - | -| `--openai-api-key` | OpenAI API key | - | -| `--embedding-model` | Model for embeddings | `text-embedding-3-small` | - -#### Server Configuration - -| Option | Description | Default | -|--------|-------------|---------| -| `--host` | Host to bind to | `0.0.0.0` | -| `--port` | Port to bind to | `8100` | - -#### General Options - -| Option | Description | Default | -|--------|-------------|---------| -| `--log-level` | Logging level | `INFO` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | + + + + + + +### Memory Configuration + +| Option | Default | Description | +|--------|---------|-------------| +| `--memory-path` | `./memory_db` | Path to the memory store (files + derived vector index). | +| `--default-top-k` | `5` | Number of memory entries to retrieve per query. | +| `--max-entries` | `500` | Maximum stored memory entries per conversation (excluding summary). | +| `--mmr-lambda` | `0.7` | MMR lambda (0-1): higher favors relevance, lower favors diversity. | +| `--recency-weight` | `0.2` | Recency score weight (0.0-1.0). Controls freshness vs. relevance. Default 0.2 (20% recency, 80% semantic relevance). | +| `--score-threshold` | `0.35` | Minimum semantic relevance threshold (0.0-1.0). Memories below this score are discarded to reduce noise. | +| `--summarization/--no-summarization` | `true` | Enable automatic fact extraction and summaries. | +| `--git-versioning/--no-git-versioning` | `true` | Enable automatic git commit of memory changes. | + +### LLM: OpenAI + +| Option | Default | Description | +|--------|---------|-------------| +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | + +### LLM Configuration + +| Option | Default | Description | +|--------|---------|-------------| +| `--embedding-model` | `text-embedding-3-small` | Embedding model to use for vectorization. | + +### Server Configuration + +| Option | Default | Description | +|--------|---------|-------------| +| `--host` | `0.0.0.0` | Host/IP to bind API servers to. | +| `--port` | `8100` | Port to bind to | + +### General Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--log-level` | `INFO` | Set logging level. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + --- @@ -136,20 +150,31 @@ agent-cli memory add -c work "Project deadline is Friday" ### Options -| Option | Description | Default | -|--------|-------------|---------| -| `-f`, `--file PATH` | Read from file (use `-` for stdin) | - | -| `-c`, `--conversation-id` | Conversation ID to add memories to | `default` | -| `--memory-path PATH` | Path to memory store | `./memory_db` | -| `--git-versioning` / `--no-git-versioning` | Commit changes to git | `true` | + + + + + + +### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--file` | - | Read memories from file. Use '-' for stdin. Supports JSON array, JSON object with 'memories' key, or plain text (one per line). | +| `--conversation-id` | `default` | Conversation ID to add memories to. | +| `--memory-path` | `./memory_db` | Path to the memory store. | +| `--git-versioning/--no-git-versioning` | `true` | Commit changes to git. | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--quiet`, `-q` | Suppress console output | `false` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--quiet` | `false` | Suppress console output from rich. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ### File Format From 2c1059d96c9bfa51c36bc65c915f484f7d4fe296 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:59:24 -0800 Subject: [PATCH 12/24] docs(rag-proxy): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using all_options_for_docs() function. --- docs/commands/rag-proxy.md | 54 ++++++++++++++++++++++++-------------- 1 file changed, 34 insertions(+), 20 deletions(-) diff --git a/docs/commands/rag-proxy.md b/docs/commands/rag-proxy.md index 52f59ec19..418e92c70 100644 --- a/docs/commands/rag-proxy.md +++ b/docs/commands/rag-proxy.md @@ -52,37 +52,51 @@ agent-cli chat --openai-base-url http://localhost:8000/v1 --llm-provider openai ## Options + + + + + + ### RAG Configuration -| Option | Description | Default | -|--------|-------------|---------| -| `--docs-folder PATH` | Folder to watch for documents | `./rag_docs` | -| `--chroma-path PATH` | ChromaDB persistence directory | `./rag_db` | -| `--limit N` | Number of chunks to retrieve per query | `3` | -| `--rag-tools` / `--no-rag-tools` | Allow agent to fetch full documents | `true` | +| Option | Default | Description | +|--------|---------|-------------| +| `--docs-folder` | `./rag_docs` | Folder to watch for documents | +| `--chroma-path` | `./rag_db` | Path to ChromaDB persistence directory | +| `--limit` | `3` | Number of document chunks to retrieve per query. | +| `--rag-tools/--no-rag-tools` | `true` | Allow agent to fetch full documents when snippets are insufficient. | + +### LLM: OpenAI + +| Option | Default | Description | +|--------|---------|-------------| +| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). | +| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. | ### LLM Configuration -| Option | Description | -|--------|-------------| -| `--openai-base-url` | OpenAI-compatible API URL (e.g., Ollama) | -| `--openai-api-key` | OpenAI API key | -| `--embedding-model` | Model for embeddings | `text-embedding-3-small` | +| Option | Default | Description | +|--------|---------|-------------| +| `--embedding-model` | `text-embedding-3-small` | Embedding model to use for vectorization. | ### Server Configuration -| Option | Description | Default | -|--------|-------------|---------| -| `--host` | Host/IP to bind to | `0.0.0.0` | -| `--port` | Port to bind to | `8000` | +| Option | Default | Description | +|--------|---------|-------------| +| `--host` | `0.0.0.0` | Host/IP to bind API servers to. | +| `--port` | `8000` | Port to bind to | ### General Options -| Option | Description | Default | -|--------|-------------|---------| -| `--log-level` | Logging level | `INFO` | -| `--config PATH` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments including config values | `false` | +| Option | Default | Description | +|--------|---------|-------------| +| `--log-level` | `INFO` | Set logging level. | +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Supported Document Types From 7df44ae7e2425c87ace954186f9e02f7bf5e8d02 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 00:59:52 -0800 Subject: [PATCH 13/24] docs(server): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using all_options_for_docs() function. --- docs/commands/server.md | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/commands/server.md b/docs/commands/server.md index 4e6384990..9a50b39ac 100644 --- a/docs/commands/server.md +++ b/docs/commands/server.md @@ -35,13 +35,29 @@ agent-cli server --reload ## Options -| Option | Description | Default | -|--------|-------------|---------| -| `--host` | Host/IP to bind the server to | `0.0.0.0` | -| `--port` | Port to bind the server to | `61337` | -| `--reload` | Enable auto-reload for development | `false` | -| `--config` | Path to a TOML configuration file | - | -| `--print-args` | Print resolved arguments | - | + + + + + + +### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--host` | `0.0.0.0` | Host to bind the server to | +| `--port` | `61337` | Port to bind the server to | +| `--reload` | `false` | Enable auto-reload for development | + +### General Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--config` | - | Path to a TOML configuration file. | +| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. | + + + ## Installation From 1b908221f9b4688fc7c128b076e46cd456dce44c Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:00:39 -0800 Subject: [PATCH 14/24] docs(start-services): convert to auto-generated options tables Replace hand-written options tables with markdown-code-runner auto-generation using all_options_for_docs() function. --- docs/commands/start-services.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/commands/start-services.md b/docs/commands/start-services.md index fa8b9ff58..3016e16cc 100644 --- a/docs/commands/start-services.md +++ b/docs/commands/start-services.md @@ -25,10 +25,20 @@ Services run inside a Zellij session named `agent-cli`. ## Options -| Option | Description | Default | -|--------|-------------|---------| -| `--attach` / `--no-attach` | Attach to the Zellij session after starting | `true` | -| `--help`, `-h` | Show help for the command | - | + + + + + + +### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--attach/--no-attach` | `true` | Attach to Zellij session after starting | + + + ## Examples From d2dc7db50391a1f4e488b3c7e07adf24f4f6bc5b Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:04:06 -0800 Subject: [PATCH 15/24] docs: add script to update all auto-generated content Finds all markdown files with CODE:START markers and runs markdown-code-runner on them. --- docs/update_docs.py | 64 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100755 docs/update_docs.py diff --git a/docs/update_docs.py b/docs/update_docs.py new file mode 100755 index 000000000..4e5168e50 --- /dev/null +++ b/docs/update_docs.py @@ -0,0 +1,64 @@ +#!/usr/bin/env python3 +"""Update all markdown files that use markdown-code-runner for auto-generation.""" + +from __future__ import annotations + +import subprocess +import sys +from pathlib import Path + + +def find_markdown_files_with_code_blocks(docs_dir: Path) -> list[Path]: + """Find all markdown files containing CODE:START markers.""" + files_with_code = [] + for md_file in docs_dir.rglob("*.md"): + content = md_file.read_text() + if "" in content: + files_with_code.append(md_file) + return sorted(files_with_code) + + +def run_markdown_code_runner(files: list[Path]) -> bool: + """Run markdown-code-runner on all files. Returns True if all succeeded.""" + if not files: + print("No files with CODE:START markers found.") + return True + + print(f"Found {len(files)} file(s) with auto-generated content:") + for f in files: + print(f" - {f}") + print() + + all_success = True + for file in files: + print(f"Updating {file}...", end=" ") + result = subprocess.run( + ["markdown-code-runner", str(file)], # noqa: S607 + check=False, + capture_output=True, + text=True, + ) + if result.returncode == 0: + print("✓") + else: + print("✗") + print(f" Error: {result.stderr}") + all_success = False + + return all_success + + +def main() -> int: + """Main entry point.""" + docs_dir = Path(__file__).parent + if not docs_dir.exists(): + print(f"Error: docs directory not found at {docs_dir}") + return 1 + + files = find_markdown_files_with_code_blocks(docs_dir) + success = run_markdown_code_runner(files) + return 0 if success else 1 + + +if __name__ == "__main__": + sys.exit(main()) From 4b64fc2001c2200a5d82481ca66be94235d691d9 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:06:10 -0800 Subject: [PATCH 16/24] docs: use rich for update_docs.py output --- docs/update_docs.py | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/update_docs.py b/docs/update_docs.py index 4e5168e50..26d9288ec 100755 --- a/docs/update_docs.py +++ b/docs/update_docs.py @@ -1,5 +1,8 @@ #!/usr/bin/env python3 -"""Update all markdown files that use markdown-code-runner for auto-generation.""" +"""Update all markdown files that use markdown-code-runner for auto-generation. + +Run from repo root: python docs/update_docs.py +""" from __future__ import annotations @@ -7,6 +10,10 @@ import sys from pathlib import Path +from rich.console import Console + +console = Console() + def find_markdown_files_with_code_blocks(docs_dir: Path) -> list[Path]: """Find all markdown files containing CODE:START markers.""" @@ -21,17 +28,17 @@ def find_markdown_files_with_code_blocks(docs_dir: Path) -> list[Path]: def run_markdown_code_runner(files: list[Path]) -> bool: """Run markdown-code-runner on all files. Returns True if all succeeded.""" if not files: - print("No files with CODE:START markers found.") + console.print("No files with CODE:START markers found.") return True - print(f"Found {len(files)} file(s) with auto-generated content:") + console.print(f"Found {len(files)} file(s) with auto-generated content:") for f in files: - print(f" - {f}") - print() + console.print(f" - {f}") + console.print() all_success = True for file in files: - print(f"Updating {file}...", end=" ") + console.print(f"Updating {file}...", end=" ") result = subprocess.run( ["markdown-code-runner", str(file)], # noqa: S607 check=False, @@ -39,10 +46,10 @@ def run_markdown_code_runner(files: list[Path]) -> bool: text=True, ) if result.returncode == 0: - print("✓") + console.print("[green]✓[/green]") else: - print("✗") - print(f" Error: {result.stderr}") + console.print("[red]✗[/red]") + console.print(f" [red]Error:[/red] {result.stderr}") all_success = False return all_success @@ -52,7 +59,7 @@ def main() -> int: """Main entry point.""" docs_dir = Path(__file__).parent if not docs_dir.exists(): - print(f"Error: docs directory not found at {docs_dir}") + console.print(f"[red]Error:[/red] docs directory not found at {docs_dir}") return 1 files = find_markdown_files_with_code_blocks(docs_dir) From acd959c964d08e122b5ac1960b5fa8f87588e130 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:06:50 -0800 Subject: [PATCH 17/24] docs: show relative paths in update_docs.py output --- docs/update_docs.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/update_docs.py b/docs/update_docs.py index 26d9288ec..3c64b3de9 100755 --- a/docs/update_docs.py +++ b/docs/update_docs.py @@ -25,7 +25,7 @@ def find_markdown_files_with_code_blocks(docs_dir: Path) -> list[Path]: return sorted(files_with_code) -def run_markdown_code_runner(files: list[Path]) -> bool: +def run_markdown_code_runner(files: list[Path], repo_root: Path) -> bool: """Run markdown-code-runner on all files. Returns True if all succeeded.""" if not files: console.print("No files with CODE:START markers found.") @@ -33,12 +33,13 @@ def run_markdown_code_runner(files: list[Path]) -> bool: console.print(f"Found {len(files)} file(s) with auto-generated content:") for f in files: - console.print(f" - {f}") + console.print(f" - {f.relative_to(repo_root)}") console.print() all_success = True for file in files: - console.print(f"Updating {file}...", end=" ") + rel_path = file.relative_to(repo_root) + console.print(f"Updating {rel_path}...", end=" ") result = subprocess.run( ["markdown-code-runner", str(file)], # noqa: S607 check=False, @@ -57,13 +58,14 @@ def run_markdown_code_runner(files: list[Path]) -> bool: def main() -> int: """Main entry point.""" - docs_dir = Path(__file__).parent + repo_root = Path(__file__).parent.parent + docs_dir = repo_root / "docs" if not docs_dir.exists(): console.print(f"[red]Error:[/red] docs directory not found at {docs_dir}") return 1 files = find_markdown_files_with_code_blocks(docs_dir) - success = run_markdown_code_runner(files) + success = run_markdown_code_runner(files, repo_root) return 0 if success else 1 From 1894fa64fb6a5ac708b8953eb36b1784c4b8bc13 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:07:45 -0800 Subject: [PATCH 18/24] docs: search entire repo for auto-generated content --- docs/update_docs.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/update_docs.py b/docs/update_docs.py index 3c64b3de9..a8f014627 100755 --- a/docs/update_docs.py +++ b/docs/update_docs.py @@ -59,12 +59,8 @@ def run_markdown_code_runner(files: list[Path], repo_root: Path) -> bool: def main() -> int: """Main entry point.""" repo_root = Path(__file__).parent.parent - docs_dir = repo_root / "docs" - if not docs_dir.exists(): - console.print(f"[red]Error:[/red] docs directory not found at {docs_dir}") - return 1 - files = find_markdown_files_with_code_blocks(docs_dir) + files = find_markdown_files_with_code_blocks(repo_root) success = run_markdown_code_runner(files, repo_root) return 0 if success else 1 From 3b869e8005fe021b3bbf31d1ed927f3bd6575fc6 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:08:19 -0800 Subject: [PATCH 19/24] ci: update workflow to run update_docs.py on all markdown files Renamed update-readme.yml to update-docs.yml and now runs the update_docs.py script which updates all files with CODE:START markers. --- .../{update-readme.yml => update-docs.yml} | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) rename .github/workflows/{update-readme.yml => update-docs.yml} (74%) diff --git a/.github/workflows/update-readme.yml b/.github/workflows/update-docs.yml similarity index 74% rename from .github/workflows/update-readme.yml rename to .github/workflows/update-docs.yml index b3ff51f28..81b672bea 100644 --- a/.github/workflows/update-readme.yml +++ b/.github/workflows/update-docs.yml @@ -1,4 +1,4 @@ -name: Update README.md +name: Update docs on: push: @@ -7,7 +7,7 @@ on: pull_request: jobs: - update_readme: + update_docs: runs-on: macos-latest steps: - name: Check out repository @@ -22,26 +22,27 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 - - name: Run markdown-code-runner + - name: Run update_docs.py env: TERM: dumb NO_COLOR: 1 TERMINAL_WIDTH: 90 run: | - uvx --with . markdown-code-runner README.md - sed -i '' 's/[[:space:]]*$//' README.md + uv sync + uv run python docs/update_docs.py + find . -name "*.md" -exec sed -i '' 's/[[:space:]]*$//' {} \; - - name: Commit updated README.md + - name: Commit updated docs id: commit run: | - git add README.md + git add -A git config --local user.email "github-actions[bot]@users.noreply.github.com" git config --local user.name "github-actions[bot]" if git diff --quiet && git diff --staged --quiet; then - echo "No changes in README.md, skipping commit." + echo "No changes in docs, skipping commit." echo "commit_status=skipped" >> $GITHUB_ENV else - git commit -m "Update README.md" + git commit -m "Update auto-generated docs" echo "commit_status=committed" >> $GITHUB_ENV fi From 59d4b8245c688b8640f192f0e9595da6f798b7bd Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:09:29 -0800 Subject: [PATCH 20/24] refactor(opts): rename OpenAI panels to OpenAI-compatible --- agent_cli/opts.py | 18 +++++++++--------- docs/commands/assistant.md | 6 +++--- docs/commands/autocorrect.md | 2 +- docs/commands/chat.md | 6 +++--- docs/commands/memory.md | 2 +- docs/commands/rag-proxy.md | 2 +- docs/commands/speak.md | 2 +- docs/commands/transcribe-daemon.md | 4 ++-- docs/commands/transcribe.md | 4 ++-- docs/commands/voice-edit.md | 6 +++--- 10 files changed, 26 insertions(+), 26 deletions(-) diff --git a/agent_cli/opts.py b/agent_cli/opts.py index d736b4bf7..d0cca5633 100644 --- a/agent_cli/opts.py +++ b/agent_cli/opts.py @@ -62,21 +62,21 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: DEFAULT_OPENAI_MODEL, "--llm-openai-model", help="The OpenAI model to use for LLM tasks.", - rich_help_panel="LLM: OpenAI", + rich_help_panel="LLM: OpenAI-compatible", ) OPENAI_API_KEY: str | None = typer.Option( None, "--openai-api-key", help="Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable.", envvar="OPENAI_API_KEY", - rich_help_panel="LLM: OpenAI", + rich_help_panel="LLM: OpenAI-compatible", ) OPENAI_BASE_URL: str | None = typer.Option( None, "--openai-base-url", help="Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1).", envvar="OPENAI_BASE_URL", - rich_help_panel="LLM: OpenAI", + rich_help_panel="LLM: OpenAI-compatible", ) # Gemini LLM_GEMINI_MODEL: str = typer.Option( @@ -138,19 +138,19 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: "whisper-1", "--asr-openai-model", help="The OpenAI model to use for ASR (transcription).", - rich_help_panel="Audio Input: OpenAI", + rich_help_panel="Audio Input: OpenAI-compatible", ) ASR_OPENAI_BASE_URL: str | None = typer.Option( None, "--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", + rich_help_panel="Audio Input: OpenAI-compatible", ) ASR_OPENAI_PROMPT: str | None = typer.Option( None, "--asr-openai-prompt", help="Custom prompt to guide transcription (optional).", - rich_help_panel="Audio Input: OpenAI", + rich_help_panel="Audio Input: OpenAI-compatible", ) @@ -237,19 +237,19 @@ def with_default(option: OptionInfo, default: str) -> OptionInfo: "tts-1", "--tts-openai-model", help="The OpenAI model to use for TTS.", - rich_help_panel="Audio Output: OpenAI", + rich_help_panel="Audio Output: OpenAI-compatible", ) TTS_OPENAI_VOICE: str = typer.Option( "alloy", "--tts-openai-voice", help="The voice to use for OpenAI TTS.", - rich_help_panel="Audio Output: OpenAI", + rich_help_panel="Audio Output: OpenAI-compatible", ) TTS_OPENAI_BASE_URL: str | None = typer.Option( None, "--tts-openai-base-url", help="Custom base URL for OpenAI-compatible TTS API (e.g., http://localhost:8000/v1 for a proxy).", - rich_help_panel="Audio Output: OpenAI", + rich_help_panel="Audio Output: OpenAI-compatible", ) diff --git a/docs/commands/assistant.md b/docs/commands/assistant.md index cd06e8a2b..2e5f87718 100644 --- a/docs/commands/assistant.md +++ b/docs/commands/assistant.md @@ -78,7 +78,7 @@ agent-cli assistant --wake-server-ip 192.168.1.100 --wake-server-port 10400 | `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | | `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### Audio Input: OpenAI +### Audio Input: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| @@ -91,7 +91,7 @@ agent-cli assistant --wake-server-ip 192.168.1.100 --wake-server-port 10400 | `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | | `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM: OpenAI +### LLM: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| @@ -125,7 +125,7 @@ agent-cli assistant --wake-server-ip 192.168.1.100 --wake-server-port 10400 | `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | | `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### Audio Output: OpenAI +### Audio Output: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| diff --git a/docs/commands/autocorrect.md b/docs/commands/autocorrect.md index a21387893..95ccfa18f 100644 --- a/docs/commands/autocorrect.md +++ b/docs/commands/autocorrect.md @@ -53,7 +53,7 @@ agent-cli autocorrect "this text has an eror" | `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | | `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM: OpenAI +### LLM: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| diff --git a/docs/commands/chat.md b/docs/commands/chat.md index ab057d945..2eb2c64b8 100644 --- a/docs/commands/chat.md +++ b/docs/commands/chat.md @@ -72,7 +72,7 @@ agent-cli chat --last-n-messages 100 --history-dir ~/.my-chat-history | `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | | `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### Audio Input: OpenAI +### Audio Input: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| @@ -87,7 +87,7 @@ agent-cli chat --last-n-messages 100 --history-dir ~/.my-chat-history | `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | | `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM: OpenAI +### LLM: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| @@ -121,7 +121,7 @@ agent-cli chat --last-n-messages 100 --history-dir ~/.my-chat-history | `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | | `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### Audio Output: OpenAI +### Audio Output: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| diff --git a/docs/commands/memory.md b/docs/commands/memory.md index eb408b2fd..5ff97a459 100644 --- a/docs/commands/memory.md +++ b/docs/commands/memory.md @@ -82,7 +82,7 @@ agent-cli chat --openai-base-url http://localhost:8100/v1 --llm-provider openai | `--summarization/--no-summarization` | `true` | Enable automatic fact extraction and summaries. | | `--git-versioning/--no-git-versioning` | `true` | Enable automatic git commit of memory changes. | -### LLM: OpenAI +### LLM: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| diff --git a/docs/commands/rag-proxy.md b/docs/commands/rag-proxy.md index 418e92c70..e452dc0b8 100644 --- a/docs/commands/rag-proxy.md +++ b/docs/commands/rag-proxy.md @@ -67,7 +67,7 @@ agent-cli chat --openai-base-url http://localhost:8000/v1 --llm-provider openai | `--limit` | `3` | Number of document chunks to retrieve per query. | | `--rag-tools/--no-rag-tools` | `true` | Allow agent to fetch full documents when snippets are insufficient. | -### LLM: OpenAI +### LLM: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| diff --git a/docs/commands/speak.md b/docs/commands/speak.md index 5dc9ce26a..0a3709896 100644 --- a/docs/commands/speak.md +++ b/docs/commands/speak.md @@ -68,7 +68,7 @@ agent-cli speak --list-devices | `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | | `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### Audio Output: OpenAI +### Audio Output: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| diff --git a/docs/commands/transcribe-daemon.md b/docs/commands/transcribe-daemon.md index e2bb1dce0..61fee5f21 100644 --- a/docs/commands/transcribe-daemon.md +++ b/docs/commands/transcribe-daemon.md @@ -93,7 +93,7 @@ agent-cli transcribe-daemon --silence-threshold 1.5 | `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | | `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### Audio Input: OpenAI +### Audio Input: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| @@ -108,7 +108,7 @@ agent-cli transcribe-daemon --silence-threshold 1.5 | `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | | `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM: OpenAI +### LLM: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| diff --git a/docs/commands/transcribe.md b/docs/commands/transcribe.md index 1ef938ddb..c79f8aa74 100644 --- a/docs/commands/transcribe.md +++ b/docs/commands/transcribe.md @@ -86,7 +86,7 @@ agent-cli transcribe --last-recording 1 | `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | | `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### Audio Input: OpenAI +### Audio Input: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| @@ -101,7 +101,7 @@ agent-cli transcribe --last-recording 1 | `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | | `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM: OpenAI +### LLM: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| diff --git a/docs/commands/voice-edit.md b/docs/commands/voice-edit.md index 7f7742591..a92cc6c2c 100644 --- a/docs/commands/voice-edit.md +++ b/docs/commands/voice-edit.md @@ -74,7 +74,7 @@ agent-cli voice-edit --stop | `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. | | `--asr-wyoming-port` | `10300` | Wyoming ASR server port. | -### Audio Input: OpenAI +### Audio Input: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| @@ -87,7 +87,7 @@ agent-cli voice-edit --stop | `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. | | `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. | -### LLM: OpenAI +### LLM: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| @@ -121,7 +121,7 @@ agent-cli voice-edit --stop | `--tts-wyoming-language` | - | Language for Wyoming TTS (e.g., 'en_US'). | | `--tts-wyoming-speaker` | - | Speaker name for Wyoming TTS voice. | -### Audio Output: OpenAI +### Audio Output: OpenAI-compatible | Option | Default | Description | |--------|---------|-------------| From ee2e4ed17f68754b4b84fc3f72e03491d924172b Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:11:39 -0800 Subject: [PATCH 21/24] docs: remove navigation.sections to keep sidebar collapsed by default --- zensical.toml | 1 - 1 file changed, 1 deletion(-) diff --git a/zensical.toml b/zensical.toml index d11e87f2c..106faea7a 100644 --- a/zensical.toml +++ b/zensical.toml @@ -75,7 +75,6 @@ features = [ "navigation.instant", "navigation.instant.prefetch", "navigation.path", - "navigation.sections", "navigation.top", "navigation.tracking", "search.highlight", From 042b365aaba7efa5d436fbc4015f56297192ea47 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:13:57 -0800 Subject: [PATCH 22/24] ci: rename update-docs.yml to markdown-code-runner.yml --- .github/workflows/{update-docs.yml => markdown-code-runner.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{update-docs.yml => markdown-code-runner.yml} (100%) diff --git a/.github/workflows/update-docs.yml b/.github/workflows/markdown-code-runner.yml similarity index 100% rename from .github/workflows/update-docs.yml rename to .github/workflows/markdown-code-runner.yml From 649dac5448a877851c37f03dd8a9270896cd4a1d Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sat, 3 Jan 2026 01:15:16 -0800 Subject: [PATCH 23/24] fix: update README with new panel names and improve update_docs.py - Regenerate README.md CLI output with OpenAI-compatible panel names - Update update_docs.py to also detect CODE:BASH:START markers --- README.md | 1679 ++++++++++++++++++++----------------------- docs/update_docs.py | 5 +- 2 files changed, 789 insertions(+), 895 deletions(-) diff --git a/README.md b/README.md index ed932715d..c2860caa8 100644 --- a/README.md +++ b/README.md @@ -387,14 +387,14 @@ agent-cli config edit Manage agent-cli configuration files. -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Commands ───────────────────────────────────────────────────────────────────╮ -│ init Create a new config file with all options commented out. │ -│ edit Open the config file in your default editor. │ -│ show Display the config file location and contents. │ -╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮ +│ init Create a new config file with all options commented out. │ +│ edit Open the config file in your default editor. │ +│ show Display the config file location and contents. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -453,53 +453,49 @@ the `[defaults]` section of your configuration file. Correct text from clipboard using a local or remote LLM. -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ text [TEXT] The text to correct. If not provided, reads from │ -│ clipboard. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ─────────────────────────────────────────────────────────╮ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ -│ 'gemini'). │ -│ [default: ollama] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is │ -│ gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ -│ the OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ -│ (e.g., for llama-server: │ -│ http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ -│ the GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including │ -│ variables taken from the configuration file. │ -╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ text [TEXT] The text to correct. If not provided, reads from clipboard. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ +│ [default: ollama] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ +│ llama-server: http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ +│ GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including variables │ +│ taken from the configuration file. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -544,114 +540,98 @@ the `[defaults]` section of your configuration file. Wyoming ASR Client for streaming microphone audio to a transcription server. -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ -│ --extra-instructions TEXT Additional instructions for the │ -│ LLM to process the transcription. │ -│ --llm --no-llm Use an LLM to process the │ -│ transcript. │ -│ [default: no-llm] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Recovery ─────────────────────────────────────────────────────────────╮ -│ --from-file PATH Transcribe audio from a │ -│ saved WAV file instead │ -│ of recording. │ -│ --last-recording INTEGER Transcribe a saved │ -│ recording. Use 1 for │ -│ most recent, 2 for │ -│ second-to-last, etc. Use │ -│ 0 to disable (default). │ -│ [default: 0] │ -│ --save-recording --no-save-recording Save the audio recording │ -│ to disk for recovery. │ -│ [default: │ -│ save-recording] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ─────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ -│ 'gemini'). │ -│ [default: ollama] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial │ -│ matching. │ -│ --list-devices List available audio input and output │ -│ devices and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR │ -│ (transcription). │ -│ [default: whisper-1] │ -│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR │ -│ API (e.g., for custom Whisper server: │ -│ http://localhost:9898). │ -│ --asr-openai-prompt TEXT Custom prompt to guide transcription │ -│ (optional). │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is │ -│ gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ -│ the OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ -│ (e.g., for llama-server: │ -│ http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ -│ the GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ─────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --clipboard --no-clipboard Copy result to clipboard. │ -│ [default: clipboard] │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write │ -│ logs to. │ -│ --quiet -q Suppress console output │ -│ from rich. │ -│ --config TEXT Path to a TOML │ -│ configuration file. │ -│ --print-args Print the command line │ -│ arguments, including │ -│ variables taken from the │ -│ configuration file. │ -│ --transcription-log PATH Path to log transcription │ -│ results with timestamps, │ -│ hostname, model, and raw │ -│ output. │ -╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮ +│ --extra-instructions TEXT Additional instructions for the LLM to │ +│ process the transcription. │ +│ --llm --no-llm Use an LLM to process the transcript. │ +│ [default: no-llm] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Recovery ───────────────────────────────────────────────────────────────────────╮ +│ --from-file PATH Transcribe audio from a saved WAV │ +│ file instead of recording. │ +│ --last-recording INTEGER Transcribe a saved recording. Use │ +│ 1 for most recent, 2 for │ +│ second-to-last, etc. Use 0 to │ +│ disable (default). │ +│ [default: 0] │ +│ --save-recording --no-save-recording Save the audio recording to disk │ +│ for recovery. │ +│ [default: save-recording] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ +│ [default: ollama] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial matching. │ +│ --list-devices List available audio input and output devices and │ +│ exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ +│ [default: whisper-1] │ +│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR API │ +│ (e.g., for custom Whisper server: │ +│ http://localhost:9898). │ +│ --asr-openai-prompt TEXT Custom prompt to guide transcription (optional). │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ +│ llama-server: http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ +│ GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ───────────────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --clipboard --no-clipboard Copy result to clipboard. │ +│ [default: clipboard] │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, │ +│ including variables taken from the │ +│ configuration file. │ +│ --transcription-log PATH Path to log transcription results │ +│ with timestamps, hostname, model, and │ +│ raw output. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -707,9 +687,8 @@ uv tool install "agent-cli[vad]" Run a continuous transcription daemon with voice activity detection. - This command runs indefinitely, capturing audio from your microphone, - detecting speech segments using Silero VAD, transcribing them, and logging - results with timestamps. + This command runs indefinitely, capturing audio from your microphone, detecting speech + segments using Silero VAD, transcribing them, and logging results with timestamps. Examples: # Basic daemon agent-cli transcribe-daemon @@ -721,115 +700,101 @@ uv tool install "agent-cli[vad]" agent-cli transcribe-daemon --llm --role notes # Custom log file and audio directory - agent-cli transcribe-daemon --transcription-log ~/meeting.jsonl --audio-dir - ~/audio - - -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --role -r TEXT Role name for logging │ -│ (e.g., 'meeting', │ -│ 'notes', 'user'). │ -│ [default: user] │ -│ --silence-threshold -s FLOAT Seconds of silence to end │ -│ a speech segment. │ -│ [default: 1.0] │ -│ --min-segment -m FLOAT Minimum speech duration │ -│ in seconds to trigger a │ -│ segment. │ -│ [default: 0.25] │ -│ --vad-threshold FLOAT VAD speech detection │ -│ threshold (0.0-1.0). │ -│ Higher = more aggressive │ -│ filtering. │ -│ [default: 0.3] │ -│ --save-audio --no-save-audio Save audio segments as │ -│ MP3 files. │ -│ [default: save-audio] │ -│ --audio-dir PATH Directory for MP3 files. │ -│ Default: │ -│ ~/.config/agent-cli/audio │ -│ --transcription-log -t PATH JSON Lines log file path. │ -│ Default: │ -│ ~/.config/agent-cli/tran… │ -│ --clipboard --no-clipboard Copy each transcription │ -│ to clipboard. │ -│ [default: no-clipboard] │ -│ --help -h Show this message and │ -│ exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ─────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ -│ 'gemini'). │ -│ [default: ollama] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial │ -│ matching. │ -│ --list-devices List available audio input and output │ -│ devices and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR │ -│ (transcription). │ -│ [default: whisper-1] │ -│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR │ -│ API (e.g., for custom Whisper server: │ -│ http://localhost:9898). │ -│ --asr-openai-prompt TEXT Custom prompt to guide transcription │ -│ (optional). │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is │ -│ gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ -│ the OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ -│ (e.g., for llama-server: │ -│ http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ -│ the GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ -│ --llm --no-llm Use an LLM to process the transcript. │ -│ [default: no-llm] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ─────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including │ -│ variables taken from the configuration file. │ -╰──────────────────────────────────────────────────────────────────────────────╯ + agent-cli transcribe-daemon --transcription-log ~/meeting.jsonl --audio-dir ~/audio + + +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --role -r TEXT Role name for logging (e.g., │ +│ 'meeting', 'notes', 'user'). │ +│ [default: user] │ +│ --silence-threshold -s FLOAT Seconds of silence to end a speech │ +│ segment. │ +│ [default: 1.0] │ +│ --min-segment -m FLOAT Minimum speech duration in seconds │ +│ to trigger a segment. │ +│ [default: 0.25] │ +│ --vad-threshold FLOAT VAD speech detection threshold │ +│ (0.0-1.0). Higher = more aggressive │ +│ filtering. │ +│ [default: 0.3] │ +│ --save-audio --no-save-audio Save audio segments as MP3 files. │ +│ [default: save-audio] │ +│ --audio-dir PATH Directory for MP3 files. Default: │ +│ ~/.config/agent-cli/audio │ +│ --transcription-log -t PATH JSON Lines log file path. Default: │ +│ ~/.config/agent-cli/transcriptions… │ +│ --clipboard --no-clipboard Copy each transcription to │ +│ clipboard. │ +│ [default: no-clipboard] │ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ +│ [default: ollama] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial matching. │ +│ --list-devices List available audio input and output devices and │ +│ exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ +│ [default: whisper-1] │ +│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR API │ +│ (e.g., for custom Whisper server: │ +│ http://localhost:9898). │ +│ --asr-openai-prompt TEXT Custom prompt to guide transcription (optional). │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ +│ llama-server: http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ +│ GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮ +│ --llm --no-llm Use an LLM to process the transcript. │ +│ [default: no-llm] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ───────────────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including variables │ +│ taken from the configuration file. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -873,76 +838,69 @@ uv tool install "agent-cli[vad]" Convert text to speech using Wyoming or OpenAI TTS server. -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ text [TEXT] Text to speak. Reads from clipboard if not provided. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ─────────────────────────────────────────────────────────╮ -│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', │ -│ 'kokoro'). │ -│ [default: wyoming] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output ───────────────────────────────────────────────────────────────╮ -│ --output-device-index INTEGER Index of the audio output device to │ -│ use for TTS. │ -│ --output-device-name TEXT Output device name keywords for │ -│ partial matching. │ -│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, │ -│ 2.0 = twice as fast, 0.5 = half │ -│ speed). │ -│ [default: 1.0] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ -│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ -│ [default: localhost] │ -│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ -│ [default: 10200] │ -│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS │ -│ (e.g., 'en_US-lessac-medium'). │ -│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., │ -│ 'en_US'). │ -│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: OpenAI ───────────────────────────────────────────────────────╮ -│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ -│ [default: tts-1] │ -│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ -│ [default: alloy] │ -│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS │ -│ API (e.g., http://localhost:8000/v1 for a │ -│ proxy). │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ -│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ -│ [default: kokoro] │ -│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ -│ [default: af_sky] │ -│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ -│ [default: http://localhost:8880/v1] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ────────────────────────────────────────────────────────────────╮ -│ --list-devices List available audio input and output devices and │ -│ exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --save-file PATH Save TTS response audio to WAV file. │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including │ -│ variables taken from the configuration file. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ─────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ text [TEXT] Text to speak. Reads from clipboard if not provided. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ +│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', 'kokoro'). │ +│ [default: wyoming] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮ +│ --output-device-index INTEGER Index of the audio output device to use for TTS. │ +│ --output-device-name TEXT Output device name keywords for partial │ +│ matching. │ +│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, 2.0 = │ +│ twice as fast, 0.5 = half speed). │ +│ [default: 1.0] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Wyoming ────────────────────────────────────────────────────────────────╮ +│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ +│ [default: localhost] │ +│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ +│ [default: 10200] │ +│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS (e.g., │ +│ 'en_US-lessac-medium'). │ +│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., 'en_US'). │ +│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮ +│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ +│ [default: tts-1] │ +│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ +│ [default: alloy] │ +│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS API │ +│ (e.g., http://localhost:8000/v1 for a proxy). │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Kokoro ─────────────────────────────────────────────────────────────────╮ +│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ +│ [default: kokoro] │ +│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ +│ [default: af_sky] │ +│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ +│ [default: http://localhost:8880/v1] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ +│ --list-devices List available audio input and output devices and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --save-file PATH Save TTS response audio to WAV file. │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including variables │ +│ taken from the configuration file. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ───────────────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -983,8 +941,7 @@ uv tool install "agent-cli[vad]" Usage: agent-cli voice-edit [OPTIONS] - Interact with clipboard text via a voice command using local or remote - services. + Interact with clipboard text via a voice command using local or remote services. Usage: @@ -995,125 +952,112 @@ uv tool install "agent-cli[vad]" • List output devices: agent-cli voice-edit --list-output-devices • Save TTS to file: agent-cli voice-edit --tts --save-file response.wav -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ─────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ -│ 'gemini'). │ -│ [default: ollama] │ -│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', │ -│ 'kokoro'). │ -│ [default: wyoming] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial │ -│ matching. │ -│ --list-devices List available audio input and output │ -│ devices and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR │ -│ (transcription). │ -│ [default: whisper-1] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is │ -│ gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ -│ the OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ -│ (e.g., for llama-server: │ -│ http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ -│ the GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output ───────────────────────────────────────────────────────────────╮ -│ --tts --no-tts Enable text-to-speech for │ -│ responses. │ -│ [default: no-tts] │ -│ --output-device-index INTEGER Index of the audio output │ -│ device to use for TTS. │ -│ --output-device-name TEXT Output device name keywords │ -│ for partial matching. │ -│ --tts-speed FLOAT Speech speed multiplier (1.0 = │ -│ normal, 2.0 = twice as fast, │ -│ 0.5 = half speed). │ -│ [default: 1.0] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ -│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ -│ [default: localhost] │ -│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ -│ [default: 10200] │ -│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS │ -│ (e.g., 'en_US-lessac-medium'). │ -│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., │ -│ 'en_US'). │ -│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: OpenAI ───────────────────────────────────────────────────────╮ -│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ -│ [default: tts-1] │ -│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ -│ [default: alloy] │ -│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS │ -│ API (e.g., http://localhost:8000/v1 for a │ -│ proxy). │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ -│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ -│ [default: kokoro] │ -│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ -│ [default: af_sky] │ -│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ -│ [default: http://localhost:8880/v1] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ─────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --save-file PATH Save TTS response audio to WAV │ -│ file. │ -│ --clipboard --no-clipboard Copy result to clipboard. │ -│ [default: clipboard] │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, │ -│ including variables taken from the │ -│ configuration file. │ -╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ +│ [default: ollama] │ +│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', 'kokoro'). │ +│ [default: wyoming] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial matching. │ +│ --list-devices List available audio input and output devices and │ +│ exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ +│ [default: whisper-1] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ +│ llama-server: http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ +│ GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮ +│ --tts --no-tts Enable text-to-speech for responses. │ +│ [default: no-tts] │ +│ --output-device-index INTEGER Index of the audio output device to use │ +│ for TTS. │ +│ --output-device-name TEXT Output device name keywords for partial │ +│ matching. │ +│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, │ +│ 2.0 = twice as fast, 0.5 = half speed). │ +│ [default: 1.0] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Wyoming ────────────────────────────────────────────────────────────────╮ +│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ +│ [default: localhost] │ +│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ +│ [default: 10200] │ +│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS (e.g., │ +│ 'en_US-lessac-medium'). │ +│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., 'en_US'). │ +│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮ +│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ +│ [default: tts-1] │ +│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ +│ [default: alloy] │ +│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS API │ +│ (e.g., http://localhost:8000/v1 for a proxy). │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Kokoro ─────────────────────────────────────────────────────────────────╮ +│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ +│ [default: kokoro] │ +│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ +│ [default: af_sky] │ +│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ +│ [default: http://localhost:8880/v1] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ───────────────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --save-file PATH Save TTS response audio to WAV file. │ +│ --clipboard --no-clipboard Copy result to clipboard. │ +│ [default: clipboard] │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including │ +│ variables taken from the configuration file. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1159,134 +1103,121 @@ uv tool install "agent-cli[vad]" Wake word-based voice assistant using local or remote services. -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ─────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ -│ 'gemini'). │ -│ [default: ollama] │ -│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', │ -│ 'kokoro'). │ -│ [default: wyoming] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Wake Word ──────────────────────────────────────────────────────────────────╮ -│ --wake-server-ip TEXT Wyoming wake word server IP address. │ -│ [default: localhost] │ -│ --wake-server-port INTEGER Wyoming wake word server port. │ -│ [default: 10400] │ -│ --wake-word TEXT Name of wake word to detect (e.g., │ -│ 'ok_nabu', 'hey_jarvis'). │ -│ [default: ok_nabu] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial │ -│ matching. │ -│ --list-devices List available audio input and output │ -│ devices and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR │ -│ (transcription). │ -│ [default: whisper-1] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is │ -│ gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ -│ the OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ -│ (e.g., for llama-server: │ -│ http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ -│ the GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output ───────────────────────────────────────────────────────────────╮ -│ --tts --no-tts Enable text-to-speech for │ -│ responses. │ -│ [default: no-tts] │ -│ --output-device-index INTEGER Index of the audio output │ -│ device to use for TTS. │ -│ --output-device-name TEXT Output device name keywords │ -│ for partial matching. │ -│ --tts-speed FLOAT Speech speed multiplier (1.0 = │ -│ normal, 2.0 = twice as fast, │ -│ 0.5 = half speed). │ -│ [default: 1.0] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ -│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ -│ [default: localhost] │ -│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ -│ [default: 10200] │ -│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS │ -│ (e.g., 'en_US-lessac-medium'). │ -│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., │ -│ 'en_US'). │ -│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: OpenAI ───────────────────────────────────────────────────────╮ -│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ -│ [default: tts-1] │ -│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ -│ [default: alloy] │ -│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS │ -│ API (e.g., http://localhost:8000/v1 for a │ -│ proxy). │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ -│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ -│ [default: kokoro] │ -│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ -│ [default: af_sky] │ -│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ -│ [default: http://localhost:8880/v1] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ─────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --save-file PATH Save TTS response audio to WAV │ -│ file. │ -│ --clipboard --no-clipboard Copy result to clipboard. │ -│ [default: clipboard] │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, │ -│ including variables taken from the │ -│ configuration file. │ -╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ +│ [default: ollama] │ +│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', 'kokoro'). │ +│ [default: wyoming] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Wake Word ────────────────────────────────────────────────────────────────────────────╮ +│ --wake-server-ip TEXT Wyoming wake word server IP address. │ +│ [default: localhost] │ +│ --wake-server-port INTEGER Wyoming wake word server port. │ +│ [default: 10400] │ +│ --wake-word TEXT Name of wake word to detect (e.g., 'ok_nabu', │ +│ 'hey_jarvis'). │ +│ [default: ok_nabu] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial matching. │ +│ --list-devices List available audio input and output devices and │ +│ exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ +│ [default: whisper-1] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ +│ llama-server: http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ +│ GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮ +│ --tts --no-tts Enable text-to-speech for responses. │ +│ [default: no-tts] │ +│ --output-device-index INTEGER Index of the audio output device to use │ +│ for TTS. │ +│ --output-device-name TEXT Output device name keywords for partial │ +│ matching. │ +│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, │ +│ 2.0 = twice as fast, 0.5 = half speed). │ +│ [default: 1.0] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Wyoming ────────────────────────────────────────────────────────────────╮ +│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ +│ [default: localhost] │ +│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ +│ [default: 10200] │ +│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS (e.g., │ +│ 'en_US-lessac-medium'). │ +│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., 'en_US'). │ +│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮ +│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ +│ [default: tts-1] │ +│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ +│ [default: alloy] │ +│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS API │ +│ (e.g., http://localhost:8000/v1 for a proxy). │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Kokoro ─────────────────────────────────────────────────────────────────╮ +│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ +│ [default: kokoro] │ +│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ +│ [default: af_sky] │ +│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ +│ [default: http://localhost:8880/v1] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ───────────────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --save-file PATH Save TTS response audio to WAV file. │ +│ --clipboard --no-clipboard Copy result to clipboard. │ +│ [default: clipboard] │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including │ +│ variables taken from the configuration file. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1339,134 +1270,121 @@ uv tool install "agent-cli[vad]" An chat agent that you can talk to. -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ─────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ -│ 'gemini'). │ -│ [default: ollama] │ -│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', │ -│ 'kokoro'). │ -│ [default: wyoming] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial │ -│ matching. │ -│ --list-devices List available audio input and output │ -│ devices and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI ────────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR │ -│ (transcription). │ -│ [default: whisper-1] │ -│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR │ -│ API (e.g., for custom Whisper server: │ -│ http://localhost:9898). │ -│ --asr-openai-prompt TEXT Custom prompt to guide transcription │ -│ (optional). │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is │ -│ gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ -│ the OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ -│ (e.g., for llama-server: │ -│ http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ -│ the GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output ───────────────────────────────────────────────────────────────╮ -│ --tts --no-tts Enable text-to-speech for │ -│ responses. │ -│ [default: no-tts] │ -│ --output-device-index INTEGER Index of the audio output │ -│ device to use for TTS. │ -│ --output-device-name TEXT Output device name keywords │ -│ for partial matching. │ -│ --tts-speed FLOAT Speech speed multiplier (1.0 = │ -│ normal, 2.0 = twice as fast, │ -│ 0.5 = half speed). │ -│ [default: 1.0] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ -│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ -│ [default: localhost] │ -│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ -│ [default: 10200] │ -│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS │ -│ (e.g., 'en_US-lessac-medium'). │ -│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., │ -│ 'en_US'). │ -│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: OpenAI ───────────────────────────────────────────────────────╮ -│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ -│ [default: tts-1] │ -│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ -│ [default: alloy] │ -│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS │ -│ API (e.g., http://localhost:8000/v1 for a │ -│ proxy). │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ -│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ -│ [default: kokoro] │ -│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ -│ [default: af_sky] │ -│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ -│ [default: http://localhost:8880/v1] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ─────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ History Options ────────────────────────────────────────────────────────────╮ -│ --history-dir PATH Directory to store conversation history. │ -│ [default: ~/.config/agent-cli/history] │ -│ --last-n-messages INTEGER Number of messages to include in the │ -│ conversation history. Set to 0 to disable │ -│ history. │ -│ [default: 50] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --save-file PATH Save TTS response audio to WAV file. │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including │ -│ variables taken from the configuration file. │ -╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ +│ [default: ollama] │ +│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', 'kokoro'). │ +│ [default: wyoming] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial matching. │ +│ --list-devices List available audio input and output devices and │ +│ exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ +│ [default: whisper-1] │ +│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR API │ +│ (e.g., for custom Whisper server: │ +│ http://localhost:9898). │ +│ --asr-openai-prompt TEXT Custom prompt to guide transcription (optional). │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ +│ llama-server: http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ +│ GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮ +│ --tts --no-tts Enable text-to-speech for responses. │ +│ [default: no-tts] │ +│ --output-device-index INTEGER Index of the audio output device to use │ +│ for TTS. │ +│ --output-device-name TEXT Output device name keywords for partial │ +│ matching. │ +│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, │ +│ 2.0 = twice as fast, 0.5 = half speed). │ +│ [default: 1.0] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Wyoming ────────────────────────────────────────────────────────────────╮ +│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ +│ [default: localhost] │ +│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ +│ [default: 10200] │ +│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS (e.g., │ +│ 'en_US-lessac-medium'). │ +│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., 'en_US'). │ +│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮ +│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ +│ [default: tts-1] │ +│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ +│ [default: alloy] │ +│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS API │ +│ (e.g., http://localhost:8000/v1 for a proxy). │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Kokoro ─────────────────────────────────────────────────────────────────╮ +│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ +│ [default: kokoro] │ +│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ +│ [default: af_sky] │ +│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ +│ [default: http://localhost:8880/v1] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ───────────────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ History Options ──────────────────────────────────────────────────────────────────────╮ +│ --history-dir PATH Directory to store conversation history. │ +│ [default: ~/.config/agent-cli/history] │ +│ --last-n-messages INTEGER Number of messages to include in the conversation │ +│ history. Set to 0 to disable history. │ +│ [default: 50] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --save-file PATH Save TTS response audio to WAV file. │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including variables │ +│ taken from the configuration file. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1513,52 +1431,49 @@ uv tool install "agent-cli[vad]" Start the RAG (Retrieval-Augmented Generation) Proxy Server. This server watches a folder for documents, indexes them, and provides an - OpenAI-compatible API that proxies requests to a backend LLM (like llama.cpp), - injecting relevant context from the documents. - -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ RAG Configuration ──────────────────────────────────────────────────────────╮ -│ --docs-folder PATH Folder to watch for documents │ -│ [default: ./rag_docs] │ -│ --chroma-path PATH Path to ChromaDB persistence │ -│ directory │ -│ [default: ./rag_db] │ -│ --limit INTEGER Number of document chunks to │ -│ retrieve per query. │ -│ [default: 3] │ -│ --rag-tools --no-rag-tools Allow agent to fetch full │ -│ documents when snippets are │ -│ insufficient. │ -│ [default: rag-tools] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ -│ (e.g., for llama-server: │ -│ http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ -│ --embedding-model TEXT Embedding model to use for vectorization. │ -│ [default: text-embedding-3-small] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Server Configuration ───────────────────────────────────────────────────────╮ -│ --host TEXT Host/IP to bind API servers to. │ -│ [default: 0.0.0.0] │ -│ --port INTEGER Port to bind to │ -│ [default: 8000] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --log-level TEXT Set logging level. │ -│ [default: INFO] │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including │ -│ variables taken from the configuration file. │ -╰──────────────────────────────────────────────────────────────────────────────╯ + OpenAI-compatible API that proxies requests to a backend LLM (like llama.cpp), injecting + relevant context from the documents. + +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ RAG Configuration ────────────────────────────────────────────────────────────────────╮ +│ --docs-folder PATH Folder to watch for documents │ +│ [default: ./rag_docs] │ +│ --chroma-path PATH Path to ChromaDB persistence directory │ +│ [default: ./rag_db] │ +│ --limit INTEGER Number of document chunks to retrieve per │ +│ query. │ +│ [default: 3] │ +│ --rag-tools --no-rag-tools Allow agent to fetch full documents when │ +│ snippets are insufficient. │ +│ [default: rag-tools] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ +│ llama-server: http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮ +│ --embedding-model TEXT Embedding model to use for vectorization. │ +│ [default: text-embedding-3-small] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Server Configuration ─────────────────────────────────────────────────────────────────╮ +│ --host TEXT Host/IP to bind API servers to. │ +│ [default: 0.0.0.0] │ +│ --port INTEGER Port to bind to │ +│ [default: 8000] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --log-level TEXT Set logging level. │ +│ [default: INFO] │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including variables taken │ +│ from the configuration file. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1612,107 +1527,91 @@ The `memory proxy` command is the core feature—a middleware server that gives Start the memory-backed chat proxy server. - This server acts as a middleware between your chat client (e.g., a web UI, - CLI, or IDE plugin) and an OpenAI-compatible LLM provider (e.g., OpenAI, - Ollama, vLLM). + This server acts as a middleware between your chat client (e.g., a web UI, CLI, or IDE + plugin) and an OpenAI-compatible LLM provider (e.g., OpenAI, Ollama, vLLM). Key Features: - • Simple Markdown Files: Memories are stored as human-readable Markdown - files, serving as the ultimate source of truth. - • Automatic Version Control: Built-in Git integration automatically commits - changes, providing a full history of memory evolution. - • Lightweight & Local: Minimal dependencies and runs entirely on your - machine. - • Proxy Middleware: Works transparently with any OpenAI-compatible - /chat/completions endpoint. + • Simple Markdown Files: Memories are stored as human-readable Markdown files, serving + as the ultimate source of truth. + • Automatic Version Control: Built-in Git integration automatically commits changes, + providing a full history of memory evolution. + • Lightweight & Local: Minimal dependencies and runs entirely on your machine. + • Proxy Middleware: Works transparently with any OpenAI-compatible /chat/completions + endpoint. How it works: 1 Intercepts POST /v1/chat/completions requests. - 2 Retrieves relevant memories (facts, previous conversations) from a local - vector database (ChromaDB) based on the user's query. + 2 Retrieves relevant memories (facts, previous conversations) from a local vector + database (ChromaDB) based on the user's query. 3 Injects these memories into the system prompt. 4 Forwards the augmented request to the real LLM (--openai-base-url). - 5 Extracts new facts from the conversation in the background and updates the - long-term memory store (including handling contradictions). - - Use this to give "long-term memory" to any OpenAI-compatible application. - Point your client's base URL to http://localhost:8100/v1. - -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Memory Configuration ───────────────────────────────────────────────────────╮ -│ --memory-path PATH Path to the memory │ -│ store (files + derived │ -│ vector index). │ -│ [default: ./memory_db] │ -│ --default-top-k INTEGER Number of memory │ -│ entries to retrieve per │ -│ query. │ -│ [default: 5] │ -│ --max-entries INTEGER Maximum stored memory │ -│ entries per │ -│ conversation (excluding │ -│ summary). │ -│ [default: 500] │ -│ --mmr-lambda FLOAT MMR lambda (0-1): │ -│ higher favors │ -│ relevance, lower favors │ -│ diversity. │ -│ [default: 0.7] │ -│ --recency-weight FLOAT Recency score weight │ -│ (0.0-1.0). Controls │ -│ freshness vs. │ -│ relevance. Default 0.2 │ -│ (20% recency, 80% │ -│ semantic relevance). │ -│ [default: 0.2] │ -│ --score-threshold FLOAT Minimum semantic │ -│ relevance threshold │ -│ (0.0-1.0). Memories │ -│ below this score are │ -│ discarded to reduce │ -│ noise. │ -│ [default: 0.35] │ -│ --summarization --no-summarization Enable automatic fact │ -│ extraction and │ -│ summaries. │ -│ [default: │ -│ summarization] │ -│ --git-versioning --no-git-versioning Enable automatic git │ -│ commit of memory │ -│ changes. │ -│ [default: │ -│ git-versioning] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI ────────────────────────────────────────────────────────────────╮ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ -│ (e.g., for llama-server: │ -│ http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ -│ --embedding-model TEXT Embedding model to use for vectorization. │ -│ [default: text-embedding-3-small] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Server Configuration ───────────────────────────────────────────────────────╮ -│ --host TEXT Host/IP to bind API servers to. │ -│ [default: 0.0.0.0] │ -│ --port INTEGER Port to bind to │ -│ [default: 8100] │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --log-level TEXT Set logging level. │ -│ [default: INFO] │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including │ -│ variables taken from the configuration file. │ -╰──────────────────────────────────────────────────────────────────────────────╯ + 5 Extracts new facts from the conversation in the background and updates the long-term + memory store (including handling contradictions). + + Use this to give "long-term memory" to any OpenAI-compatible application. Point your + client's base URL to http://localhost:8100/v1. + +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Memory Configuration ─────────────────────────────────────────────────────────────────╮ +│ --memory-path PATH Path to the memory store (files + │ +│ derived vector index). │ +│ [default: ./memory_db] │ +│ --default-top-k INTEGER Number of memory entries to │ +│ retrieve per query. │ +│ [default: 5] │ +│ --max-entries INTEGER Maximum stored memory entries per │ +│ conversation (excluding summary). │ +│ [default: 500] │ +│ --mmr-lambda FLOAT MMR lambda (0-1): higher favors │ +│ relevance, lower favors │ +│ diversity. │ +│ [default: 0.7] │ +│ --recency-weight FLOAT Recency score weight (0.0-1.0). │ +│ Controls freshness vs. relevance. │ +│ Default 0.2 (20% recency, 80% │ +│ semantic relevance). │ +│ [default: 0.2] │ +│ --score-threshold FLOAT Minimum semantic relevance │ +│ threshold (0.0-1.0). Memories │ +│ below this score are discarded to │ +│ reduce noise. │ +│ [default: 0.35] │ +│ --summarization --no-summarization Enable automatic fact extraction │ +│ and summaries. │ +│ [default: summarization] │ +│ --git-versioning --no-git-versioning Enable automatic git commit of │ +│ memory changes. │ +│ [default: git-versioning] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ +│ llama-server: http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮ +│ --embedding-model TEXT Embedding model to use for vectorization. │ +│ [default: text-embedding-3-small] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Server Configuration ─────────────────────────────────────────────────────────────────╮ +│ --host TEXT Host/IP to bind API servers to. │ +│ [default: 0.0.0.0] │ +│ --port INTEGER Port to bind to │ +│ [default: 8100] │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --log-level TEXT Set logging level. │ +│ [default: INFO] │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including variables taken │ +│ from the configuration file. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1763,11 +1662,11 @@ agent-cli memory add -c work "Project deadline is Friday" Add memories directly without LLM extraction. - This writes facts directly to the memory store, bypassing the LLM-based fact - extraction. Useful for bulk imports or seeding memories. + This writes facts directly to the memory store, bypassing the LLM-based fact extraction. + Useful for bulk imports or seeding memories. - The memory proxy file watcher (if running) will auto-index new files. - Otherwise, they'll be indexed on next memory proxy startup. + The memory proxy file watcher (if running) will auto-index new files. Otherwise, they'll + be indexed on next memory proxy startup. Examples:: @@ -1788,35 +1687,29 @@ agent-cli memory add -c work "Project deadline is Friday" agent-cli memory add -c work "Project deadline is Friday" -╭─ Arguments ──────────────────────────────────────────────────────────────────╮ -│ memories [MEMORIES]... Memories to add. Each argument becomes one │ -│ fact. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ────────────────────────────────────────────────────────────────────╮ -│ --file -f PATH Read memories from file. │ -│ Use '-' for stdin. │ -│ Supports JSON array, │ -│ JSON object with │ -│ 'memories' key, or plain │ -│ text (one per line). │ -│ --conversation-id -c TEXT Conversation ID to add │ -│ memories to. │ -│ [default: default] │ -│ --memory-path PATH Path to the memory │ -│ store. │ -│ [default: ./memory_db] │ -│ --git-versioning --no-git-versioning Commit changes to git. │ -│ [default: │ -│ git-versioning] │ -│ --help -h Show this message and │ -│ exit. │ -╰──────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ────────────────────────────────────────────────────────────╮ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including │ -│ variables taken from the configuration file. │ -╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ +│ memories [MEMORIES]... Memories to add. Each argument becomes one fact. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ +│ --file -f PATH Read memories from file. Use '-' │ +│ for stdin. Supports JSON array, │ +│ JSON object with 'memories' key, │ +│ or plain text (one per line). │ +│ --conversation-id -c TEXT Conversation ID to add memories │ +│ to. │ +│ [default: default] │ +│ --memory-path PATH Path to the memory store. │ +│ [default: ./memory_db] │ +│ --git-versioning --no-git-versioning Commit changes to git. │ +│ [default: git-versioning] │ +│ --help -h Show this message and exit. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ──────────────────────────────────────────────────────────────────────╮ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including variables │ +│ taken from the configuration file. │ +╰────────────────────────────────────────────────────────────────────────────────────────╯ ``` diff --git a/docs/update_docs.py b/docs/update_docs.py index a8f014627..b29772a53 100755 --- a/docs/update_docs.py +++ b/docs/update_docs.py @@ -16,11 +16,12 @@ def find_markdown_files_with_code_blocks(docs_dir: Path) -> list[Path]: - """Find all markdown files containing CODE:START markers.""" + """Find all markdown files containing markdown-code-runner markers.""" files_with_code = [] for md_file in docs_dir.rglob("*.md"): content = md_file.read_text() - if "" in content: + # Match both CODE:START and CODE:BASH:START patterns + if "" in content or "" in content: files_with_code.append(md_file) return sorted(files_with_code) From fc8124ff4a65305519a63afa57750c055e4271a4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 3 Jan 2026 09:15:58 +0000 Subject: [PATCH 24/24] Update auto-generated docs --- README.md | 1679 ++++++++++++++++++++++++++++------------------------- 1 file changed, 893 insertions(+), 786 deletions(-) diff --git a/README.md b/README.md index c2860caa8..e3bd6c11b 100644 --- a/README.md +++ b/README.md @@ -387,14 +387,14 @@ agent-cli config edit Manage agent-cli configuration files. -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮ -│ init Create a new config file with all options commented out. │ -│ edit Open the config file in your default editor. │ -│ show Display the config file location and contents. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Commands ───────────────────────────────────────────────────────────────────╮ +│ init Create a new config file with all options commented out. │ +│ edit Open the config file in your default editor. │ +│ show Display the config file location and contents. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -453,49 +453,53 @@ the `[defaults]` section of your configuration file. Correct text from clipboard using a local or remote LLM. -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ text [TEXT] The text to correct. If not provided, reads from clipboard. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ -│ [default: ollama] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ -│ llama-server: http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ -│ GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including variables │ -│ taken from the configuration file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ text [TEXT] The text to correct. If not provided, reads from │ +│ clipboard. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ─────────────────────────────────────────────────────────╮ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ +│ 'gemini'). │ +│ [default: ollama] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is │ +│ gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ +│ the OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ +│ (e.g., for llama-server: │ +│ http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ +│ the GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including │ +│ variables taken from the configuration file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -540,98 +544,114 @@ the `[defaults]` section of your configuration file. Wyoming ASR Client for streaming microphone audio to a transcription server. -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮ -│ --extra-instructions TEXT Additional instructions for the LLM to │ -│ process the transcription. │ -│ --llm --no-llm Use an LLM to process the transcript. │ -│ [default: no-llm] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Recovery ───────────────────────────────────────────────────────────────────────╮ -│ --from-file PATH Transcribe audio from a saved WAV │ -│ file instead of recording. │ -│ --last-recording INTEGER Transcribe a saved recording. Use │ -│ 1 for most recent, 2 for │ -│ second-to-last, etc. Use 0 to │ -│ disable (default). │ -│ [default: 0] │ -│ --save-recording --no-save-recording Save the audio recording to disk │ -│ for recovery. │ -│ [default: save-recording] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ -│ [default: ollama] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial matching. │ -│ --list-devices List available audio input and output devices and │ -│ exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ -│ [default: whisper-1] │ -│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR API │ -│ (e.g., for custom Whisper server: │ -│ http://localhost:9898). │ -│ --asr-openai-prompt TEXT Custom prompt to guide transcription (optional). │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ -│ llama-server: http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ -│ GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ───────────────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --clipboard --no-clipboard Copy result to clipboard. │ -│ [default: clipboard] │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, │ -│ including variables taken from the │ -│ configuration file. │ -│ --transcription-log PATH Path to log transcription results │ -│ with timestamps, hostname, model, and │ -│ raw output. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ +│ --extra-instructions TEXT Additional instructions for the │ +│ LLM to process the transcription. │ +│ --llm --no-llm Use an LLM to process the │ +│ transcript. │ +│ [default: no-llm] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Recovery ─────────────────────────────────────────────────────────────╮ +│ --from-file PATH Transcribe audio from a │ +│ saved WAV file instead │ +│ of recording. │ +│ --last-recording INTEGER Transcribe a saved │ +│ recording. Use 1 for │ +│ most recent, 2 for │ +│ second-to-last, etc. Use │ +│ 0 to disable (default). │ +│ [default: 0] │ +│ --save-recording --no-save-recording Save the audio recording │ +│ to disk for recovery. │ +│ [default: │ +│ save-recording] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ─────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ +│ 'gemini'). │ +│ [default: ollama] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial │ +│ matching. │ +│ --list-devices List available audio input and output │ +│ devices and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR │ +│ (transcription). │ +│ [default: whisper-1] │ +│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR │ +│ API (e.g., for custom Whisper server: │ +│ http://localhost:9898). │ +│ --asr-openai-prompt TEXT Custom prompt to guide transcription │ +│ (optional). │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is │ +│ gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ +│ the OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ +│ (e.g., for llama-server: │ +│ http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ +│ the GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ─────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --clipboard --no-clipboard Copy result to clipboard. │ +│ [default: clipboard] │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write │ +│ logs to. │ +│ --quiet -q Suppress console output │ +│ from rich. │ +│ --config TEXT Path to a TOML │ +│ configuration file. │ +│ --print-args Print the command line │ +│ arguments, including │ +│ variables taken from the │ +│ configuration file. │ +│ --transcription-log PATH Path to log transcription │ +│ results with timestamps, │ +│ hostname, model, and raw │ +│ output. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -687,8 +707,9 @@ uv tool install "agent-cli[vad]" Run a continuous transcription daemon with voice activity detection. - This command runs indefinitely, capturing audio from your microphone, detecting speech - segments using Silero VAD, transcribing them, and logging results with timestamps. + This command runs indefinitely, capturing audio from your microphone, + detecting speech segments using Silero VAD, transcribing them, and logging + results with timestamps. Examples: # Basic daemon agent-cli transcribe-daemon @@ -700,101 +721,115 @@ uv tool install "agent-cli[vad]" agent-cli transcribe-daemon --llm --role notes # Custom log file and audio directory - agent-cli transcribe-daemon --transcription-log ~/meeting.jsonl --audio-dir ~/audio - - -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --role -r TEXT Role name for logging (e.g., │ -│ 'meeting', 'notes', 'user'). │ -│ [default: user] │ -│ --silence-threshold -s FLOAT Seconds of silence to end a speech │ -│ segment. │ -│ [default: 1.0] │ -│ --min-segment -m FLOAT Minimum speech duration in seconds │ -│ to trigger a segment. │ -│ [default: 0.25] │ -│ --vad-threshold FLOAT VAD speech detection threshold │ -│ (0.0-1.0). Higher = more aggressive │ -│ filtering. │ -│ [default: 0.3] │ -│ --save-audio --no-save-audio Save audio segments as MP3 files. │ -│ [default: save-audio] │ -│ --audio-dir PATH Directory for MP3 files. Default: │ -│ ~/.config/agent-cli/audio │ -│ --transcription-log -t PATH JSON Lines log file path. Default: │ -│ ~/.config/agent-cli/transcriptions… │ -│ --clipboard --no-clipboard Copy each transcription to │ -│ clipboard. │ -│ [default: no-clipboard] │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ -│ [default: ollama] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial matching. │ -│ --list-devices List available audio input and output devices and │ -│ exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ -│ [default: whisper-1] │ -│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR API │ -│ (e.g., for custom Whisper server: │ -│ http://localhost:9898). │ -│ --asr-openai-prompt TEXT Custom prompt to guide transcription (optional). │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ -│ llama-server: http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ -│ GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮ -│ --llm --no-llm Use an LLM to process the transcript. │ -│ [default: no-llm] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ───────────────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including variables │ -│ taken from the configuration file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ + agent-cli transcribe-daemon --transcription-log ~/meeting.jsonl --audio-dir + ~/audio + + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --role -r TEXT Role name for logging │ +│ (e.g., 'meeting', │ +│ 'notes', 'user'). │ +│ [default: user] │ +│ --silence-threshold -s FLOAT Seconds of silence to end │ +│ a speech segment. │ +│ [default: 1.0] │ +│ --min-segment -m FLOAT Minimum speech duration │ +│ in seconds to trigger a │ +│ segment. │ +│ [default: 0.25] │ +│ --vad-threshold FLOAT VAD speech detection │ +│ threshold (0.0-1.0). │ +│ Higher = more aggressive │ +│ filtering. │ +│ [default: 0.3] │ +│ --save-audio --no-save-audio Save audio segments as │ +│ MP3 files. │ +│ [default: save-audio] │ +│ --audio-dir PATH Directory for MP3 files. │ +│ Default: │ +│ ~/.config/agent-cli/audio │ +│ --transcription-log -t PATH JSON Lines log file path. │ +│ Default: │ +│ ~/.config/agent-cli/tran… │ +│ --clipboard --no-clipboard Copy each transcription │ +│ to clipboard. │ +│ [default: no-clipboard] │ +│ --help -h Show this message and │ +│ exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ─────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ +│ 'gemini'). │ +│ [default: ollama] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial │ +│ matching. │ +│ --list-devices List available audio input and output │ +│ devices and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR │ +│ (transcription). │ +│ [default: whisper-1] │ +│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR │ +│ API (e.g., for custom Whisper server: │ +│ http://localhost:9898). │ +│ --asr-openai-prompt TEXT Custom prompt to guide transcription │ +│ (optional). │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is │ +│ gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ +│ the OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ +│ (e.g., for llama-server: │ +│ http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ +│ the GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ +│ --llm --no-llm Use an LLM to process the transcript. │ +│ [default: no-llm] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ─────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including │ +│ variables taken from the configuration file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -838,69 +873,76 @@ uv tool install "agent-cli[vad]" Convert text to speech using Wyoming or OpenAI TTS server. -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ text [TEXT] Text to speak. Reads from clipboard if not provided. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ -│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', 'kokoro'). │ -│ [default: wyoming] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮ -│ --output-device-index INTEGER Index of the audio output device to use for TTS. │ -│ --output-device-name TEXT Output device name keywords for partial │ -│ matching. │ -│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, 2.0 = │ -│ twice as fast, 0.5 = half speed). │ -│ [default: 1.0] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Wyoming ────────────────────────────────────────────────────────────────╮ -│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ -│ [default: localhost] │ -│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ -│ [default: 10200] │ -│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS (e.g., │ -│ 'en_US-lessac-medium'). │ -│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., 'en_US'). │ -│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮ -│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ -│ [default: tts-1] │ -│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ -│ [default: alloy] │ -│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS API │ -│ (e.g., http://localhost:8000/v1 for a proxy). │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Kokoro ─────────────────────────────────────────────────────────────────╮ -│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ -│ [default: kokoro] │ -│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ -│ [default: af_sky] │ -│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ -│ [default: http://localhost:8880/v1] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ -│ --list-devices List available audio input and output devices and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --save-file PATH Save TTS response audio to WAV file. │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including variables │ -│ taken from the configuration file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ───────────────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ text [TEXT] Text to speak. Reads from clipboard if not provided. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ─────────────────────────────────────────────────────────╮ +│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', │ +│ 'kokoro'). │ +│ [default: wyoming] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ +│ --output-device-index INTEGER Index of the audio output device to │ +│ use for TTS. │ +│ --output-device-name TEXT Output device name keywords for │ +│ partial matching. │ +│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, │ +│ 2.0 = twice as fast, 0.5 = half │ +│ speed). │ +│ [default: 1.0] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ +│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ +│ [default: localhost] │ +│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ +│ [default: 10200] │ +│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS │ +│ (e.g., 'en_US-lessac-medium'). │ +│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., │ +│ 'en_US'). │ +│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: OpenAI-compatible ────────────────────────────────────────────╮ +│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ +│ [default: tts-1] │ +│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ +│ [default: alloy] │ +│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS │ +│ API (e.g., http://localhost:8000/v1 for a │ +│ proxy). │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ +│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ +│ [default: kokoro] │ +│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ +│ [default: af_sky] │ +│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ +│ [default: http://localhost:8880/v1] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ +│ --list-devices List available audio input and output devices and │ +│ exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --save-file PATH Save TTS response audio to WAV file. │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including │ +│ variables taken from the configuration file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ─────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -941,7 +983,8 @@ uv tool install "agent-cli[vad]" Usage: agent-cli voice-edit [OPTIONS] - Interact with clipboard text via a voice command using local or remote services. + Interact with clipboard text via a voice command using local or remote + services. Usage: @@ -952,112 +995,125 @@ uv tool install "agent-cli[vad]" • List output devices: agent-cli voice-edit --list-output-devices • Save TTS to file: agent-cli voice-edit --tts --save-file response.wav -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ -│ [default: ollama] │ -│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', 'kokoro'). │ -│ [default: wyoming] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial matching. │ -│ --list-devices List available audio input and output devices and │ -│ exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ -│ [default: whisper-1] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ -│ llama-server: http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ -│ GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮ -│ --tts --no-tts Enable text-to-speech for responses. │ -│ [default: no-tts] │ -│ --output-device-index INTEGER Index of the audio output device to use │ -│ for TTS. │ -│ --output-device-name TEXT Output device name keywords for partial │ -│ matching. │ -│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, │ -│ 2.0 = twice as fast, 0.5 = half speed). │ -│ [default: 1.0] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Wyoming ────────────────────────────────────────────────────────────────╮ -│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ -│ [default: localhost] │ -│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ -│ [default: 10200] │ -│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS (e.g., │ -│ 'en_US-lessac-medium'). │ -│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., 'en_US'). │ -│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮ -│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ -│ [default: tts-1] │ -│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ -│ [default: alloy] │ -│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS API │ -│ (e.g., http://localhost:8000/v1 for a proxy). │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Kokoro ─────────────────────────────────────────────────────────────────╮ -│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ -│ [default: kokoro] │ -│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ -│ [default: af_sky] │ -│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ -│ [default: http://localhost:8880/v1] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ───────────────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --save-file PATH Save TTS response audio to WAV file. │ -│ --clipboard --no-clipboard Copy result to clipboard. │ -│ [default: clipboard] │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including │ -│ variables taken from the configuration file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ─────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ +│ 'gemini'). │ +│ [default: ollama] │ +│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', │ +│ 'kokoro'). │ +│ [default: wyoming] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial │ +│ matching. │ +│ --list-devices List available audio input and output │ +│ devices and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR │ +│ (transcription). │ +│ [default: whisper-1] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is │ +│ gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ +│ the OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ +│ (e.g., for llama-server: │ +│ http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ +│ the GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ +│ --tts --no-tts Enable text-to-speech for │ +│ responses. │ +│ [default: no-tts] │ +│ --output-device-index INTEGER Index of the audio output │ +│ device to use for TTS. │ +│ --output-device-name TEXT Output device name keywords │ +│ for partial matching. │ +│ --tts-speed FLOAT Speech speed multiplier (1.0 = │ +│ normal, 2.0 = twice as fast, │ +│ 0.5 = half speed). │ +│ [default: 1.0] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ +│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ +│ [default: localhost] │ +│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ +│ [default: 10200] │ +│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS │ +│ (e.g., 'en_US-lessac-medium'). │ +│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., │ +│ 'en_US'). │ +│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: OpenAI-compatible ────────────────────────────────────────────╮ +│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ +│ [default: tts-1] │ +│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ +│ [default: alloy] │ +│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS │ +│ API (e.g., http://localhost:8000/v1 for a │ +│ proxy). │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ +│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ +│ [default: kokoro] │ +│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ +│ [default: af_sky] │ +│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ +│ [default: http://localhost:8880/v1] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ─────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --save-file PATH Save TTS response audio to WAV │ +│ file. │ +│ --clipboard --no-clipboard Copy result to clipboard. │ +│ [default: clipboard] │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, │ +│ including variables taken from the │ +│ configuration file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1103,121 +1159,134 @@ uv tool install "agent-cli[vad]" Wake word-based voice assistant using local or remote services. -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ -│ [default: ollama] │ -│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', 'kokoro'). │ -│ [default: wyoming] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Wake Word ────────────────────────────────────────────────────────────────────────────╮ -│ --wake-server-ip TEXT Wyoming wake word server IP address. │ -│ [default: localhost] │ -│ --wake-server-port INTEGER Wyoming wake word server port. │ -│ [default: 10400] │ -│ --wake-word TEXT Name of wake word to detect (e.g., 'ok_nabu', │ -│ 'hey_jarvis'). │ -│ [default: ok_nabu] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial matching. │ -│ --list-devices List available audio input and output devices and │ -│ exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ -│ [default: whisper-1] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ -│ llama-server: http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ -│ GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮ -│ --tts --no-tts Enable text-to-speech for responses. │ -│ [default: no-tts] │ -│ --output-device-index INTEGER Index of the audio output device to use │ -│ for TTS. │ -│ --output-device-name TEXT Output device name keywords for partial │ -│ matching. │ -│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, │ -│ 2.0 = twice as fast, 0.5 = half speed). │ -│ [default: 1.0] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Wyoming ────────────────────────────────────────────────────────────────╮ -│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ -│ [default: localhost] │ -│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ -│ [default: 10200] │ -│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS (e.g., │ -│ 'en_US-lessac-medium'). │ -│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., 'en_US'). │ -│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮ -│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ -│ [default: tts-1] │ -│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ -│ [default: alloy] │ -│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS API │ -│ (e.g., http://localhost:8000/v1 for a proxy). │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Kokoro ─────────────────────────────────────────────────────────────────╮ -│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ -│ [default: kokoro] │ -│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ -│ [default: af_sky] │ -│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ -│ [default: http://localhost:8880/v1] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ───────────────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --save-file PATH Save TTS response audio to WAV file. │ -│ --clipboard --no-clipboard Copy result to clipboard. │ -│ [default: clipboard] │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including │ -│ variables taken from the configuration file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ─────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ +│ 'gemini'). │ +│ [default: ollama] │ +│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', │ +│ 'kokoro'). │ +│ [default: wyoming] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Wake Word ──────────────────────────────────────────────────────────────────╮ +│ --wake-server-ip TEXT Wyoming wake word server IP address. │ +│ [default: localhost] │ +│ --wake-server-port INTEGER Wyoming wake word server port. │ +│ [default: 10400] │ +│ --wake-word TEXT Name of wake word to detect (e.g., │ +│ 'ok_nabu', 'hey_jarvis'). │ +│ [default: ok_nabu] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial │ +│ matching. │ +│ --list-devices List available audio input and output │ +│ devices and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR │ +│ (transcription). │ +│ [default: whisper-1] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is │ +│ gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ +│ the OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ +│ (e.g., for llama-server: │ +│ http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ +│ the GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ +│ --tts --no-tts Enable text-to-speech for │ +│ responses. │ +│ [default: no-tts] │ +│ --output-device-index INTEGER Index of the audio output │ +│ device to use for TTS. │ +│ --output-device-name TEXT Output device name keywords │ +│ for partial matching. │ +│ --tts-speed FLOAT Speech speed multiplier (1.0 = │ +│ normal, 2.0 = twice as fast, │ +│ 0.5 = half speed). │ +│ [default: 1.0] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ +│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ +│ [default: localhost] │ +│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ +│ [default: 10200] │ +│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS │ +│ (e.g., 'en_US-lessac-medium'). │ +│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., │ +│ 'en_US'). │ +│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: OpenAI-compatible ────────────────────────────────────────────╮ +│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ +│ [default: tts-1] │ +│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ +│ [default: alloy] │ +│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS │ +│ API (e.g., http://localhost:8000/v1 for a │ +│ proxy). │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ +│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ +│ [default: kokoro] │ +│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ +│ [default: af_sky] │ +│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ +│ [default: http://localhost:8880/v1] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ─────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --save-file PATH Save TTS response audio to WAV │ +│ file. │ +│ --clipboard --no-clipboard Copy result to clipboard. │ +│ [default: clipboard] │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, │ +│ including variables taken from the │ +│ configuration file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1270,121 +1339,134 @@ uv tool install "agent-cli[vad]" An chat agent that you can talk to. -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Provider Selection ───────────────────────────────────────────────────────────────────╮ -│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ -│ [default: wyoming] │ -│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', 'gemini'). │ -│ [default: ollama] │ -│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', 'kokoro'). │ -│ [default: wyoming] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input ──────────────────────────────────────────────────────────────────────────╮ -│ --input-device-index INTEGER Index of the audio input device to use. │ -│ --input-device-name TEXT Device name keywords for partial matching. │ -│ --list-devices List available audio input and output devices and │ -│ exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: Wyoming ─────────────────────────────────────────────────────────────────╮ -│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ -│ [default: localhost] │ -│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ -│ [default: 10300] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Input: OpenAI-compatible ───────────────────────────────────────────────────────╮ -│ --asr-openai-model TEXT The OpenAI model to use for ASR (transcription). │ -│ [default: whisper-1] │ -│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR API │ -│ (e.g., for custom Whisper server: │ -│ http://localhost:9898). │ -│ --asr-openai-prompt TEXT Custom prompt to guide transcription (optional). │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Ollama ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-ollama-model TEXT The Ollama model to use. Default is gemma3:4b. │ -│ [default: gemma3:4b] │ -│ --llm-ollama-host TEXT The Ollama server host. Default is │ -│ http://localhost:11434. │ -│ [default: http://localhost:11434] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ -│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ -│ [default: gpt-5-mini] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ -│ llama-server: http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: Gemini ──────────────────────────────────────────────────────────────────────────╮ -│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ -│ [default: gemini-2.5-flash] │ -│ --gemini-api-key TEXT Your Gemini API key. Can also be set with the │ -│ GEMINI_API_KEY environment variable. │ -│ [env var: GEMINI_API_KEY] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output ─────────────────────────────────────────────────────────────────────────╮ -│ --tts --no-tts Enable text-to-speech for responses. │ -│ [default: no-tts] │ -│ --output-device-index INTEGER Index of the audio output device to use │ -│ for TTS. │ -│ --output-device-name TEXT Output device name keywords for partial │ -│ matching. │ -│ --tts-speed FLOAT Speech speed multiplier (1.0 = normal, │ -│ 2.0 = twice as fast, 0.5 = half speed). │ -│ [default: 1.0] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Wyoming ────────────────────────────────────────────────────────────────╮ -│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ -│ [default: localhost] │ -│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ -│ [default: 10200] │ -│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS (e.g., │ -│ 'en_US-lessac-medium'). │ -│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., 'en_US'). │ -│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: OpenAI-compatible ──────────────────────────────────────────────────────╮ -│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ -│ [default: tts-1] │ -│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ -│ [default: alloy] │ -│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS API │ -│ (e.g., http://localhost:8000/v1 for a proxy). │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Audio Output: Kokoro ─────────────────────────────────────────────────────────────────╮ -│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ -│ [default: kokoro] │ -│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ -│ [default: af_sky] │ -│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ -│ [default: http://localhost:8880/v1] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Process Management ───────────────────────────────────────────────────────────────────╮ -│ --stop Stop any running background process. │ -│ --status Check if a background process is running. │ -│ --toggle 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. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ History Options ──────────────────────────────────────────────────────────────────────╮ -│ --history-dir PATH Directory to store conversation history. │ -│ [default: ~/.config/agent-cli/history] │ -│ --last-n-messages INTEGER Number of messages to include in the conversation │ -│ history. Set to 0 to disable history. │ -│ [default: 50] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --save-file PATH Save TTS response audio to WAV file. │ -│ --log-level TEXT Set logging level. │ -│ [default: WARNING] │ -│ --log-file TEXT Path to a file to write logs to. │ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including variables │ -│ taken from the configuration file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Provider Selection ─────────────────────────────────────────────────────────╮ +│ --asr-provider TEXT The ASR provider to use ('wyoming', 'openai'). │ +│ [default: wyoming] │ +│ --llm-provider TEXT The LLM provider to use ('ollama', 'openai', │ +│ 'gemini'). │ +│ [default: ollama] │ +│ --tts-provider TEXT The TTS provider to use ('wyoming', 'openai', │ +│ 'kokoro'). │ +│ [default: wyoming] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input ────────────────────────────────────────────────────────────────╮ +│ --input-device-index INTEGER Index of the audio input device to use. │ +│ --input-device-name TEXT Device name keywords for partial │ +│ matching. │ +│ --list-devices List available audio input and output │ +│ devices and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: Wyoming ───────────────────────────────────────────────────────╮ +│ --asr-wyoming-ip TEXT Wyoming ASR server IP address. │ +│ [default: localhost] │ +│ --asr-wyoming-port INTEGER Wyoming ASR server port. │ +│ [default: 10300] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Input: OpenAI-compatible ─────────────────────────────────────────────╮ +│ --asr-openai-model TEXT The OpenAI model to use for ASR │ +│ (transcription). │ +│ [default: whisper-1] │ +│ --asr-openai-base-url TEXT Custom base URL for OpenAI-compatible ASR │ +│ API (e.g., for custom Whisper server: │ +│ http://localhost:9898). │ +│ --asr-openai-prompt TEXT Custom prompt to guide transcription │ +│ (optional). │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Ollama ────────────────────────────────────────────────────────────────╮ +│ --llm-ollama-model TEXT The Ollama model to use. Default is │ +│ gemma3:4b. │ +│ [default: gemma3:4b] │ +│ --llm-ollama-host TEXT The Ollama server host. Default is │ +│ http://localhost:11434. │ +│ [default: http://localhost:11434] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ +│ --llm-openai-model TEXT The OpenAI model to use for LLM tasks. │ +│ [default: gpt-5-mini] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with │ +│ the OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ +│ (e.g., for llama-server: │ +│ http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: Gemini ────────────────────────────────────────────────────────────────╮ +│ --llm-gemini-model TEXT The Gemini model to use for LLM tasks. │ +│ [default: gemini-2.5-flash] │ +│ --gemini-api-key TEXT Your Gemini API key. Can also be set with │ +│ the GEMINI_API_KEY environment variable. │ +│ [env var: GEMINI_API_KEY] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output ───────────────────────────────────────────────────────────────╮ +│ --tts --no-tts Enable text-to-speech for │ +│ responses. │ +│ [default: no-tts] │ +│ --output-device-index INTEGER Index of the audio output │ +│ device to use for TTS. │ +│ --output-device-name TEXT Output device name keywords │ +│ for partial matching. │ +│ --tts-speed FLOAT Speech speed multiplier (1.0 = │ +│ normal, 2.0 = twice as fast, │ +│ 0.5 = half speed). │ +│ [default: 1.0] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Wyoming ──────────────────────────────────────────────────────╮ +│ --tts-wyoming-ip TEXT Wyoming TTS server IP address. │ +│ [default: localhost] │ +│ --tts-wyoming-port INTEGER Wyoming TTS server port. │ +│ [default: 10200] │ +│ --tts-wyoming-voice TEXT Voice name to use for Wyoming TTS │ +│ (e.g., 'en_US-lessac-medium'). │ +│ --tts-wyoming-language TEXT Language for Wyoming TTS (e.g., │ +│ 'en_US'). │ +│ --tts-wyoming-speaker TEXT Speaker name for Wyoming TTS voice. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: OpenAI-compatible ────────────────────────────────────────────╮ +│ --tts-openai-model TEXT The OpenAI model to use for TTS. │ +│ [default: tts-1] │ +│ --tts-openai-voice TEXT The voice to use for OpenAI TTS. │ +│ [default: alloy] │ +│ --tts-openai-base-url TEXT Custom base URL for OpenAI-compatible TTS │ +│ API (e.g., http://localhost:8000/v1 for a │ +│ proxy). │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Audio Output: Kokoro ───────────────────────────────────────────────────────╮ +│ --tts-kokoro-model TEXT The Kokoro model to use for TTS. │ +│ [default: kokoro] │ +│ --tts-kokoro-voice TEXT The voice to use for Kokoro TTS. │ +│ [default: af_sky] │ +│ --tts-kokoro-host TEXT The base URL for the Kokoro API. │ +│ [default: http://localhost:8880/v1] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Process Management ─────────────────────────────────────────────────────────╮ +│ --stop Stop any running background process. │ +│ --status Check if a background process is running. │ +│ --toggle 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. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ History Options ────────────────────────────────────────────────────────────╮ +│ --history-dir PATH Directory to store conversation history. │ +│ [default: ~/.config/agent-cli/history] │ +│ --last-n-messages INTEGER Number of messages to include in the │ +│ conversation history. Set to 0 to disable │ +│ history. │ +│ [default: 50] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --save-file PATH Save TTS response audio to WAV file. │ +│ --log-level TEXT Set logging level. │ +│ [default: WARNING] │ +│ --log-file TEXT Path to a file to write logs to. │ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including │ +│ variables taken from the configuration file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1431,49 +1513,52 @@ uv tool install "agent-cli[vad]" Start the RAG (Retrieval-Augmented Generation) Proxy Server. This server watches a folder for documents, indexes them, and provides an - OpenAI-compatible API that proxies requests to a backend LLM (like llama.cpp), injecting - relevant context from the documents. - -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ RAG Configuration ────────────────────────────────────────────────────────────────────╮ -│ --docs-folder PATH Folder to watch for documents │ -│ [default: ./rag_docs] │ -│ --chroma-path PATH Path to ChromaDB persistence directory │ -│ [default: ./rag_db] │ -│ --limit INTEGER Number of document chunks to retrieve per │ -│ query. │ -│ [default: 3] │ -│ --rag-tools --no-rag-tools Allow agent to fetch full documents when │ -│ snippets are insufficient. │ -│ [default: rag-tools] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ -│ llama-server: http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮ -│ --embedding-model TEXT Embedding model to use for vectorization. │ -│ [default: text-embedding-3-small] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Server Configuration ─────────────────────────────────────────────────────────────────╮ -│ --host TEXT Host/IP to bind API servers to. │ -│ [default: 0.0.0.0] │ -│ --port INTEGER Port to bind to │ -│ [default: 8000] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --log-level TEXT Set logging level. │ -│ [default: INFO] │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including variables taken │ -│ from the configuration file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ + OpenAI-compatible API that proxies requests to a backend LLM (like llama.cpp), + injecting relevant context from the documents. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ RAG Configuration ──────────────────────────────────────────────────────────╮ +│ --docs-folder PATH Folder to watch for documents │ +│ [default: ./rag_docs] │ +│ --chroma-path PATH Path to ChromaDB persistence │ +│ directory │ +│ [default: ./rag_db] │ +│ --limit INTEGER Number of document chunks to │ +│ retrieve per query. │ +│ [default: 3] │ +│ --rag-tools --no-rag-tools Allow agent to fetch full │ +│ documents when snippets are │ +│ insufficient. │ +│ [default: rag-tools] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ +│ (e.g., for llama-server: │ +│ http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ +│ --embedding-model TEXT Embedding model to use for vectorization. │ +│ [default: text-embedding-3-small] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Server Configuration ───────────────────────────────────────────────────────╮ +│ --host TEXT Host/IP to bind API servers to. │ +│ [default: 0.0.0.0] │ +│ --port INTEGER Port to bind to │ +│ [default: 8000] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --log-level TEXT Set logging level. │ +│ [default: INFO] │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including │ +│ variables taken from the configuration file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1527,91 +1612,107 @@ The `memory proxy` command is the core feature—a middleware server that gives Start the memory-backed chat proxy server. - This server acts as a middleware between your chat client (e.g., a web UI, CLI, or IDE - plugin) and an OpenAI-compatible LLM provider (e.g., OpenAI, Ollama, vLLM). + This server acts as a middleware between your chat client (e.g., a web UI, + CLI, or IDE plugin) and an OpenAI-compatible LLM provider (e.g., OpenAI, + Ollama, vLLM). Key Features: - • Simple Markdown Files: Memories are stored as human-readable Markdown files, serving - as the ultimate source of truth. - • Automatic Version Control: Built-in Git integration automatically commits changes, - providing a full history of memory evolution. - • Lightweight & Local: Minimal dependencies and runs entirely on your machine. - • Proxy Middleware: Works transparently with any OpenAI-compatible /chat/completions - endpoint. + • Simple Markdown Files: Memories are stored as human-readable Markdown + files, serving as the ultimate source of truth. + • Automatic Version Control: Built-in Git integration automatically commits + changes, providing a full history of memory evolution. + • Lightweight & Local: Minimal dependencies and runs entirely on your + machine. + • Proxy Middleware: Works transparently with any OpenAI-compatible + /chat/completions endpoint. How it works: 1 Intercepts POST /v1/chat/completions requests. - 2 Retrieves relevant memories (facts, previous conversations) from a local vector - database (ChromaDB) based on the user's query. + 2 Retrieves relevant memories (facts, previous conversations) from a local + vector database (ChromaDB) based on the user's query. 3 Injects these memories into the system prompt. 4 Forwards the augmented request to the real LLM (--openai-base-url). - 5 Extracts new facts from the conversation in the background and updates the long-term - memory store (including handling contradictions). - - Use this to give "long-term memory" to any OpenAI-compatible application. Point your - client's base URL to http://localhost:8100/v1. - -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Memory Configuration ─────────────────────────────────────────────────────────────────╮ -│ --memory-path PATH Path to the memory store (files + │ -│ derived vector index). │ -│ [default: ./memory_db] │ -│ --default-top-k INTEGER Number of memory entries to │ -│ retrieve per query. │ -│ [default: 5] │ -│ --max-entries INTEGER Maximum stored memory entries per │ -│ conversation (excluding summary). │ -│ [default: 500] │ -│ --mmr-lambda FLOAT MMR lambda (0-1): higher favors │ -│ relevance, lower favors │ -│ diversity. │ -│ [default: 0.7] │ -│ --recency-weight FLOAT Recency score weight (0.0-1.0). │ -│ Controls freshness vs. relevance. │ -│ Default 0.2 (20% recency, 80% │ -│ semantic relevance). │ -│ [default: 0.2] │ -│ --score-threshold FLOAT Minimum semantic relevance │ -│ threshold (0.0-1.0). Memories │ -│ below this score are discarded to │ -│ reduce noise. │ -│ [default: 0.35] │ -│ --summarization --no-summarization Enable automatic fact extraction │ -│ and summaries. │ -│ [default: summarization] │ -│ --git-versioning --no-git-versioning Enable automatic git commit of │ -│ memory changes. │ -│ [default: git-versioning] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM: OpenAI-compatible ───────────────────────────────────────────────────────────────╮ -│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API (e.g., for │ -│ llama-server: http://localhost:8080/v1). │ -│ [env var: OPENAI_BASE_URL] │ -│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ -│ OPENAI_API_KEY environment variable. │ -│ [env var: OPENAI_API_KEY] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ LLM Configuration ────────────────────────────────────────────────────────────────────╮ -│ --embedding-model TEXT Embedding model to use for vectorization. │ -│ [default: text-embedding-3-small] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Server Configuration ─────────────────────────────────────────────────────────────────╮ -│ --host TEXT Host/IP to bind API servers to. │ -│ [default: 0.0.0.0] │ -│ --port INTEGER Port to bind to │ -│ [default: 8100] │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --log-level TEXT Set logging level. │ -│ [default: INFO] │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including variables taken │ -│ from the configuration file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ + 5 Extracts new facts from the conversation in the background and updates the + long-term memory store (including handling contradictions). + + Use this to give "long-term memory" to any OpenAI-compatible application. + Point your client's base URL to http://localhost:8100/v1. + +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Memory Configuration ───────────────────────────────────────────────────────╮ +│ --memory-path PATH Path to the memory │ +│ store (files + derived │ +│ vector index). │ +│ [default: ./memory_db] │ +│ --default-top-k INTEGER Number of memory │ +│ entries to retrieve per │ +│ query. │ +│ [default: 5] │ +│ --max-entries INTEGER Maximum stored memory │ +│ entries per │ +│ conversation (excluding │ +│ summary). │ +│ [default: 500] │ +│ --mmr-lambda FLOAT MMR lambda (0-1): │ +│ higher favors │ +│ relevance, lower favors │ +│ diversity. │ +│ [default: 0.7] │ +│ --recency-weight FLOAT Recency score weight │ +│ (0.0-1.0). Controls │ +│ freshness vs. │ +│ relevance. Default 0.2 │ +│ (20% recency, 80% │ +│ semantic relevance). │ +│ [default: 0.2] │ +│ --score-threshold FLOAT Minimum semantic │ +│ relevance threshold │ +│ (0.0-1.0). Memories │ +│ below this score are │ +│ discarded to reduce │ +│ noise. │ +│ [default: 0.35] │ +│ --summarization --no-summarization Enable automatic fact │ +│ extraction and │ +│ summaries. │ +│ [default: │ +│ summarization] │ +│ --git-versioning --no-git-versioning Enable automatic git │ +│ commit of memory │ +│ changes. │ +│ [default: │ +│ git-versioning] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM: OpenAI-compatible ─────────────────────────────────────────────────────╮ +│ --openai-base-url TEXT Custom base URL for OpenAI-compatible API │ +│ (e.g., for llama-server: │ +│ http://localhost:8080/v1). │ +│ [env var: OPENAI_BASE_URL] │ +│ --openai-api-key TEXT Your OpenAI API key. Can also be set with the │ +│ OPENAI_API_KEY environment variable. │ +│ [env var: OPENAI_API_KEY] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ LLM Configuration ──────────────────────────────────────────────────────────╮ +│ --embedding-model TEXT Embedding model to use for vectorization. │ +│ [default: text-embedding-3-small] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Server Configuration ───────────────────────────────────────────────────────╮ +│ --host TEXT Host/IP to bind API servers to. │ +│ [default: 0.0.0.0] │ +│ --port INTEGER Port to bind to │ +│ [default: 8100] │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --log-level TEXT Set logging level. │ +│ [default: INFO] │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including │ +│ variables taken from the configuration file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -1662,11 +1763,11 @@ agent-cli memory add -c work "Project deadline is Friday" Add memories directly without LLM extraction. - This writes facts directly to the memory store, bypassing the LLM-based fact extraction. - Useful for bulk imports or seeding memories. + This writes facts directly to the memory store, bypassing the LLM-based fact + extraction. Useful for bulk imports or seeding memories. - The memory proxy file watcher (if running) will auto-index new files. Otherwise, they'll - be indexed on next memory proxy startup. + The memory proxy file watcher (if running) will auto-index new files. + Otherwise, they'll be indexed on next memory proxy startup. Examples:: @@ -1687,29 +1788,35 @@ agent-cli memory add -c work "Project deadline is Friday" agent-cli memory add -c work "Project deadline is Friday" -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ memories [MEMORIES]... Memories to add. Each argument becomes one fact. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --file -f PATH Read memories from file. Use '-' │ -│ for stdin. Supports JSON array, │ -│ JSON object with 'memories' key, │ -│ or plain text (one per line). │ -│ --conversation-id -c TEXT Conversation ID to add memories │ -│ to. │ -│ [default: default] │ -│ --memory-path PATH Path to the memory store. │ -│ [default: ./memory_db] │ -│ --git-versioning --no-git-versioning Commit changes to git. │ -│ [default: git-versioning] │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ General Options ──────────────────────────────────────────────────────────────────────╮ -│ --quiet -q Suppress console output from rich. │ -│ --config TEXT Path to a TOML configuration file. │ -│ --print-args Print the command line arguments, including variables │ -│ taken from the configuration file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ memories [MEMORIES]... Memories to add. Each argument becomes one │ +│ fact. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --file -f PATH Read memories from file. │ +│ Use '-' for stdin. │ +│ Supports JSON array, │ +│ JSON object with │ +│ 'memories' key, or plain │ +│ text (one per line). │ +│ --conversation-id -c TEXT Conversation ID to add │ +│ memories to. │ +│ [default: default] │ +│ --memory-path PATH Path to the memory │ +│ store. │ +│ [default: ./memory_db] │ +│ --git-versioning --no-git-versioning Commit changes to git. │ +│ [default: │ +│ git-versioning] │ +│ --help -h Show this message and │ +│ exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ General Options ────────────────────────────────────────────────────────────╮ +│ --quiet -q Suppress console output from rich. │ +│ --config TEXT Path to a TOML configuration file. │ +│ --print-args Print the command line arguments, including │ +│ variables taken from the configuration file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ```