qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/cli.py

@@ -0,0 +1,1168 @@
+from __future__ import annotations
+
+import signal as _signal
+import sys
+from typing import Any
+
+import typer
+from rich import box
+from rich.align import Align
+from rich.console import Console
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.table import Table
+from rich.text import Text
+
+from . import audit as _audit
+from . import config as _cfg
+from . import extras as _extras
+from .commands import asset, ca, cs, csam, etm, pc, pm, scanauth, sub, tc, user, vm, was
+
+_err = Console(stderr=True)
+
+
+def _qualys_cli_version() -> str:
+    try:
+        from importlib.metadata import version
+        return version("qualys-cli")
+    except Exception:
+        return "0.0.0"
+
+app = typer.Typer(
+    name="qualys-cli",
+    help="Qualys API CLI — VM, PC, PM, ETM, WAS, TC, CA, CS, CSAM and more.",
+    invoke_without_command=True,
+    pretty_exceptions_enable=False,
+    rich_markup_mode="rich",
+)
+
+# Qualys brand red (#ed2e26).
+_QUALYS_RED = "#ed2e26"
+
+# "QUALYS" wordmark in block capitals (the Q keeps its little tail).
+_WORDMARK = """\
+ ██████  ██    ██  █████  ██      ██    ██  ███████
+██    ██ ██    ██ ██   ██ ██       ██  ██  ██
+██    ██ ██    ██ ███████ ██        ████   ███████
+██ ▄▄ ██ ██    ██ ██   ██ ██         ██        ██
+ ██████   ██████  ██   ██ ███████    ██    ███████
+    ▀▀\
+"""
+
+
+def _print_banner() -> None:
+    if not _err.is_terminal:
+        return
+    try:
+        from importlib.metadata import version
+        ver = version("qualys-cli")
+    except Exception:
+        ver = "0.1.0"
+
+    _err.print()
+    _err.print(Align.center(Text(_WORDMARK, style=f"bold {_QUALYS_RED}")))
+    _err.print(Rule(
+        f"[dim]v{ver}  ·  A unified command-line interface for the Qualys REST APIs[/dim]",
+        style=_QUALYS_RED,
+    ))
+    _err.print()
+
+    # ── Capabilities summary ────────────────────────────────────────────────
+    cap = Table(
+        box=None, show_header=False, show_edge=False,
+        padding=(0, 1), pad_edge=False,
+    )
+    cap.add_column(no_wrap=True)               # icon
+    cap.add_column(no_wrap=True, min_width=20) # label
+    cap.add_column(no_wrap=False)              # description
+    cap.add_row(
+        "[bold #ed2e26]●[/bold #ed2e26]",
+        "[bold]Vuln & Compliance[/bold]",
+        "[red1]vm[/red1] · [red1]pc[/red1] · [red1]was[/red1]   "
+        "[dim]scans, hosts, KB, policies, posture, web-app findings[/dim]",
+    )
+    cap.add_row(
+        "[bold #ed2e26]●[/bold #ed2e26]",
+        "[bold]Cloud Security[/bold]",
+        "[dodger_blue1]tc[/dodger_blue1] · [dodger_blue1]ca[/dodger_blue1] · "
+        "[dodger_blue1]cs[/dodger_blue1] · [dodger_blue1]csam[/dodger_blue1]   "
+        "[dim]CSPM, agents, containers, asset & EASM inventory[/dim]",
+    )
+    cap.add_row(
+        "[bold #ed2e26]●[/bold #ed2e26]",
+        "[bold]Patch & Risk[/bold]",
+        "[dark_orange]pm[/dark_orange] · [dark_orange]etm[/dark_orange]   "
+        "[dim]deployment jobs, mitigations, TruRisk reports[/dim]",
+    )
+    cap.add_row(
+        "[bold #ed2e26]●[/bold #ed2e26]",
+        "[bold]Asset & User Mgmt[/bold]",
+        "[medium_spring_green]asset[/medium_spring_green] · "
+        "[medium_spring_green]user[/medium_spring_green] · "
+        "[medium_spring_green]scanauth[/medium_spring_green] · "
+        "[medium_spring_green]sub[/medium_spring_green]   "
+        "[dim]IPs, networks, groups, auth records, subscription[/dim]",
+    )
+    _err.print(cap)
+    _err.print()
+
+    # ── Quick-start hints ───────────────────────────────────────────────────
+    hint = Table(
+        box=None, show_header=False, show_edge=False,
+        padding=(0, 1), pad_edge=False,
+    )
+    hint.add_column(no_wrap=True)               # arrow
+    hint.add_column(no_wrap=True, min_width=20) # description
+    hint.add_column(no_wrap=False)              # command
+    hint.add_row("[bold yellow]→[/bold yellow]", "[dim]Get started[/dim]",
+                 "[cyan]qualys-cli configure[/cyan]")
+    hint.add_row("[bold yellow]→[/bold yellow]", "[dim]Browse all modules[/dim]",
+                 "[cyan]qualys-cli help[/cyan]")
+    hint.add_row("[bold yellow]→[/bold yellow]", "[dim]Switch output mode[/dim]",
+                 "[cyan]qualys-cli mode agentic[/cyan]   "
+                 "[dim](JSON for scripts/agents)[/dim]")
+    hint.add_row("[bold yellow]→[/bold yellow]", "[dim]Per-command flags[/dim]",
+                 "[cyan]qualys-cli <module> <cmd> --help[/cyan]")
+    _err.print(hint)
+
+    _err.print()
+    _err.print(Rule(
+        "[dim]209 commands across 13 Qualys APIs  ·  "
+        "rich tables for humans, clean JSON for agents  ·  "
+        "JWT auto-refresh · retry/backoff · OS-keyring credential storage[/dim]",
+        style=_QUALYS_RED,
+    ))
+    _err.print()
+
+# ── Register every command group into a named Typer help panel ─────────────
+# Typer's `rich_help_panel` argument groups entries into separately-bordered
+# boxes in the root --help output. Without this, all 27 sub-apps render as
+# one flat list, which is hard to scan. Panels mirror the four operational
+# domains (Vuln & Compliance, Cloud Security, Patch & Risk, Asset & User
+# Management) plus an "Operator & Automation" section for the cross-cutting
+# utility commands and a "Configuration & Diagnostics" section for the local
+# top-level entries (configure / mode / profiles / doctor / etc.).
+
+_PANEL_VC = "Vulnerability & Compliance"
+_PANEL_CS = "Cloud Security"
+_PANEL_PR = "Patch & Risk"
+_PANEL_AU = "Asset & User Management"
+_PANEL_OP = "Operator & Automation"
+_PANEL_AGENT = "Agent & Integration Bridges"
+_PANEL_CFG = "Configuration & Diagnostics"
+
+# Vulnerability & Compliance APIs
+app.add_typer(vm.app,       rich_help_panel=_PANEL_VC)
+app.add_typer(pc.app,       rich_help_panel=_PANEL_VC)
+app.add_typer(was.app,      rich_help_panel=_PANEL_VC)
+
+# Cloud Security APIs
+app.add_typer(tc.app,       rich_help_panel=_PANEL_CS)
+app.add_typer(ca.app,       rich_help_panel=_PANEL_CS)
+app.add_typer(cs.app,       rich_help_panel=_PANEL_CS)
+app.add_typer(csam.app,     rich_help_panel=_PANEL_CS)
+
+# Patch & Risk APIs
+app.add_typer(pm.app,       rich_help_panel=_PANEL_PR)
+app.add_typer(etm.app,      rich_help_panel=_PANEL_PR)
+
+# Asset & User Management APIs
+app.add_typer(asset.app,    rich_help_panel=_PANEL_AU)
+app.add_typer(scanauth.app, rich_help_panel=_PANEL_AU)
+app.add_typer(user.app,     rich_help_panel=_PANEL_AU)
+app.add_typer(sub.app,      rich_help_panel=_PANEL_AU)
+
+# Operator & Automation utilities — preflight, audit, history, batch
+app.add_typer(_extras.doctor_app,       name="doctor",       rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.health_app,       name="health",       rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.stats_app,        name="stats",        rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.verify_audit_app, name="verify-audit", rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.rotate_jwt_app,   name="rotate-jwt",   rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.last_app,         name="last",         rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.replay_app,       name="replay",       rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.watch_app,        name="watch",        rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.batch_app,        name="batch",        rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.query_app,        name="query",        rich_help_panel=_PANEL_OP)
+app.add_typer(_extras.cache_app,        name="cache",        rich_help_panel=_PANEL_OP)
+
+# Agent / integration bridges (MCP, HTTP server, shell completion)
+app.add_typer(_extras.mcp_app,          name="mcp",          rich_help_panel=_PANEL_AGENT)
+app.add_typer(_extras.serve_app,        name="serve",        rich_help_panel=_PANEL_AGENT)
+app.add_typer(_extras.completion_app,   name="completion",   rich_help_panel=_PANEL_AGENT)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        try:
+            from importlib.metadata import version
+            ver = version("qualys-cli")
+        except Exception:
+            ver = "0.1.0"
+        _err.print(f"[bold]qualys-cli[/bold] [cyan]{ver}[/cyan]")
+        raise typer.Exit()
+
+
+_NO_AUTH_CMDS = {
+    "configure", "profiles", "help", "mode",
+    # Local-only utility commands that don't need credentials to be useful
+    "stats", "verify-audit", "last", "replay", "completion", "cache",
+    "query", "batch", "watch",
+}
+
+
+def _apply_profile_mode(profile_name: str) -> None:
+    """Read output_mode from the profile and patch all Console instances."""
+    import os
+
+    from rich.console import Console as _Console
+
+    from . import client as _client_mod
+    from . import formatters as _fmt
+
+    mode = os.environ.get("QUALYS_OUTPUT_MODE", "")
+    if not mode:
+        try:
+            p = _cfg.get_profile(profile_name)
+            mode = p.output_mode
+        except Exception:
+            mode = "interactive"
+
+    if mode == "agentic":
+        force, no_color = False, True
+    else:  # interactive
+        force, no_color = True, False
+
+    global _err
+    _err = _Console(stderr=True, force_terminal=force, no_color=no_color)
+    _fmt._console = _Console(force_terminal=force, no_color=no_color)
+    _fmt._err = _Console(stderr=True, force_terminal=force, no_color=no_color)
+    _client_mod._console = _Console(stderr=True, force_terminal=force, no_color=no_color)
+
+
+def _maybe_auto_configure(profile: str) -> None:
+    """If credentials are missing and we're in a TTY, run the configure wizard automatically."""
+    # In non-TTY mode errors surface as JSON — don't prompt
+    if not _err.is_terminal:
+        return
+    try:
+        _cfg.get_profile(profile)
+        return  # credentials OK
+    except ValueError:
+        pass
+
+    _err.print()
+    _err.print(Panel(
+        f"No credentials found for profile [bold]{profile}[/bold].\n"
+        "Let's configure them now.",
+        title="[bold yellow] First-time Setup [/bold yellow]",
+        border_style="yellow",
+        expand=False,
+    ))
+    _err.print()
+
+    username = typer.prompt("Username")
+    password = typer.prompt("Password", hide_input=True, confirmation_prompt=True)
+    _save_and_show(profile, username, password, output_mode="interactive", continuing=True)
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    profile: str = typer.Option(
+        "default", "--profile", "-p", envvar="QUALYS_PROFILE",
+        help="Named credential profile",
+    ),
+    version: bool | None = typer.Option(
+        None, "--version", "-V",
+        is_eager=True, callback=_version_callback,
+        help="Show version and exit",
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", "--explain",
+        help="Print the resolved HTTP request and exit without sending it",
+    ),
+) -> None:
+    """Qualys API CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj["profile_name"] = profile
+
+    # Apply output mode before any output so banners/JSON/spinners are correct.
+    _apply_profile_mode(profile)
+
+    # Always assign so a test using --dry-run doesn't leak DRY_RUN=True into
+    # subsequent in-process invocations (CliRunner reuses module state).
+    from . import client as _client_mod
+    _client_mod.DRY_RUN = bool(dry_run)
+
+    # Stamp the active profile/username onto the audit log as soon as we know
+    # them. The username may be unavailable (no config yet) — that's fine,
+    # subsequent log lines still carry the correlation ID.
+    try:
+        prof = _cfg.get_profile(profile)
+        username = prof.username
+    except Exception:
+        prof = None
+        username = ""
+    _audit.init(profile=profile, username=username)
+
+    # Surface schema warnings on the active profile (typos in config.toml etc.)
+    # once per invocation, never blocking the command itself.
+    for warn in _cfg.collect_warnings():
+        if _err.is_terminal:
+            _err.print(f"  [yellow]⚠ config:[/yellow] [dim]{warn}[/dim]")
+
+    # Wire profile-driven output redaction (PII / customer-field protection).
+    # Always assign LOCKED_MODE (even when there's no profile yet) so a
+    # locked profile from an earlier in-process invocation can't leak into
+    # a later one that has no profile (relevant for CliRunner-based tests
+    # that reuse module state, same concern as DRY_RUN above).
+    from . import formatters as _fmt
+    _fmt.LOCKED_MODE = bool(prof and prof.locked_mode)
+    if prof and prof.redact_fields:
+        _fmt.REDACT_FIELDS = list(prof.redact_fields)
+
+    # Locked-mode and scope-restricted profile enforcement.
+    if prof:
+        invoked = ctx.invoked_subcommand or ""
+
+        # Locked mode: refuses free-form --output-file paths (enforced in
+        # formatters.guard_output_file / output()), suppresses verbose request
+        # logging (enforced in client.make(), which zeroes `verbose` for a
+        # locked profile), and refuses to run at all against a profile that
+        # still has a plaintext password in config.toml.
+        if prof.locked_mode:
+            has_plaintext = any(
+                "plaintext" in w and f"'{profile}'" in w for w in _cfg.collect_warnings()
+            )
+            if has_plaintext and invoked not in _NO_AUTH_CMDS:
+                _err.print(Panel(
+                    f"Profile [bold]{profile}[/bold] is locked but still has a "
+                    "plaintext password in config.toml.\n\n"
+                    "Run [cyan]qualys-cli configure[/cyan] to move it into the "
+                    "OS keyring before using a locked profile.",
+                    title="[bold red] Locked mode — plaintext password refused [/bold red]",
+                    border_style="red", expand=False,
+                ))
+                raise typer.Exit(3)
+
+        if prof.allowed_modules and invoked and invoked not in _NO_AUTH_CMDS \
+                and invoked not in {*prof.allowed_modules, "doctor", "health"}:
+            _err.print(Panel(
+                f"Profile [bold]{profile}[/bold] is scope-restricted and may not invoke "
+                f"the [bold]{invoked}[/bold] module.\n\n"
+                f"Allowed: [cyan]{', '.join(prof.allowed_modules)}[/cyan]",
+                title="[bold red] Scope restriction [/bold red]",
+                border_style="red", expand=False,
+            ))
+            raise typer.Exit(3)
+
+    if ctx.invoked_subcommand is None:
+        _print_banner()
+        _err.print(ctx.get_help())
+        raise typer.Exit()
+
+    if ctx.invoked_subcommand not in _NO_AUTH_CMDS:
+        _maybe_auto_configure(profile)
+
+
+_OP_STYLES: dict[str, str] = {
+    "list":   "bold cyan",
+    "get":    "bold cyan",
+    "count":  "bold cyan",
+    "create": "bold green",
+    "update": "bold green",
+    "patch":  "bold green",
+    "import": "bold green",
+    "add":    "bold green",
+    "manage": "bold green",
+    "launch": "bold yellow",
+    "run":    "bold yellow",
+    "fetch":  "bold yellow",
+    "scan":   "bold yellow",
+    "delete": "bold red",
+    "remove": "bold red",
+    "cancel": "bold red",
+    "purge":  "bold red",
+    "export": "bold blue",
+    "download": "bold blue",
+    "config": "bold magenta",
+    "info":   "bold cyan",
+    "sync":   "bold green",
+    "activate":   "bold green",
+    "deactivate": "bold red",
+    "enable":     "bold green",
+    "disable":    "bold red",
+}
+
+# Per-module metadata for the in-CLI help screen. Each entry:
+#   color, friendly title, domain (groups modules into colored sections)
+_VC = "Vulnerability & Compliance"
+_CS = "Cloud Security"
+_PR = "Patch & Risk"
+_AU = "Asset & User Management"
+_MODULE_DISPLAY: dict[str, tuple[str, str, str]] = {
+    "vm":       ("red1",                "Vulnerability Management",   _VC),
+    "pc":       ("red1",                "Policy Compliance",          _VC),
+    "was":      ("red1",                "Web App Scanning",           _VC),
+    "tc":       ("dodger_blue1",        "TotalCloud CSPM",            _CS),
+    "ca":       ("dodger_blue1",        "Cloud Agent",                _CS),
+    "cs":       ("dodger_blue1",        "Container Security",         _CS),
+    "csam":     ("dodger_blue1",        "CyberSecurity Asset Mgmt",   _CS),
+    "pm":       ("dark_orange",         "Patch Management",           _PR),
+    "etm":      ("dark_orange",         "Enterprise TruRisk Mgmt",    _PR),
+    "asset":    ("medium_spring_green", "IP / Network / Group Mgmt",  _AU),
+    "user":     ("medium_spring_green", "User Management",            _AU),
+    "scanauth": ("medium_spring_green", "Scan Auth Records",          _AU),
+    "sub":      ("medium_spring_green", "Subscription",               _AU),
+}
+
+# Order of domain sections in the help screen
+_DOMAIN_ORDER = [
+    "Vulnerability & Compliance",
+    "Cloud Security",
+    "Patch & Risk",
+    "Asset & User Management",
+]
+_DOMAIN_RULE_COLORS = {
+    "Vulnerability & Compliance": "red1",
+    "Cloud Security":             "dodger_blue1",
+    "Patch & Risk":               "dark_orange",
+    "Asset & User Management":    "medium_spring_green",
+}
+
+
+_BUCKET_REWRITES: dict[str, str] = {
+    # Map command-final tokens to a sensible action bucket so help stays tidy
+    "scan-again": "run",
+    "edit-severity": "manage",
+    "ignore": "manage",
+    "reactivate": "manage",
+    "restore": "manage",
+    "retest": "run",
+    "retest-status": "get",
+    "results": "fetch",
+    "burp": "import",
+    "owasp-zap": "import",
+    "add-to-subscription": "create",
+    "create-webapp": "create",
+    "create-scan": "create",
+    "list-by-asset": "list",
+    "list-easm": "list",
+    "list-scan": "list",
+    "import-asset": "import",
+    "import-app": "import",
+    "sn-export": "export",
+    "change-status": "manage",
+    "bulk-delete": "delete",
+    "bulk-activate": "manage",
+    "bulk-deactivate": "manage",
+    "launch-ods": "launch",
+    "user-prefs": "config",
+    "download-resource": "download",
+    "data": "get",
+    "products": "list",
+    "columns": "get",
+    "runs": "list",
+    "summary": "get",
+    "findings": "list",
+    "vulns": "list",
+    "software": "list",
+    "generate": "run",
+    "change-password": "manage",
+    "orgs": "list",
+}
+
+
+def _walk_module(t: typer.Typer, prefix: str = "") -> list[tuple[str, str]]:
+    """Return [(operation_name, action_bucket), ...] for every command under a Typer.
+
+    operation_name is the dotted command path inside the module
+    (e.g. "scan list", "host detection", "act-key create").
+    action_bucket is the bucket label used to colour and group the entry
+    (e.g. "list", "create", "delete").
+    """
+    out: list[tuple[str, str]] = []
+    for c in (t.registered_commands or []):
+        if isinstance(c.name, str):
+            cname = c.name
+        elif c.callback is not None:
+            cname = c.callback.__name__.replace("_", "-")
+        else:
+            continue
+        full = f"{prefix} {cname}".strip()
+        # Pick the bucket from the final token; rewrites map oddities into
+        # canonical buckets (e.g. scan-again → run, owasp-zap → import).
+        bucket = _BUCKET_REWRITES.get(cname, cname)
+        out.append((full, bucket))
+    for g in (t.registered_groups or []):
+        sub = g.typer_instance
+        if sub is None:
+            continue
+        gname = sub.info.name if sub.info and isinstance(sub.info.name, str) else g.name
+        if not isinstance(gname, str):
+            continue
+        out.extend(_walk_module(sub, f"{prefix} {gname}".strip()))
+    return out
+
+
+def _bucket_ops(ops: list[tuple[str, str]]) -> list[tuple[str, str]]:
+    """Group commands by their action word into [(label, "cmd1 · cmd2"), ...]."""
+    buckets: dict[str, list[str]] = {}
+    for op, action in ops:
+        buckets.setdefault(action, []).append(op)
+    # Order: list-style first, then mutate, then delete. Falls back to alpha.
+    order = [
+        "info", "list", "count", "get", "status",
+        "create", "add", "import", "patch", "update", "activate", "enable", "sync",
+        "launch", "run", "fetch", "scan", "scan-again",
+        "export", "download",
+        "deactivate", "disable", "cancel", "purge", "remove", "delete",
+    ]
+    out: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    for label in order:
+        if label in buckets:
+            out.append((label, " · ".join(buckets[label])))
+            seen.add(label)
+    for label in sorted(buckets):
+        if label not in seen:
+            out.append((label, " · ".join(buckets[label])))
+    return out
+
+
+def _module_table(
+    color: str,
+    modules: list[tuple[str, str, list[tuple[str, str]]]],
+) -> Table:
+    """Build a table for one module group.
+
+    Each module gets a bold header row followed by indented operation rows,
+    one row per action type, color-coded by type.
+    """
+    t = Table(box=None, show_header=False, show_edge=False, padding=(0, 1), pad_edge=True)
+    t.add_column("cmd",   min_width=12, no_wrap=True)
+    t.add_column("label", min_width=10, no_wrap=True)
+    t.add_column("cmds",  no_wrap=False)
+
+    for i, (cmd, name, ops) in enumerate(modules):
+        if i:
+            t.add_row("", "", "")  # blank spacer between modules
+        # Module header row
+        t.add_row(
+            f"[bold {color}]{cmd}[/bold {color}]",
+            f"[bold white]{name}[/bold white]",
+            "",
+        )
+        # One row per operation bucket
+        for label, cmds in ops:
+            style = _OP_STYLES.get(label, "bold white")
+            t.add_row(
+                "",
+                f"  [{style}]{label}[/{style}]",
+                f"[dim]{cmds}[/dim]",
+            )
+    return t
+
+
+@app.command("help", rich_help_panel=_PANEL_CFG)
+def help_cmd(ctx: typer.Context) -> None:
+    """Show detailed help: modules grouped by domain, with color-coded operations.
+
+    The list is generated by introspecting the live Typer app, so it stays in
+    sync with the actual registered commands automatically.
+    """
+    _print_banner()
+
+    # Collect every module's commands by walking the live Typer app
+    by_module: dict[str, list[tuple[str, str]]] = {}
+    for grp in (app.registered_groups or []):
+        sub = grp.typer_instance
+        if sub is None:
+            continue
+        mod_key = sub.info.name if sub.info else grp.name
+        if not isinstance(mod_key, str) or mod_key not in _MODULE_DISPLAY:
+            continue
+        by_module[mod_key] = _walk_module(sub)
+
+    # Group modules by their domain section
+    by_domain: dict[str, list[tuple[str, str, list[tuple[str, str]]]]] = {}
+    for mod_key, ops in by_module.items():
+        color, title, domain = _MODULE_DISPLAY[mod_key]
+        by_domain.setdefault(domain, []).append((mod_key, title, _bucket_ops(ops)))
+
+    # Render each domain section in the documented order
+    for i, domain in enumerate(_DOMAIN_ORDER):
+        if domain not in by_domain:
+            continue
+        if i:
+            _err.print()
+        rule_color = _DOMAIN_RULE_COLORS[domain]
+        _err.print(Rule(
+            f"[bold {rule_color}]  {domain}  [/bold {rule_color}]",
+            style=rule_color,
+        ))
+        # All entries in a domain share the same accent colour
+        _err.print(_module_table(rule_color, by_domain[domain]))
+
+    # ── Output formats ──────────────────────────────────────────────────────
+    _err.print()
+    _err.print(Rule("[bold]  Output Formats  [/bold]", style="dim"))
+    fmt = Table(
+        box=box.SIMPLE_HEAD, show_header=True, border_style="dim",
+        show_edge=False, padding=(0, 1), header_style="bold",
+    )
+    fmt.add_column("Flag / Context",            style="cyan",  min_width=28)
+    fmt.add_column("Behaviour",                 style="white")
+    fmt.add_row("qualys-cli mode",
+                "Show or change the persistent output mode for this profile")
+    fmt.add_row("qualys-cli mode interactive",
+                "Default: rich tables · colours · spinners")
+    fmt.add_row("qualys-cli mode agentic",
+                "Clean JSON · no decoration — for scripts and AI agents")
+    fmt.add_row("--format json",                "One-shot: full JSON to stdout")
+    fmt.add_row("--format jsonl",               "One JSON object per line (NDJSON)")
+    fmt.add_row("--format yaml",                "Full YAML to stdout")
+    fmt.add_row("--format table",               "Rich table (forced)")
+    fmt.add_row("--output-file out.json",
+                "Dump full data to file (JSON or YAML by extension)")
+    fmt.add_row("--limit 0",                    "Remove 25-row cap — return all rows")
+    fmt.add_row("--profile NAME",               "Use a named credential profile")
+    fmt.add_row("-v / -vv",
+                "Log requests and response sizes (secrets never logged)")
+    _err.print(fmt)
+
+    # ── Quick examples ──────────────────────────────────────────────────────
+    _err.print()
+    _err.print(Rule("[bold]  Quick Examples  [/bold]", style="dim"))
+    ex = Table(
+        box=None, show_header=False, show_edge=False, padding=(0, 1),
+    )
+    ex.add_column("desc",  style="dim",  min_width=30)
+    ex.add_column("cmd",   style="cyan")
+
+    examples = [
+        ("First-time setup",                   "qualys-cli configure"),
+        ("VM host detections",                  "qualys-cli vm host detection --ips 10.0.0.0/24"),
+        ("Launch a VM scan",
+         'qualys-cli vm scan launch --title "Weekly" --ip 10.0.1.0/24 --option-id 123'),
+        ("List patch jobs (JSON)",              "qualys-cli pm job list --format json"),
+        ("All CSAM assets, no row cap",         "qualys-cli csam asset list --limit 0"),
+        ("Pipe-friendly output",                "qualys-cli csam asset list | jq '.[].name'"),
+        ("TotalCloud AWS connectors",           "qualys-cli tc connector list --provider AWS"),
+        ("Container images with vulns",
+         'qualys-cli cs image list --filter "vulns.severity5Count:>0"'),
+        ("Cloud agent list",                    "qualys-cli ca agent list"),
+        ("Subscription info",                   "qualys-cli sub info"),
+    ]
+    for desc, cmd in examples:
+        ex.add_row(desc, cmd)
+    _err.print(ex)
+    _err.print()
+
+
+def _save_and_show(
+    profile: str,
+    username: str,
+    password: str,
+    output_mode: str = "interactive",
+    continuing: bool = False,
+) -> None:
+    """Save credentials and display a confirmation panel with detected platform info."""
+    from .platforms import detect as _detect_platform
+
+    in_keyring = _cfg.save_profile(
+        profile, username=username, password=password, output_mode=output_mode,
+    )
+
+    try:
+        plat = _detect_platform(username)
+        api_url = plat.api_url
+        gateway_url = plat.gateway_url
+        platform_name = plat.name
+    except ValueError:
+        api_url = gateway_url = "[dim]unknown — set QUALYS_URL to override[/dim]"
+        platform_name = "unknown"
+
+    mode_label = (
+        "[cyan]agentic[/cyan] (JSON, no decoration)"
+        if output_mode == "agentic"
+        else "[green]interactive[/green] (rich tables)"
+    )
+
+    t = Table(
+        box=box.SIMPLE_HEAD, show_header=False, border_style="dim",
+        show_edge=False, padding=(0, 1),
+    )
+    t.add_column("key", style="dim")
+    t.add_column("val")
+    t.add_row("Profile",     f"[bold]{profile}[/bold]")
+    t.add_row("Platform",    f"[cyan]{platform_name}[/cyan]")
+    t.add_row("API URL",     api_url)
+    t.add_row("Gateway URL", gateway_url)
+    t.add_row("Username",    username)
+    t.add_row(
+        "Password",
+        "[dim]stored in system keyring[/dim]" if in_keyring
+        else "[bold yellow]WARNING[/bold yellow] [dim]keyring unavailable — "
+             "stored in plaintext in config.toml[/dim]",
+    )
+    t.add_row("Output mode", mode_label)
+
+    suffix = " Continuing with your command…" if continuing else ""
+    _err.print()
+    _err.print(Panel(
+        t,
+        title="[bold green] Profile saved [/bold green]",
+        subtitle=f"[dim]{suffix}[/dim]" if suffix else None,
+        border_style="green",
+        expand=False,
+    ))
+    _err.print()
+
+
+@app.command("configure", rich_help_panel=_PANEL_CFG)
+def configure(
+    profile: str = typer.Option(
+        "default", "--profile", "-p", help="Profile name to create/update"
+    ),
+    username: str | None = typer.Option(None, "--username", "-u"),
+    password: str | None = typer.Option(
+        None, "--password",
+        help="Stored in system keyring. WARNING: passing a secret as a CLI "
+             "flag can leak via shell history or `ps`; prefer the "
+             "interactive prompt or the QUALYS_PASSWORD env var.",
+    ),
+    output_mode: str | None = typer.Option(
+        None, "--output-mode",
+        help="interactive (rich tables) or agentic (JSON, no decoration)",
+    ),
+) -> None:
+    """Create or update a named credential profile.
+
+    Platform URLs are auto-detected from your username
+    (see https://www.qualys.com/platform-identification).
+    Override with [dim]QUALYS_URL[/dim] / [dim]QUALYS_GATEWAY_URL[/dim] env vars if needed.
+    """
+    if not username:
+        username = typer.prompt("Username")
+    if password and _err.is_terminal:
+        _err.print(
+            "  [yellow]⚠[/yellow] [dim]--password was passed on the command line — it may be "
+            "visible in shell history or `ps`. Prefer the interactive prompt or "
+            "QUALYS_PASSWORD.[/dim]"
+        )
+    if not password:
+        password = typer.prompt("Password", hide_input=True, confirmation_prompt=True)
+    if not output_mode:
+        raw = typer.prompt(
+            "Output mode",
+            default="interactive",
+            prompt_suffix=" [interactive/agentic]: ",
+            show_default=False,
+        ).strip().lower()
+        output_mode = raw if raw in ("interactive", "agentic") else "interactive"
+
+    _save_and_show(profile, username, password, output_mode=output_mode)
+
+
+@app.command("mode", rich_help_panel=_PANEL_CFG)
+def mode_cmd(
+    ctx: typer.Context,
+    new_mode: str | None = typer.Argument(
+        None, help="Set mode: [bold]interactive[/bold] or [bold]agentic[/bold]"
+    ),
+    profile: str = typer.Option(
+        "default", "--profile", "-p", help="Profile to update"
+    ),
+) -> None:
+    """Show or change the output mode for a profile.
+
+    [bold]interactive[/bold]  Rich tables, colours, spinners — for human use.\n
+    [bold]agentic[/bold]      Plain JSON, no decoration — for scripts and AI agents.
+
+    Examples:\n
+      qualys-cli mode\n
+      qualys-cli mode agentic\n
+      qualys-cli mode interactive
+    """
+    _VALID = ("interactive", "agentic")
+
+    if new_mode is None:
+        # Show current mode
+        try:
+            p = _cfg.get_profile(profile)
+            current = p.output_mode
+        except Exception:
+            current = "interactive"
+        _err.print()
+        _err.print(
+            f"  Profile [bold]{profile}[/bold] is in "
+            f"[bold cyan]{current}[/bold cyan] mode."
+        )
+        other = "agentic" if current == "interactive" else "interactive"
+        _err.print(
+            f"  Run [bold]qualys-cli mode {other}[/bold] to switch."
+        )
+        _err.print()
+        return
+
+    new_mode = new_mode.lower()
+    if new_mode not in _VALID:
+        _err.print(
+            f"  [bold red]Invalid mode[/bold red] [bold]{new_mode!r}[/bold]. "
+            f"Choose: {' | '.join(_VALID)}"
+        )
+        raise typer.Exit(1)
+
+    _cfg.set_output_mode(profile, new_mode)
+    label = (
+        "[green]interactive[/green] (rich tables)"
+        if new_mode == "interactive"
+        else "[cyan]agentic[/cyan] (JSON, no decoration)"
+    )
+    _err.print()
+    _err.print(
+        f"  [bold green]✓[/bold green]  Profile [bold]{profile}[/bold] "
+        f"→ output mode set to {label}."
+    )
+    _err.print(
+        "  [dim]Takes effect on the next command.[/dim]"
+    )
+    _err.print()
+
+
+@app.command("profiles", rich_help_panel=_PANEL_CFG)
+def profiles() -> None:
+    """List configured credential profiles."""
+    from pathlib import Path
+    config_file = Path.home() / ".config" / "qualys-cli" / "config.toml"
+    if not config_file.exists():
+        _err.print(Panel(
+            "No profiles configured.\n\n"
+            "Run [bold cyan]qualys-cli configure[/bold cyan] to get started.",
+            title="[bold yellow] No profiles [/bold yellow]",
+            border_style="yellow",
+            expand=False,
+        ))
+        raise typer.Exit(1)
+
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    data = tomllib.loads(config_file.read_text())
+    profiles_data = data.get("profiles", {})
+    if not profiles_data:
+        _err.print("[dim]No profiles configured.[/dim]")
+        raise typer.Exit(1)
+
+    from .platforms import detect as _detect_platform
+
+    t = Table(
+        box=box.SIMPLE_HEAD, header_style="bold", border_style="dim",
+        show_edge=False, padding=(0, 1),
+    )
+    t.add_column("Profile")
+    t.add_column("Platform")
+    t.add_column("Username")
+    t.add_column("API URL")
+    for name, prof in profiles_data.items():
+        uname = prof.get("username", "")
+        try:
+            plat = _detect_platform(uname)
+            platform_name = f"[cyan]{plat.name}[/cyan]"
+            api_url = prof.get("url") or plat.api_url
+        except ValueError:
+            platform_name = "[dim]unknown[/dim]"
+            api_url = prof.get("url", "[dim]—[/dim]")
+        t.add_row(f"[bold]{name}[/bold]", platform_name, uname or "[dim]—[/dim]", api_url)
+
+    _err.print()
+    _err.print(t)
+    _err.print()
+
+
+# ---------------------------------------------------------------------------
+# Entry point with global exception handling
+# ---------------------------------------------------------------------------
+
+# Map APIError subclasses to (panel title, machine "type" tag) used by _show_error.
+_ERROR_TITLES: dict[str, tuple[str, str]] = {
+    "AuthError":      ("Authentication Failed",   "auth_error"),
+    "NotFoundError":  ("Not Found",                "not_found"),
+    "RateLimitError": ("Rate Limited",             "rate_limit"),
+    "ServerError":    ("Server Error",             "server_error"),
+    "TimeoutError":   ("Timeout",                  "timeout"),
+    "NetworkError":   ("Network Error",            "network_error"),
+    "APIError":       ("API Error",                "api_error"),
+}
+
+
+def _show_error(exc: Exception) -> int:
+    """Render *exc* and return the exit code the process should use."""
+    import json as _json
+    import sys as _sys
+
+    from .client import APIError
+
+    if isinstance(exc, APIError):
+        kind = type(exc).__name__
+        title, type_tag = _ERROR_TITLES.get(kind, _ERROR_TITLES["APIError"])
+        exit_code = exc.exit_code
+        # Record the failure in the audit log so reviewers can see *why* a
+        # command exited non-zero, not just that it did.
+        _audit.log_error(kind, exc.message, status=exc.status or None)
+
+        if not _err.is_terminal:
+            payload = {
+                "error": exc.message,
+                "status": exc.status,
+                "type": type_tag,
+                "correlation": exc.correlation or _audit.CORRELATION_ID,
+            }
+            if exc.request_id:
+                payload["request_id"] = exc.request_id
+            print(_json.dumps(payload), file=_sys.stderr)
+            return exit_code
+
+        # Build a friendly panel: the API message, then a hint, then the
+        # correlation/request IDs so users can find this run in the audit log.
+        body = f"[white]{exc.message}[/white]"
+        if exc.hint:
+            body += f"\n\n[dim]{exc.hint}[/dim]"
+        ids: list[str] = []
+        if exc.correlation or _audit.CORRELATION_ID:
+            ids.append(f"correlation [bold]{exc.correlation or _audit.CORRELATION_ID}[/bold]")
+        if exc.request_id:
+            ids.append(f"request [bold]{exc.request_id}[/bold]")
+        if ids:
+            body += f"\n[dim]({' · '.join(ids)})[/dim]"
+        status_label = f"HTTP {exc.status}" if exc.status else "Network"
+        _err.print(Panel(
+            body,
+            title=f"[bold red] {status_label} — {title} [/bold red]",
+            border_style="red",
+            padding=(0, 1),
+            expand=False,
+        ))
+        return exit_code
+
+    if isinstance(exc, ValueError):
+        _audit.log_error("ConfigurationError", str(exc))
+        if not _err.is_terminal:
+            print(_json.dumps({
+                "error": str(exc),
+                "type": "configuration_error",
+                "correlation": _audit.CORRELATION_ID,
+            }), file=_sys.stderr)
+            return 2
+        _err.print(Panel(
+            f"[white]{exc}[/white]\n\n"
+            "[dim]Run [cyan]qualys-cli configure[/cyan] to set up credentials, or set "
+            "the QUALYS_USERNAME / QUALYS_PASSWORD env vars.[/dim]",
+            title="[bold red] Configuration Error [/bold red]",
+            border_style="red",
+            padding=(0, 1),
+            expand=False,
+        ))
+        return 2
+
+    # Unknown / unexpected error — still log it so it shows up in audit.
+    _audit.log_error(type(exc).__name__, str(exc))
+    if not _err.is_terminal:
+        print(_json.dumps({
+            "error": str(exc),
+            "type": "error",
+            "correlation": _audit.CORRELATION_ID,
+        }), file=_sys.stderr)
+        return 1
+    _err.print(Panel(
+        f"[white]{exc}[/white]\n\n"
+        f"[dim]correlation [bold]{_audit.CORRELATION_ID}[/bold] — share this ID "
+        "if you file a bug report.[/dim]",
+        title="[bold red] Error [/bold red]",
+        border_style="red",
+        padding=(0, 1),
+        expand=False,
+    ))
+    return 1
+
+
+def _build_post_options() -> list[Any]:
+    """Construct the cross-cutting post-processing options
+    (``--where`` / ``--columns`` / ``--sort`` / ``--sort-by`` / ``--sort-desc``
+    / ``--jq``) used by the formatter.
+
+    Each option is registered with ``expose_value=False`` so it never reaches
+    the underlying Typer command function — instead a callback stashes the
+    parsed value into a ContextVar that the output formatter reads at render
+    time. This avoids threading these flags through ~200 command signatures.
+    """
+    import click as _click
+
+    from . import formatters as _fmt
+
+    def _cb(name: str) -> Any:
+        def _set(_ctx: _click.Context, _param: _click.Parameter, value: Any) -> Any:
+            if value is not None:
+                _fmt.set_post_process_opt(name, value)
+            return value
+        return _set
+
+    return [
+        _click.Option(
+            ["--where"], type=str, default=None, expose_value=False,
+            callback=_cb("where"),
+            help="Filter rows (ops: =, !=, ~, >=, >, <=, <). See docs/usage.html.",
+        ),
+        _click.Option(
+            ["--columns"], type=str, default=None, expose_value=False,
+            callback=_cb("columns"),
+            help="Override default table columns (comma-separated)",
+        ),
+        _click.Option(
+            ["--sort"], type=str, default=None, expose_value=False,
+            callback=_cb("sort"),
+            help="Sort rows by field[:asc|:desc]",
+        ),
+        _click.Option(
+            ["--sort-by"], type=str, default=None, expose_value=False,
+            callback=_cb("sort_by"),
+            help="Sort rows by FIELD (combine with --sort-desc for descending)",
+        ),
+        _click.Option(
+            ["--sort-desc"], is_flag=True, default=False, expose_value=False,
+            callback=_cb("sort_desc"),
+            help="Reverse sort order when using --sort-by",
+        ),
+        _click.Option(
+            ["--jq"], type=str, default=None, expose_value=False,
+            callback=_cb("jq"),
+            help="jq-lite query against the parsed payload, e.g. '.foo[].id'",
+        ),
+    ]
+
+
+def _inject_post_options_into(root_cmd: Any) -> Any:
+    """Walk a Click command tree and append the post-processing options to
+    every leaf (idempotent — skips options already present).
+
+    Collision is checked against the user-facing flag strings (``--sort``,
+    ``--where``, …) rather than the click ``.name`` attribute, because Typer
+    derives the click name from the Python parameter name, not from the
+    ``--flag`` declaration. A command that declared ``sort: str = typer.Option(
+    None, "--server-sort")`` would otherwise still shadow our global
+    ``--sort`` despite the rename.
+    """
+    import click as _click
+
+    post_opts = _build_post_options()
+
+    def _walk(cmd: _click.Command) -> None:
+        if isinstance(cmd, _click.Group):
+            for sub in cmd.commands.values():
+                _walk(sub)
+            return
+        existing_flags: set[str] = set()
+        for p in cmd.params:
+            existing_flags.update(getattr(p, "opts", ()) or ())
+        for opt in post_opts:
+            if not any(decl in existing_flags for decl in opt.opts):
+                cmd.params.append(opt)
+
+    _walk(root_cmd)
+    return root_cmd
+
+
+# Patch ``typer.main.get_command`` so that any caller — the qualys-cli binary
+# via main(), Typer's CliRunner used by the test suite, or anything that imports
+# ``app`` and invokes it — sees the injected options. Without this, options
+# only attach when main() is the entry point and tests / MCP / embedded use
+# would lose them.
+#
+# Scope / lifetime caveats:
+#   - The patch is process-lifetime; there is no unpatch hook. We guard with
+#     ``typer_instance is app`` so unrelated Typer apps in the same process
+#     are not mutated.
+#   - If qualys-cli is ever imported as a library alongside other Typer apps,
+#     the patched function is still on ``typer.main`` — those other apps just
+#     fall through to the original behaviour via the identity check.
+#   - typer.testing's late-binding alias is also patched below for the same
+#     reason CliRunner.invoke would otherwise miss the injection.
+_original_get_command = typer.main.get_command
+
+
+def _patched_get_command(typer_instance: typer.Typer) -> Any:
+    cmd = _original_get_command(typer_instance)
+    if typer_instance is app:
+        _inject_post_options_into(cmd)
+    return cmd
+
+
+typer.main.get_command = _patched_get_command
+
+# typer.testing rebinds get_command at *its* module-load time via
+# ``from typer.main import get_command as _get_command``, so if a test module
+# imported typer.testing before this module, its alias still points to the
+# original. Patch the alias directly when the testing module is loaded so
+# CliRunner.invoke(app, ...) also sees the injected options.
+try:
+    import typer.testing as _typer_testing
+    _typer_testing._get_command = _patched_get_command  # type: ignore[attr-defined]
+except ImportError:
+    pass
+
+
+def main() -> None:
+    import contextlib as _ctx
+
+    # Top-level Ctrl-C handler: ensures the spinner / audit state is flushed
+    # before the process exits even when interrupted between calls.
+    def _sigint(_signum: int, _frame: object) -> None:
+        raise KeyboardInterrupt()
+    with _ctx.suppress(ValueError, OSError):
+        _signal.signal(_signal.SIGINT, _sigint)
+
+    # Initialise audit early so even argument-parsing errors are captured.
+    _audit.init()
+    version = _qualys_cli_version()
+    started = _audit.log_command_start(sys.argv, version)
+    exit_code = 0
+    # Clear any leftover formatter post-processing state. Today every CLI
+    # invocation is a fresh process so this is paranoia; if a future caller
+    # ever invokes main() twice in-process (e.g. embedded harness) the reset
+    # guarantees option values can't bleed between runs.
+    from . import formatters as _fmt
+    _fmt.reset_post_process_opts()
+    try:
+        app(standalone_mode=False)
+    except typer.Exit as e:
+        exit_code = int(e.exit_code or 0)
+        _audit.log_command_end(started, exit_code, version)
+        raise SystemExit(exit_code)
+    except typer.Abort:
+        exit_code = 130
+        _err.print("\n  [yellow]Aborted.[/yellow]\n")
+        _audit.log_command_end(started, exit_code, version)
+        raise SystemExit(exit_code)
+    except KeyboardInterrupt:
+        exit_code = 130
+        _err.print("\n  [yellow]Interrupted.[/yellow]\n")
+        _audit.log_command_end(started, exit_code, version)
+        raise SystemExit(exit_code)
+    except SystemExit as se:
+        exit_code = int(se.code or 0) if se.code is not None else 0
+        _audit.log_command_end(started, exit_code, version)
+        raise
+    except Exception as exc:
+        # Special-case --dry-run: it's not an error; exit cleanly with 0.
+        from .client import DryRunExit as _DryRunExit
+        if isinstance(exc, _DryRunExit):
+            _audit.log_command_end(started, 0, version)
+            raise SystemExit(0)
+        exit_code = _show_error(exc)
+        _audit.log_command_end(started, exit_code, version)
+        raise SystemExit(exit_code)
+    else:
+        _audit.log_command_end(started, exit_code, version)