Help examples, error suggestions, and test cleanup

.github/workflows/ci.yml

@@ -33,10 +33,11 @@ jobs:
         run: npm install -g markdownlint-cli@0.45.0
 
       # check.sh runs every tool through `uv run` / `uv build` for a locked,
-      # reproducible env, so uv must be on PATH (installed from PyPI to match the
-      # repo's pip-based, no-new-action posture).
+      # reproducible env, so only uv must be on PATH (installed from PyPI to match
+      # the repo's pip-based, no-new-action posture). `uv run` itself syncs the
+      # project + dev group into .venv, so no `pip install -e .` is needed here.
       - name: Install
-        run: python -m pip install -e ".[dev]" uv
+        run: python -m pip install uv
 
       - name: Lint, typecheck, test
         run: ./scripts/check.sh
@@ -55,9 +56,12 @@ jobs:
       - name: System deps (PortAudio + ffmpeg)
         run: sudo apt-get update && sudo apt-get install -y libportaudio2 ffmpeg
 
-      # The local pytest hook runs `python -m pytest`, so the package must be importable.
+      # The local pytest hook runs `python -m pytest`, so the package + dev group
+      # must be importable. `pip install --group` needs pip >= 25.1, so upgrade first.
       - name: Install
-        run: python -m pip install -e ".[dev]"
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e . --group dev
 
       - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
 

.pre-commit-config.yaml

@@ -2,15 +2,20 @@ repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
+      # syrupy indents every line of an .ambr block (blank lines become "  "), so
+      # trimming/EOF-fixing those files desyncs them from the live render and breaks
+      # the snapshot tests. Leave the generated snapshots alone.
       - id: trailing-whitespace
+        exclude: ^tests/__snapshots__/
       - id: end-of-file-fixer
+        exclude: ^tests/__snapshots__/
       - id: check-yaml
       - id: check-toml
       - id: check-merge-conflict
       - id: check-added-large-files
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.13
+    rev: v0.15.16
     hooks:
       - id: ruff
         args: [--fix]

README.md

@@ -10,7 +10,7 @@ curl -fsSL https://github.com/ghraw/AssemblyAI/cli/main/install.sh | sh
 ```
 
 The installer uses [`pipx`](https://pipx.pypa.io) when available (falling back to
-`pip --user`) and requires Python 3.10+. Prefer to do it yourself:
+`pip --user`) and requires Python 3.11+. Prefer to do it yourself:
 
 ```sh
 pipx install "git+https://github.com/AssemblyAI/cli.git"   # or: pip install --user ...

aai_cli/agent/audio.py

@@ -36,6 +36,7 @@ def _default_output_stream(rate: int) -> Any:
             f"Could not open the audio output device: {exc}",
             error_type="audio_output_error",
             exit_code=1,
+            suggestion="Check your speaker/output device, then run 'aai doctor'.",
         ) from exc
     return stream
 
@@ -154,6 +155,7 @@ def _default_duplex_stream(*, rate: int, blocksize: int, callback: Any, device:
             f"Could not open the audio device: {exc}",
             error_type="audio_output_error",
             exit_code=1,
+            suggestion="Check your microphone/output device, then run 'aai doctor'.",
         ) from exc
     return stream
 

aai_cli/auth/flow.py

@@ -1,20 +1,25 @@
 from __future__ import annotations
 
 import webbrowser
+from collections.abc import Mapping
 from typing import Any
 
 from aai_cli import output
 from aai_cli.auth import ams, discovery, endpoints, loopback
 from aai_cli.errors import APIError
 
 
-def _require(mapping: Any, key: str, what: str) -> Any:
+def _require(mapping: Mapping[str, Any], key: str, what: str) -> Any:
     """Pull a required field out of an AMS response, or raise a clean APIError.
 
     AMS only returns HTTP errors for outright failures; a 200 with an unexpected
     shape would otherwise KeyError into an ugly traceback, so map that to the same
-    "run login again" message the rest of the flow uses.
+    "run login again" message the rest of the flow uses. The return stays `Any`
+    because AMS JSON leaves are untyped and callers coerce them (int()/str()).
     """
