Add root -v/--verbose flag for stderr diagnostics

The CLI had no way to see what it was doing on the wire: library loggers
were actively silenced so stderr stayed clean next to normalized errors,
and diagnosing an auth or connectivity problem meant reading code.

A new root flag closes that gap (counted, gh/speechmatics style):
- `-v` surfaces request-level logs (httpx and friends at INFO)
- `-vv` adds wire-level detail (websockets frames, httpcore events at DEBUG)

aai_cli/debuglog.py installs one stderr handler with a redacting
formatter; config.resolve_api_key and AppState.resolve_session register
the API key and session JWT at their resolution choke points so verbose
output can never print them in clear (websockets logs the raw
Authorization header at DEBUG during the handshake). The realtime
silencers (aai_cli.ws, streaming/diagnostics) stand down while verbose
mode is active, and the root callback logs the resolved environment.

https://claude.ai/code/session_01Q6KZYc7FPWhyJkbQLUtq36

Author: claude

.importlinter

@@ -16,6 +16,7 @@ source_modules =
     aai_cli.config
     aai_cli.config_builder
     aai_cli.context
+    aai_cli.debuglog
     aai_cli.environments
     aai_cli.errors
     aai_cli.eval_data
@@ -78,6 +79,7 @@ source_modules =
     aai_cli.client
     aai_cli.config
     aai_cli.config_builder
+    aai_cli.debuglog
     aai_cli.environments
     aai_cli.errors
     aai_cli.eval_data

AGENTS.md

@@ -173,6 +173,7 @@ Each file in `aai_cli/commands/` is a Typer sub-app (`transcribe`, `stream`, `ag
 - **`environments.py`** — a frozen `Environment` (api_base, streaming_host, llm_gateway_base, ams_base, stytch_*). `DEFAULT_ENV` is **`production`**; use `--sandbox` (or `--env sandbox000` / `AAI_ENV`) to target the sandbox. The active environment is a process-global set once at startup; precedence: `--env` → `AAI_ENV` → profile's stored env → default. A credential is only valid against the environment that minted it.
 - **`client.py`** — thin wrappers over the `assemblyai` SDK (`transcribe`, `list_transcripts`, `stream_audio`, etc.). It normalizes SDK exceptions: auth failures become a single clean `auth_failure()` `CLIError`; everything else becomes `APIError`. New SDK calls should follow this try/except shape.
 - **`errors.py`** — the `CLIError` hierarchy (each with `error_type` + `exit_code`). `output.py` emits errors to **stderr**; stdout stays clean for pipelines. `--json` switches to machine-readable output; it is never auto-enabled — `output.resolve_json()` deliberately keeps human text the default even when piped or agent-run.
+- **`debuglog.py`** — the root `-v/--verbose` flag (count: `-v` request-level at INFO, `-vv` wire-level at DEBUG). The CLI normally configures no logging, and the realtime paths *silence* library loggers (`ws.py`, `streaming/diagnostics.py`); verbose mode installs one redacting stderr handler and those silencers stand down. Secrets are registered at their resolution choke points (`config.resolve_api_key`, `AppState.resolve_session`) and masked in every rendered record — websockets logs the raw Authorization header at DEBUG, so masking lives in the formatter, not at call sites. Stdlib-only on purpose: `config` (a Rich-free layer) imports it.
 
 ### Feature subsystems
 

aai_cli/config.py

@@ -14,6 +14,7 @@
 import tomli_w
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
 
+from aai_cli import debuglog
 from aai_cli.errors import CLIError, NotAuthenticated
 
 KEYRING_SERVICE = "assemblyai-cli"
@@ -408,6 +409,18 @@ def set_update_cache(*, last_check: float, latest_version: str | None) -> None:
 
 
 def resolve_api_key(*, profile: str | None = None, api_key_flag: str | None = None) -> str:
+    """The API key for SDK/gateway calls: --api-key flag > ASSEMBLYAI_API_KEY > keyring.
+
+    Every resolved key is registered with the verbose-log redactor
+    (``debuglog.register_secret``) at this single choke point, so ``-v``/``-vv``
+    diagnostics can never print it in clear no matter which library logs it.
+    """
+    key = _resolve_api_key(profile=profile, api_key_flag=api_key_flag)
+    debuglog.register_secret(key)
+    return key
+
+
+def _resolve_api_key(*, profile: str | None, api_key_flag: str | None) -> str:
     # Values are stripped at every tier: a whitespace-only key (e.g. a botched
     # `export ASSEMBLYAI_API_KEY='   '`) must read as "no key" (the clean exit-4
     # not-signed-in path), not get sent as an illegal HTTP header byte string.

aai_cli/context.py

@@ -9,7 +9,7 @@
 import keyring.errors
 import typer
 
-from aai_cli import config, environments, output, telemetry, update_check
+from aai_cli import config, debuglog, environments, output, telemetry, update_check
 from aai_cli.environments import Environment
 from aai_cli.errors import APIError, CLIError, NotAuthenticated
 
@@ -72,6 +72,9 @@ def resolve_session(self) -> tuple[int, str]:
                     "can't access account commands."
                 ),
             )
+        # Registered like the API key in config.resolve_api_key: -v/-vv diagnostics
+        # must never print the session JWT in clear.
+        debuglog.register_secret(session["jwt"])
         return account_id, session["jwt"]
 
     def env_override_warning(self) -> str | None:

aai_cli/debuglog.py

@@ -0,0 +1,70 @@
+"""Opt-in diagnostic logging behind the root ``-v/--verbose`` flag.
+
+The CLI normally configures no logging at all, and the realtime paths actively
+*silence* library loggers so stderr stays clean next to the CLI's normalized
+errors (``aai_cli.ws``, ``aai_cli.streaming.diagnostics``). Verbose mode is the
+inverse switch: ``enable`` installs one stderr handler so library logs become
+visible — ``-v`` surfaces request-level lines (httpx and friends at INFO),
+``-vv`` wire-level detail (websockets frames, httpcore events at DEBUG) — and
+the silencers stand down while it is ``active``.
+
+Secrets never print in clear: ``register_secret`` records sensitive values as
+they are resolved (API key, session JWT) and the handler's formatter masks them
+in every rendered record. Masking must live in the formatter, not at call
+sites, because the leak comes from *library* logs — websockets logs the raw
+Authorization header at DEBUG during the handshake.
+
+Stdlib-only on purpose: ``config`` (a Rich-free library layer) registers
+secrets here, so this module must not pull in Rich via ``output``/``theme``.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+_MASK = "[redacted]"
+
+_verbosity = 0
+_secrets: set[str] = set()
+
+
+class _RedactingFormatter(logging.Formatter):
+    """Formats records normally, then masks every registered secret."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        text = super().format(record)
+        for secret in _secrets:
+            text = text.replace(secret, _MASK)
+        return text
+
+
+def register_secret(value: str | None) -> None:
+    """Record a sensitive value so verbose output masks it. Empty values are
+    ignored (replacing "" would shred every record)."""
+    if value:
+        _secrets.add(value)
+
+
+def active() -> bool:
+    """Whether verbose logging is on — the realtime silencers stand down then."""
+    return _verbosity > 0
+
+
+def enable(verbosity: int) -> None:
+    """Install the stderr diagnostics handler: ``-v`` (1) at INFO, ``-vv``+ at DEBUG.
+
+    Zero is the everyday no-op — no handler, the CLI stays log-silent. The
+    handler goes on the root logger so third-party loggers (httpx, websockets,
+    the assemblyai SDK) are covered without naming each one; stderr keeps the
+    errors-to-stderr / data-to-stdout split intact for pipelines.
+    """
+    global _verbosity
+    if verbosity <= 0:
+        return
+    _verbosity = verbosity
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(_RedactingFormatter("[%(name)s] %(message)s"))
+    root = logging.getLogger()
+    root.addHandler(handler)
+    root.setLevel(logging.INFO if verbosity == 1 else logging.DEBUG)

aai_cli/main.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 import sys
 from types import ModuleType
 from typing import TYPE_CHECKING
@@ -19,7 +20,7 @@
     # context type, not the upstream click.Context. Imported for typing only.
     from typer._click.core import Context as ClickContext
 
-from aai_cli import __version__, argscan, environments, help_panels, output, stdio, theme
+from aai_cli import __version__, argscan, debuglog, environments, help_panels, output, stdio, theme
 from aai_cli.commands import (
     account,
     agent,
@@ -286,6 +287,8 @@ def _profile_has_key(state: AppState) -> bool:
 # honor the request.
 _RAW_ARGS_META_KEY = "aai_raw_args"
 
+_LOG = logging.getLogger("aai_cli")
+
 
 def _sandbox_conflict_warning(sandbox: bool, env: str | None) -> str | None:
     """A warning when ``--sandbox`` and a contradictory ``--env`` are both passed.
@@ -341,6 +344,13 @@ def main(
     quiet: bool = typer.Option(
         False, "--quiet", "-q", help="Suppress non-essential messages (warnings, hints)."
     ),
+    verbose: int = typer.Option(
+        0,
+        "--verbose",
+        "-v",
+        count=True,
+        help="Log diagnostics to stderr (-v: requests, -vv: wire-level detail).",
+    ),
     # Underscore name: the eager callback does the work, so the parameter is intentionally
     # unused in the body (avoids ARG001 without a `del`).
     _version: bool = typer.Option(
@@ -358,6 +368,9 @@ def main(
     # The command's own --json flag isn't parsed yet, so sniff the pending command line:
     # a root-callback failure (e.g. bad --env) still emits the JSON error shape when the
     # invocation opted into JSON, and renders human text on stderr otherwise.
+    # Enabled before anything else runs so even environment/profile resolution
+    # failures can be diagnosed with -v.
+    debuglog.enable(verbose)
     raw_args: list[str] = ctx.meta.get(_RAW_ARGS_META_KEY, [])
     json_mode = output.resolve_json(explicit=argscan.requests_json(raw_args))
     conflict_warning = _sandbox_conflict_warning(sandbox, env)
@@ -370,6 +383,8 @@ def main(
     except CLIError as err:
         output.emit_error(err, json_mode=json_mode)
         raise typer.Exit(code=err.exit_code) from None
+    active_env = environments.active()
+    _LOG.debug("environment: %s (%s)", active_env.name, active_env.api_base)
     for warning in (conflict_warning, state.env_override_warning()):
         if warning and not quiet:
             # Surfaced in JSON mode too (as {"warning": …}), so a `--json` pipeline gets

aai_cli/skills/aai-cli/SKILL.md

@@ -33,9 +33,14 @@ suddenly returns auth errors, check you are on the same `--env` you logged in
 under.
 
 **Profiles.** `--profile <name>` selects a named credential set. Global flags
-(`--profile`, `--env`, `--sandbox`) go *before* the subcommand:
+(`--profile`, `--env`, `--sandbox`, `-v/--verbose`) go *before* the subcommand:
 `assembly --sandbox transcribe call.mp3`.
 
+**Diagnostics.** `assembly -v <command>` logs request-level diagnostics to
+stderr (HTTP requests and statuses); `-vv` adds wire-level detail (WebSocket
+frames, connection events). Secrets (API key, session JWT) are redacted from
+that output. Use this to debug auth/connectivity instead of guessing.
+
 ## Output contract (read this before parsing output)
 
 - **Data goes to stdout; errors and progress go to stderr.** Piping stdout is

aai_cli/streaming/diagnostics.py

@@ -11,6 +11,7 @@
 
 import logging
 
+from aai_cli import debuglog
 from aai_cli import ws as wsutil
 from aai_cli.errors import APIError, CLIError, NotAuthenticated
 
@@ -29,9 +30,13 @@ def silence_streaming_logging() -> None:
     """Silence the library loggers that would dirty stderr during a realtime run.
 
     Extends the shared websockets silencing (``aai_cli.ws``) with the assemblyai
-    SDK's streaming logger, which only the `stream` path uses. Idempotent.
+    SDK's streaming logger, which only the `stream` path uses. Idempotent. Stands
+    down (like ``aai_cli.ws``) under the root ``-v/--verbose`` flag, where library
+    logs are the requested output.
     """
     wsutil.silence_websockets_logging()
+    if debuglog.active():
+        return
     logging.getLogger(SDK_STREAMING_LOGGER).setLevel(logging.CRITICAL)
 
 

aai_cli/ws.py

@@ -9,6 +9,7 @@
 
 import logging
 
+from aai_cli import debuglog
 from aai_cli.errors import APIError, CLIError, auth_failure, is_auth_failure
 
 # A pre-upgrade HTTP 403 on the WebSocket handshake is NOT a rejected key (it also
@@ -31,7 +32,12 @@ def silence_websockets_logging() -> None:
     ``websockets.client`` logger, which would land on stderr right next to our clean
     CLIError. Those internals are never user-actionable from the CLI, so raise the
     loggers above every level they emit at. Idempotent: re-setting the level is a no-op.
+
+    Stands down under the root ``-v/--verbose`` flag: wire-level frames are exactly
+    what ``-vv`` exists to show, so verbose mode leaves the loggers untouched.
     """
+    if debuglog.active():
+        return
     for name in WEBSOCKETS_LOGGERS:
         logging.getLogger(name).setLevel(logging.CRITICAL)
 

pyproject.toml

@@ -256,6 +256,8 @@ max-statements = 40
 "aai_cli/output.py" = ["T201"]
 # The active environment is process-global startup state by design.
 "aai_cli/environments.py" = ["PLW0603"]
+# Verbosity is process-global startup state by design (mirrors environments.py).
+"aai_cli/debuglog.py" = ["PLW0603"]
 # BaseHTTPRequestHandler.log_message requires a parameter named `format`.
 "aai_cli/auth/loopback.py" = ["A002"]
 # Template constants include URL path names such as TOKEN_PATH, not credentials.