+    # Nested calls pass an `Any`-typed value that the type checker accepts as a
+    # Mapping but which may be a non-mapping at runtime (e.g. a malformed 200),
+    # so still guard with isinstance before calling .get.
     value = mapping.get(key) if isinstance(mapping, dict) else None
     if value is None:
         raise APIError(
@@ -55,7 +60,10 @@ def find_or_create_cli_key(account_id: int, session_jwt: str) -> str:
     """Return the existing 'AssemblyAI CLI' key, or create one in the first project."""
     projects = ams.list_projects(account_id, session_jwt)
     if not projects:
-        raise APIError("Your account has no project to create an API key in.")
+        raise APIError(
+            "Your account has no project to create an API key in.",
+            suggestion="Create a project in the AssemblyAI dashboard, then run 'aai login' again.",
+        )
     for entry in projects:
         for token in entry.get("tokens", []):
             if _is_reusable_cli_token(token):
@@ -71,9 +79,15 @@ def run_login_flow() -> str:
     result = _capture()
 
     if result.error == "timeout":
-        raise APIError("Login timed out waiting for the browser. Run 'aai login' again.")
+        raise APIError(
+            "Login timed out waiting for the browser.",
+            suggestion="Run 'aai login' again.",
+        )
     if result.token_type != "discovery_oauth" or not result.token:  # noqa: S105
-        raise APIError("Login did not return a valid OAuth token. Run 'aai login' again.")
+        raise APIError(
+            "Login did not return a valid OAuth token.",
+            suggestion="Run 'aai login' again.",
+        )
 
     disc = ams.discover(result.token)
     organizations = disc.get("organizations") or []

aai_cli/client.py

@@ -26,7 +26,10 @@ def resolve_audio_source(source: str | None, *, sample: bool) -> str:
     if sample:
         return SAMPLE_AUDIO_URL
     if not source:
-        raise UsageError("Provide an audio path/URL or use --sample.")
+        raise UsageError(
+            "Provide an audio path or URL.",
+            suggestion="Or pass --sample to use the hosted demo file.",
+        )
     return source
 
 

aai_cli/commands/agent.py

@@ -13,12 +13,22 @@
 from aai_cli.agent.voices import DEFAULT_VOICE, VOICES, format_voice_list
 from aai_cli.context import AppState, run_command
 from aai_cli.errors import CLIError, UsageError
+from aai_cli.help_text import examples_epilog
 from aai_cli.streaming.sources import FileSource
 
 app = typer.Typer()
 
 
-@app.command()
+@app.command(
+    epilog=examples_epilog(
+        [
+            ("Start a live voice conversation", "aai agent"),
+            ("Pick a voice and opening line", 'aai agent --voice james --greeting "Hi there"'),
+            ("See available voices", "aai agent --list-voices"),
+            ("Print equivalent Python instead of running", "aai agent --show-code"),
+        ]
+    )
+)
 def agent(
     ctx: typer.Context,
     source: str = typer.Argument(
@@ -65,7 +75,10 @@ def agent(
     def body(state: AppState, json_mode: bool) -> None:
         text_mode, json_mode = output.stream_output_modes(output_field, json_mode)
         if voice not in VOICES:
-            raise UsageError(f"Unknown voice {voice!r}. Run 'aai agent --list-voices'.")
+            raise UsageError(
+                f"Unknown voice {voice!r}.",
+                suggestion="Run 'aai agent --list-voices' to see the options.",
+            )
         if system_prompt_file is not None:
             try:
                 system_prompt_text = system_prompt_file.read_text(encoding="utf-8")
@@ -74,6 +87,7 @@ def body(state: AppState, json_mode: bool) -> None:
                     f"Could not read --system-prompt-file {system_prompt_file}: {exc}",
                     error_type="file_not_found",
                     exit_code=2,
+                    suggestion="Check the path and that the file is readable.",
                 ) from exc
         else:
             system_prompt_text = system_prompt

aai_cli/commands/claude.py

@@ -10,6 +10,7 @@
 from aai_cli import output
 from aai_cli.context import AppState, run_command
 from aai_cli.errors import UsageError
+from aai_cli.help_text import examples_epilog
 from aai_cli.steps import Step, render_steps
 
 app = typer.Typer(
@@ -187,7 +188,14 @@ def _render(data: dict[str, list[Step]]) -> str:
     return render_steps(data["steps"], heading=_STEPS_HEADING)
 
 
-@app.command()
+@app.command(
+    epilog=examples_epilog(
+        [
+            ("Wire AssemblyAI docs + skill into Claude Code", "aai claude install"),
+            ("Install for the current project only", "aai claude install --scope project"),
+        ]
+    )
+)
 def install(
     ctx: typer.Context,
     scope: str = typer.Option(
@@ -216,7 +224,13 @@ def body(_state: AppState, json_mode: bool) -> None:
     run_command(ctx, body, json=json_out)
 
 
-@app.command()
+@app.command(
+    epilog=examples_epilog(
+        [
+            ("Show whether Claude Code is wired up", "aai claude status"),
+        ]
+    )
+)
 def status(
     ctx: typer.Context,
     json_out: bool = typer.Option(False, "--json", help="Output raw JSON."),
@@ -230,7 +244,13 @@ def body(_state: AppState, json_mode: bool) -> None:
     run_command(ctx, body, json=json_out)
 
 
-@app.command()
+@app.command(
+    epilog=examples_epilog(
+        [
+            ("Remove the AssemblyAI MCP server and skill", "aai claude remove"),
+        ]
+    )
+)
 def remove(
     ctx: typer.Context,
     scope: str | None = typer.Option(

aai_cli/commands/doctor.py

@@ -10,6 +10,7 @@
 from aai_cli import client, config, output
 from aai_cli.context import AppState, resolve_profile, run_command
 from aai_cli.errors import CLIError, NotAuthenticated
+from aai_cli.help_text import examples_epilog
 
 app = typer.Typer()
 
@@ -31,14 +32,14 @@ class Check(TypedDict):
 def _check_python() -> Check:
     v = sys.version_info
     version = f"{v.major}.{v.minor}.{v.micro}"
-    if v >= (3, 10):
+    if v >= (3, 11):
         return {"name": "python", "status": "ok", "affects": [], "detail": version, "fix": None}
     return {
         "name": "python",
         "status": "fail",
         "affects": ["everything"],
-        "detail": f"Python {version} is too old; the CLI needs 3.10+",
-        "fix": "Install Python 3.10 or newer, then reinstall the CLI.",
+        "detail": f"Python {version} is too old; the CLI needs 3.11+",
+        "fix": "Install Python 3.11 or newer, then reinstall the CLI.",
     }
 
 
@@ -187,7 +188,13 @@ def _render(data: dict[str, object]) -> str:
     return "\n".join(lines)
 
 
-@app.command()
+@app.command(
+    epilog=examples_epilog(
+        [
+            ("Check your environment is ready", "aai doctor"),
+        ]
+    )
+)
 def doctor(
     ctx: typer.Context,
     json_out: bool = typer.Option(False, "--json", help="Output raw JSON."),

aai_cli/commands/init.py

@@ -10,6 +10,7 @@
 from aai_cli import __version__, environments, output, steps
 from aai_cli.context import AppState, run_command
 from aai_cli.errors import CLIError
+from aai_cli.help_text import examples_epilog
 from aai_cli.init import keys, runner, scaffold, templates
 
 # Single-command sub-typer flattened to `aai init` (the exact pattern `aai transcribe`
@@ -58,7 +59,15 @@ def _resolve_dir(directory: str | None, template: str, *, here: bool) -> Path:
     return Path.cwd() / f"{template}-app"
 
 
-@app.command()
+@app.command(
+    epilog=examples_epilog(
+        [
+            ("Scaffold a new app interactively", "aai init"),
+            ("Scaffold a transcribe app into ./my-app", "aai init transcribe my-app"),
+            ("Scaffold into the current directory", "aai init transcribe --here"),
+        ]
+    )
+)
 def init(
     ctx: typer.Context,
     template: str = typer.Argument(None, help="Template to scaffold (omit to pick interactively)."),

aai_cli/commands/llm.py

@@ -8,11 +8,20 @@
 from aai_cli.context import AppState, run_command
 from aai_cli.errors import UsageError
 from aai_cli.follow import FollowRenderer
+from aai_cli.help_text import examples_epilog
 
 app = typer.Typer()
 
 
-@app.command()
+@app.command(
+    epilog=examples_epilog(
+        [
+            ("Summarize a past transcript", 'aai llm "summarize" --transcript-id 5551234-abcd'),
+            ("Pipe any text in", 'echo "meeting notes" | aai llm "turn into action items"'),
+            ("See available models", "aai llm --list-models"),
+        ]
+    )
+)
 def llm(
     ctx: typer.Context,
     prompt: str = typer.Argument(None, help="The prompt to send to the model."),
@@ -95,7 +104,10 @@ def ask(transcript_text: str) -> str:
 
     def body(state: AppState, json_mode: bool) -> None:
         if not prompt:
-            raise UsageError("Provide a prompt, or use --list-models.")
+            raise UsageError(
+                "Provide a prompt.",
+                suggestion="Or pass --list-models to see available models.",
+            )
         output.validate_output_field(output_field, ("text", "json"))
         api_key = config.resolve_api_key(profile=state.profile)
         # Text piped on stdin becomes the content the prompt operates on, unless an