agentrust-py 0.0.3__py3-none-any.whl

agentrust_sdk/cli.py

@@ -0,0 +1,736 @@
+"""
+agentrust CLI — frictionless onboarding and ops commands.
+
+Entry point: agentrust (installed via pyproject.toml [project.scripts])
+
+Commands:
+  agentrust init           Onboard project: issue free API key, write config
+  agentrust status         Show current tier, org, agent count
+  agentrust policy sync    Pull latest policies from control plane
+  agentrust policy push    Publish a new policy pack version
+  agentrust policy list    List loaded policy packs and versions
+  agentrust audit tail     Stream local SQLite audit log
+  agentrust agents list    Show registered agents and their scorecards
+  agentrust upgrade        Open upgrade page for current org
+  agentrust whoami         Show current auth identity and tier
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import webbrowser
+from pathlib import Path
+
+_SIGNUP_URL = "https://agentrust.io/signup"
+_UPGRADE_URL = "https://agentrust.io/upgrade"
+_AUTH_URL = "https://agentrust.io/auth/cli"
+_DOCS_URL = "https://docs.agentrust.io"
+
+TIER_COLOURS = {
+    "oss": "\033[32m",       # green
+    "free": "\033[36m",      # cyan
+    "developer": "\033[34m", # blue
+    "team": "\033[35m",      # magenta
+    "enterprise": "\033[33m",# yellow
+}
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+
+
+def _colour(text: str, colour: str) -> str:
+    return f"{colour}{text}{RESET}" if sys.stdout.isatty() else text
+
+
+def _print_banner() -> None:
+    print(f"\n{BOLD}AgentTrust Edge{RESET}  — the AI Agent Harness\n")
+
+
+def _print_tier_info(tier: str, org_id: str, source: str) -> None:
+    col = TIER_COLOURS.get(tier, "")
+    print(f"  Tier   : {_colour(tier.upper(), col + BOLD)}")
+    print(f"  Org    : {org_id}")
+    print(f"  Source : {DIM}{source}{RESET}")
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def cmd_init(args: list[str]) -> int:
+    """Interactive project onboarding wizard."""
+    from .auth import save_key_to_config, read_config, _GLOBAL_CONFIG
+
+    _print_banner()
+    print("Welcome to AgentTrust! Let's get you set up.\n")
+
+    # Check if already configured
+    existing = read_config("global")
+    if existing.get("api_key"):
+        print(f"  ✓ Already configured (tier: {existing.get('tier', 'unknown')})")
+        print(f"  Config: {_GLOBAL_CONFIG}")
+        print("\n  Run `agentrust status` to verify.\n")
+        return 0
+
+    # Detect if --local flag is set (offline/air-gap mode)
+    local_mode = "--local" in args
+
+    if local_mode:
+        print("  Local mode: generating offline API key (Free tier)\n")
+        import secrets
+        local_key = f"at_local_{secrets.token_hex(16)}"
+        path = save_key_to_config(local_key, scope="global")
+        print(f"  ✓ Local key written to: {path}")
+        print(f"  ✓ Tier: FREE (local mode)")
+        print(f"\n  {DIM}Note: Central dashboard, policy sync, and analytics")
+        print(f"  require a cloud API key. Run `agentrust init` to upgrade.{RESET}\n")
+        return 0
+
+    # Cloud auth flow
+    print("  Opening AgentTrust signup in your browser...")
+    print(f"  {DIM}URL: {_AUTH_URL}{RESET}\n")
+
+    try:
+        webbrowser.open(_AUTH_URL)
+    except Exception:
+        print(f"  Could not open browser. Visit: {_AUTH_URL}\n")
+
+    print("  Paste your API key here (or press Enter to skip):")
+    try:
+        key = input("  API key: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print("\n  Skipped. Run `agentrust init` again to complete setup.")
+        return 0
+
+    if not key:
+        print(f"\n  Skipped. Get your free key at: {_SIGNUP_URL}")
+        print("  Then run: agentrust init\n")
+        return 0
+
+    path = save_key_to_config(key, scope="global")
+
+    # Read back tier info
+    from .auth import resolve_key
+    info = resolve_key(key)
+
+    print(f"\n  ✓ API key saved to: {path}")
+    _print_tier_info(info.tier.value, info.org_id, "config")
+
+    # Detect framework
+    from .decorator import _detect_framework
+    fw = _detect_framework()
+    print(f"\n  ✓ Framework detected: {fw}")
+    print(f"\n  You're ready! Add to your agent:\n")
+    print(f"    {BOLD}from agentrust import harness{RESET}\n")
+    print(f"    {BOLD}@harness{RESET}")
+    print(f"    def my_agent(user, input):")
+    print(f"        return {{...}}\n")
+    print(f"  Docs: {_DOCS_URL}\n")
+    return 0
+
+
+def cmd_whoami(args: list[str]) -> int:
+    """Show current auth identity and tier."""
+    from .auth import resolve_key
+    info = resolve_key()
+
+    _print_banner()
+    if info.source == "none":
+        print("  Not authenticated (OSS mode — schema validation only)")
+        print(f"\n  Get a free key: {_SIGNUP_URL}")
+        print("  Then run: agentrust init\n")
+        return 0
+
+    _print_tier_info(info.tier.value, info.org_id, info.source)
+    print()
+
+    # Show what's available vs locked
+    from .tiers import Capability, is_allowed, UPGRADE_MESSAGES
+    groups = {
+        "Validation": [Capability.SCHEMA_VALIDATION, Capability.EVIDENCE_VALIDATION,
+                       Capability.CONTRADICTION_DETECTION, Capability.CONSISTENCY_CHECK],
+        "Risk & Confidence": [Capability.CONFIDENCE_ENGINE, Capability.RISK_SCORING,
+                              Capability.HISTORICAL_RELIABILITY],
+        "Policy": [Capability.BUILTIN_POLICY_PACKS, Capability.CUSTOM_POLICIES, Capability.POLICY_SYNC],
+        "Audit": [Capability.LOCAL_AUDIT, Capability.CENTRAL_AUDIT, Capability.ANALYTICS],
+        "Operations": [Capability.REVIEW_QUEUE, Capability.ALERT_ENGINE, Capability.WEBHOOKS],
+        "Multi-Agent": [Capability.TRUST_CHAIN, Capability.RATE_LIMITER],
+        "Integrations": [Capability.LANGGRAPH_ADAPTER, Capability.CREWAI_ADAPTER, Capability.SELF_HOSTED],
+    }
+
+    for group, caps in groups.items():
+        print(f"  {BOLD}{group}{RESET}")
+        for cap in caps:
+            allowed = is_allowed(cap, info.tier)
+            icon = "✓" if allowed else "✗"
+            colour = "\033[32m" if allowed else "\033[31m"
+            print(f"    {_colour(icon, colour)} {cap.value.replace('_', ' ')}")
+        print()
+
+    if info.tier.value in ("oss", "free", "developer"):
+        print(f"  Upgrade: {_UPGRADE_URL}\n")
+    return 0
+
+
+def cmd_status(args: list[str]) -> int:
+    """Show config status without making API calls."""
+    from .auth import resolve_key, _GLOBAL_CONFIG, _project_config
+    info = resolve_key()
+
+    _print_banner()
+    print("  Config status\n")
+    _print_tier_info(info.tier.value, info.org_id, info.source)
+
+    proj = _project_config()
+    print(f"\n  Global config : {_GLOBAL_CONFIG}")
+    print(f"  Project config: {proj or '(none)'}")
+    print(f"  AGENTRUST_KEY : {'set' if os.environ.get('AGENTRUST_KEY') else 'not set'}")
+    print()
+    return 0
+
+
+def cmd_policy(args: list[str]) -> int:
+    """Policy subcommands: sync, push, list."""
+    from .auth import resolve_key
+    from .tiers import Capability, is_allowed
+
+    info = resolve_key()
+    sub = args[0] if args else "list"
+
+    if sub == "sync":
+        if not is_allowed(Capability.POLICY_SYNC, info.tier):
+            print(f"\n  ✗ Policy sync requires Team tier ($149/mo)")
+            print(f"  Upgrade: {_UPGRADE_URL}\n")
+            return 1
+        print("\n  Syncing policies from control plane...")
+        print("  (Connect to control plane — `agentrust init` first)\n")
+        return 0
+
+    if sub == "push":
+        if not is_allowed(Capability.CUSTOM_POLICIES, info.tier):
+            print(f"\n  ✗ Custom policies require Team tier ($149/mo)")
+            print(f"  Upgrade: {_UPGRADE_URL}\n")
+            return 1
+        file_arg = args[1] if len(args) > 1 else None
+        if not file_arg:
+            print("\n  Usage: agentrust policy push <policy.yaml> [--env production]\n")
+            return 1
+        print(f"\n  Pushing policy: {file_arg}")
+        print("  (Connect to control plane — `agentrust init` first)\n")
+        return 0
+
+    if sub == "list":
+        # Works on all tiers — shows local config dir
+        config_dir = Path.home() / ".agentrust" / "policies"
+        if config_dir.exists():
+            packs = list(config_dir.glob("*.yaml"))
+            print(f"\n  Policy packs in {config_dir}:\n")
+            for p in packs:
+                print(f"    · {p.name}")
+            if not packs:
+                print("    (none — run `agentrust policy sync` to pull from control plane)")
+        else:
+            print(f"\n  No local policy cache found at {config_dir}")
+            print("  Run `agentrust policy sync` to pull policies.\n")
+        return 0
+
+    if sub == "pack":
+        return _cmd_policy_pack(args[1:])
+
+    print(f"\n  Unknown policy command: {sub}")
+    print("  Usage: agentrust policy [sync|push|list|pack]\n")
+    return 1
+
+
+def _cmd_policy_pack(args: list[str]) -> int:
+    """Offline policy pack management for air-gapped deployments.
+
+    Subcommands:
+      agentrust policy pack list                     List installed packs
+      agentrust policy pack bundle <outdir>          Bundle all packs into outdir/
+      agentrust policy pack install <path>           Install packs from a directory or tarball
+      agentrust policy pack export <pack> <outfile>  Export a single pack to a file
+    """
+    import shutil
+    import tarfile
+
+    PACK_DIR = Path.home() / ".agentrust" / "policy_packs"
+    PACK_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Also look for built-in packs relative to the SDK
+    _SDK_PACK_DIR = Path(__file__).parent.parent.parent / "agentrust-edge" / "gateway" / "config" / "policy_packs"
+
+    sub = args[0] if args else "list"
+
+    if sub == "list":
+        all_dirs = [PACK_DIR]
+        if _SDK_PACK_DIR.exists():
+            all_dirs.append(_SDK_PACK_DIR)
+        packs: list[str] = []
+        for d in all_dirs:
+            packs.extend(p.stem for p in sorted(d.glob("*.yaml")))
+        print(f"\n  Installed policy packs ({len(packs)}):\n")
+        for name in sorted(set(packs)):
+            print(f"    · {name}")
+        if not packs:
+            print("    (none)")
+        print()
+        return 0
+
+    if sub == "bundle":
+        outdir = Path(args[1]) if len(args) > 1 else Path("agentrust-policy-bundle")
+        outdir.mkdir(parents=True, exist_ok=True)
+        sources = [PACK_DIR]
+        if _SDK_PACK_DIR.exists():
+            sources.append(_SDK_PACK_DIR)
+        count = 0
+        for src in sources:
+            for p in src.glob("*.yaml"):
+                shutil.copy2(p, outdir / p.name)
+                count += 1
+        # Create a tarball as well
+        tar_path = Path(str(outdir) + ".tar.gz")
+        with tarfile.open(tar_path, "w:gz") as tar:
+            tar.add(outdir, arcname=outdir.name)
+        print(f"\n  Bundled {count} policy pack(s) → {outdir}/ and {tar_path}\n")
+        return 0
+
+    if sub == "install":
+        src_path = Path(args[1]) if len(args) > 1 else None
+        if not src_path:
+            print("\n  Usage: agentrust policy pack install <directory-or-tarball>\n")
+            return 1
+        count = 0
+        if src_path.suffix in (".gz", ".tgz") or str(src_path).endswith(".tar.gz"):
+            import tempfile
+            with tempfile.TemporaryDirectory() as tmpdir:
+                with tarfile.open(src_path, "r:gz") as tar:
+                    tar.extractall(tmpdir)
+                for p in Path(tmpdir).rglob("*.yaml"):
+                    shutil.copy2(p, PACK_DIR / p.name)
+                    count += 1
+        elif src_path.is_dir():
+            for p in src_path.glob("*.yaml"):
+                shutil.copy2(p, PACK_DIR / p.name)
+                count += 1
+        elif src_path.suffix == ".yaml":
+            shutil.copy2(src_path, PACK_DIR / src_path.name)
+            count = 1
+        else:
+            print(f"\n  Unsupported format: {src_path}. Expected .yaml, directory, or .tar.gz\n")
+            return 1
+        print(f"\n  Installed {count} policy pack(s) → {PACK_DIR}\n")
+        return 0
+
+    if sub == "export":
+        pack_name = args[1] if len(args) > 1 else None
+        outfile = Path(args[2]) if len(args) > 2 else None
+        if not pack_name or not outfile:
+            print("\n  Usage: agentrust policy pack export <pack-name> <outfile.yaml>\n")
+            return 1
+        sources = [PACK_DIR]
+        if _SDK_PACK_DIR.exists():
+            sources.append(_SDK_PACK_DIR)
+        for src in sources:
+            p = src / f"{pack_name}.yaml"
+            if p.exists():
+                shutil.copy2(p, outfile)
+                print(f"\n  Exported {p} → {outfile}\n")
+                return 0
+        print(f"\n  Pack '{pack_name}' not found. Run: agentrust policy pack list\n")
+        return 1
+
+    print(f"\n  Unknown pack subcommand: {sub}")
+    print("  Usage: agentrust policy pack [list|bundle|install|export]\n")
+    return 1
+
+
+def cmd_audit(args: list[str]) -> int:
+    """Tail the local SQLite audit log."""
+    from .auth import resolve_key
+    from .tiers import Capability, is_allowed
+
+    info = resolve_key()
+    if not is_allowed(Capability.LOCAL_AUDIT, info.tier):
+        print(f"\n  ✗ Audit log requires Free tier or above.")
+        print(f"  Sign up free: {_SIGNUP_URL}\n")
+        return 1
+
+    db_path = Path.home() / ".agentrust" / "audit.db"
+    if not db_path.exists():
+        print(f"\n  No audit log found at {db_path}")
+        print("  Audit records appear here after your first @harness call.\n")
+        return 0
+
+    try:
+        import sqlite3
+        con = sqlite3.connect(db_path)
+        con.row_factory = sqlite3.Row
+        rows = con.execute(
+            "SELECT envelope_id, agent_id, decision, risk_tier, final_confidence, timestamp "
+            "FROM executions ORDER BY timestamp DESC LIMIT 20"
+        ).fetchall()
+        print(f"\n  Last {len(rows)} executions from {db_path}:\n")
+        print(f"  {'ENVELOPE':<12} {'AGENT':<20} {'DECISION':<12} {'RISK':<10} {'CONF':>6}  TIMESTAMP")
+        print("  " + "─" * 75)
+        for row in rows:
+            eid = str(row["envelope_id"])[:8]
+            print(
+                f"  {eid:<12} {str(row['agent_id']):<20} "
+                f"{str(row['decision']):<12} {str(row['risk_tier']):<10} "
+                f"{float(row['final_confidence'] or 0):>6.1f}  {row['timestamp']}"
+            )
+        print()
+        con.close()
+    except Exception as exc:
+        print(f"\n  Could not read audit log: {exc}\n")
+        return 1
+    return 0
+
+
+def cmd_upgrade(args: list[str]) -> int:
+    """Open upgrade page."""
+    from .auth import resolve_key
+    info = resolve_key()
+    print(f"\n  Current tier: {info.tier.value.upper()}")
+    print(f"  Opening upgrade page: {_UPGRADE_URL}\n")
+    try:
+        webbrowser.open(_UPGRADE_URL)
+    except Exception:
+        print(f"  Visit: {_UPGRADE_URL}\n")
+    return 0
+
+
+def cmd_help(args: list[str]) -> int:
+    _print_banner()
+    print("  Commands:\n")
+    cmds = [
+        ("init",           "Onboard: issue free key, write config"),
+        ("whoami",         "Show tier, org, and capability access"),
+        ("status",         "Show config file locations"),
+        ("policy sync",    "Pull latest policies from control plane  [Team+]"),
+        ("policy push",    "Publish a policy pack version            [Team+]"),
+        ("policy list",    "List locally cached policy packs"),
+        ("audit tail",     "Show recent local audit records          [Free+]"),
+        ("queue replay",   "Replay buffered queue records to gateway"),
+        ("queue status",   "Show count of buffered queue records"),
+        ("export [file]",  "Export local audit records to JSONL file"),
+        ("purge",          "Delete all local audit databases         [--confirm]"),
+        ("disable",        "Show rollback / kill-switch instructions"),
+        ("uninstall",      "Full exit: export + purge + gateway hard-delete  [--delete-from-gateway --tenant-id <id> --confirm]"),
+        ("upgrade",        "Open upgrade page for current org"),
+        ("help",           "Show this help"),
+    ]
+    for cmd, desc in cmds:
+        print(f"    {BOLD}agentrust {cmd:<18}{RESET} {desc}")
+    print(f"\n  Docs: {_DOCS_URL}\n")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def cmd_export(args: list[str]) -> int:
+    """Export all local audit records to a JSON file (rollback/exit story)."""
+    import json as _json
+
+    output_file = args[0] if args else "agentrust_audit_export.jsonl"
+
+    _print_banner()
+    print(f"  Exporting local audit records to: {output_file}\n")
+
+    db_path = Path.home() / ".agentrust" / "audit.db"
+    embedded_db = Path.home() / ".agentrust" / "embedded.db"
+
+    exported = 0
+    with open(output_file, "w") as fh:
+        for db in (db_path, embedded_db):
+            if not db.exists():
+                continue
+            try:
+                import sqlite3
+                con = sqlite3.connect(str(db))
+                con.row_factory = sqlite3.Row
+                rows = con.execute(
+                    "SELECT * FROM executions ORDER BY timestamp ASC"
+                ).fetchall()
+                for row in rows:
+                    fh.write(_json.dumps(dict(row)) + "\n")
+                    exported += 1
+                con.close()
+                print(f"  ✓ Exported {len(rows)} records from {db}")
+            except Exception as exc:
+                print(f"  ✗ Could not read {db}: {exc}")
+
+    if exported == 0:
+        print("  No local records found. Remote records require gateway export.\n")
+        print("  To export from a running gateway:")
+        print("    curl -H 'X-AgentTrust-Token: $KEY' http://localhost:8000/v1/audit/executions\n")
+    else:
+        print(f"\n  ✓ Exported {exported} total records to: {output_file}")
+        print("  You can safely uninstall: pip uninstall agentrust-sdk\n")
+    return 0
+
+
+def cmd_purge(args: list[str]) -> int:
+    """Delete all local audit records (requires --confirm flag)."""
+    if "--confirm" not in args:
+        print("\n  Safety check: this will permanently delete all local audit records.")
+        print("  Re-run with --confirm to proceed:\n")
+        print("    agentrust purge --confirm\n")
+        print("  Tip: run 'agentrust export' first to save a backup.\n")
+        return 1
+
+    _print_banner()
+    print("  Purging local audit records…\n")
+
+    purged = 0
+    for db_name in ("audit.db", "embedded.db", "queue.db"):
+        db_path = Path.home() / ".agentrust" / db_name
+        if db_path.exists():
+            try:
+                db_path.unlink()
+                print(f"  ✓ Deleted {db_path}")
+                purged += 1
+            except Exception as exc:
+                print(f"  ✗ Could not delete {db_path}: {exc}")
+
+    if purged == 0:
+        print("  No local databases found.")
+    else:
+        print(f"\n  ✓ Purged {purged} local database(s).")
+        print("  Remote records in the gateway are not affected by this command.\n")
+        print("  To remove remote records, use the gateway API:")
+        print("    DELETE /v1/audit/executions/{envelope_id}/pii\n")
+    return 0
+
+
+def cmd_disable(args: list[str]) -> int:
+    """Show instructions to disable AgentTrust without code changes (kill-switch)."""
+    _print_banner()
+    print("  Rollback / disable AgentTrust without code changes:\n")
+    print("  Option 1 — Environment variable kill-switch (no redeploy needed):")
+    print(f"    {BOLD}export AGENTRUST_ENABLED=false{RESET}\n")
+    print("  This makes @harness a no-op — your agent functions run unchanged.")
+    print("  The SDK import still works; it just skips all validation.\n")
+    print("  Option 2 — Uninstall:")
+    print(f"    {BOLD}pip uninstall agentrust-sdk{RESET}")
+    print("  Then remove @harness decorators from your code.\n")
+    print("  Option 3 — Export data before uninstalling:")
+    print(f"    {BOLD}agentrust export backup.jsonl{RESET}")
+    print(f"    {BOLD}agentrust purge --confirm{RESET}")
+    print(f"    {BOLD}pip uninstall agentrust-sdk{RESET}\n")
+    print("  Your data in the gateway PostgreSQL is NOT deleted by uninstalling the SDK.")
+    print("  To delete gateway records, contact your gateway operator or use:")
+    print("    DELETE /v1/audit/executions/{envelope_id}/pii  (masks payload data)\n")
+    return 0
+
+
+def cmd_uninstall(args: list[str]) -> int:
+    """Full uninstall: export data, purge gateway (hard delete), remove SDK."""
+    _print_banner()
+    delete_gateway = "--delete-from-gateway" in args
+    confirmed = "--confirm" in args
+    export_to = None
+    tenant_id = None
+    agent_id = None
+
+    for i, a in enumerate(args):
+        if a == "--export-to" and i + 1 < len(args):
+            export_to = args[i + 1]
+        if a == "--tenant-id" and i + 1 < len(args):
+            tenant_id = args[i + 1]
+        if a == "--agent-id" and i + 1 < len(args):
+            agent_id = args[i + 1]
+
+    if not confirmed:
+        print("  This command will:")
+        step = 1
+        if export_to:
+            print(f"    {step}. Export audit records to {export_to}")
+            step += 1
+        print(f"    {step}. Delete all local SQLite databases")
+        step += 1
+        if delete_gateway:
+            print(
+                f"    {step}. HARD DELETE all gateway data "
+                f"({'tenant=' + tenant_id if tenant_id else 'ALL tenants'}, "
+                f"{'agent=' + agent_id if agent_id else 'all agents'}) — IRREVERSIBLE"
+            )
+            step += 1
+        print(f"    {step}. Print pip uninstall instructions\n")
+        print("  Usage:")
+        print(f"    agentrust uninstall --delete-from-gateway --confirm")
+        print(f"    agentrust uninstall --delete-from-gateway --tenant-id my-org --confirm")
+        print(f"    agentrust uninstall --delete-from-gateway --agent-id my-agent --confirm")
+        print(f"    agentrust uninstall --export-to backup.jsonl --delete-from-gateway --confirm\n")
+        return 1
+
+    print("  Starting AgentTrust uninstall…\n")
+
+    # Step 1: Export
+    if export_to:
+        rc = cmd_export([export_to])
+        if rc != 0:
+            print("  Warning: export had errors, continuing…")
+        else:
+            print(f"  ✓ Exported records to {export_to}")
+
+    # Step 2: Purge local SQLite databases
+    cmd_purge(["--confirm"])
+
+    # Step 3: Hard-delete from gateway using the tenant purge endpoint
+    if delete_gateway:
+        from .config import SDK_CONFIG
+        import httpx
+
+        gw_url = SDK_CONFIG.gateway_url.rstrip("/")
+        key = SDK_CONFIG.api_key
+        headers = {"Content-Type": "application/json"}
+        if key:
+            headers["X-AgentTrust-Token"] = key
+
+        params: dict[str, str] = {"confirm": "true"}
+        if tenant_id:
+            params["tenant_id"] = tenant_id
+        if agent_id:
+            params["agent_id"] = agent_id
+
+        print(f"  Sending hard-delete to {gw_url}/v1/audit/tenant …")
+
+        try:
+            with httpx.Client(base_url=gw_url, headers=headers, timeout=60) as http:
+                resp = http.delete("/v1/audit/tenant", params=params)
+
+                if resp.status_code == 400:
+                    # confirm=false guard triggered — should not happen (we pass confirm=true)
+                    print(f"  ✗ Gateway refused purge: {resp.json().get('detail', '?')}")
+                    return 1
+
+                if resp.status_code == 404:
+                    # Gateway is older and doesn't have the tenant purge endpoint
+                    print("  ⚠  Gateway does not support tenant purge endpoint (old version).")
+                    print("  Falling back to PII masking (soft delete)…")
+                    resp2 = http.delete("/v1/audit/executions", params={"confirm": "true"})
+                    resp2.raise_for_status()
+                    data2 = resp2.json()
+                    print(f"  ✓ Gateway: masked {data2.get('masked', '?')} execution record(s)")
+                    return 0
+
+                resp.raise_for_status()
+                data = resp.json()
+
+            print(
+                f"  ✓ Gateway tenant purge complete:\n"
+                f"       Executions deleted:    {data.get('executions_deleted', '?')}\n"
+                f"       Certifications deleted: {data.get('certifications_deleted', '?')}\n"
+                f"       Agents deleted:         {data.get('agents_deleted', '?')}\n"
+                f"       Total deleted:          {data.get('total_deleted', '?')}"
+            )
+
+        except httpx.ConnectError:
+            print(
+                f"  ✗ Could not reach gateway at {gw_url}\n"
+                f"  Manual step: DELETE {gw_url}/v1/audit/tenant?confirm=true"
+                + (f"&tenant_id={tenant_id}" if tenant_id else "")
+                + (f"&agent_id={agent_id}" if agent_id else "")
+                + "\n"
+            )
+        except Exception as exc:
+            print(f"  ✗ Gateway purge failed: {exc}")
+            print(
+                f"  Manual step: DELETE {gw_url}/v1/audit/tenant"
+                f"?confirm=true on your gateway\n"
+            )
+
+    print("\n  ✓ To complete uninstall, run:")
+    print(f"    {BOLD}pip uninstall agentrust-sdk -y{RESET}\n")
+    return 0
+
+
+def cmd_queue(args: list[str]) -> int:
+    """Queue subcommands: replay, status."""
+    sub = args[0] if args else "status"
+
+    if sub == "replay":
+        _print_banner()
+        print("  Replaying locally buffered validations against gateway…\n")
+        from .client import drain_queue
+        try:
+            sent, failed = drain_queue()
+        except Exception as exc:
+            print(f"  ✗ Replay failed: {exc}\n")
+            return 1
+        print(f"  ✓ Sent: {sent}  Failed: {failed}")
+        if failed:
+            print("  Failed records remain in the queue. Check gateway connectivity.\n")
+        elif sent == 0:
+            print("  Queue is empty — nothing to replay.\n")
+        else:
+            print("  All buffered records replayed successfully.\n")
+        return 0 if failed == 0 else 1
+
+    if sub == "status":
+        from .config import SDK_CONFIG
+        db_path = SDK_CONFIG.queue_db
+        if not db_path.exists():
+            print(f"\n  Queue database not found at {db_path}")
+            print("  No buffered records.\n")
+            return 0
+        import sqlite3
+        try:
+            con = sqlite3.connect(str(db_path))
+            count = con.execute("SELECT COUNT(*) FROM queue").fetchone()[0]
+            con.close()
+            print(f"\n  Queue: {count} buffered record(s) at {db_path}")
+            print("  Run `agentrust queue replay` to flush.\n")
+        except Exception as exc:
+            print(f"\n  Could not read queue: {exc}\n")
+            return 1
+        return 0
+
+    print(f"\n  Unknown queue command: {sub}")
+    print("  Usage: agentrust queue [replay|status]\n")
+    return 1
+
+
+_COMMANDS = {
+    "init": cmd_init,
+    "whoami": cmd_whoami,
+    "status": cmd_status,
+    "policy": cmd_policy,
+    "audit": cmd_audit,
+    "queue": cmd_queue,
+    "export": cmd_export,
+    "purge": cmd_purge,
+    "disable": cmd_disable,
+    "uninstall": cmd_uninstall,
+    "upgrade": cmd_upgrade,
+    "help": cmd_help,
+    "--help": cmd_help,
+    "-h": cmd_help,
+}
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+    if not argv:
+        cmd_help([])
+        return
+
+    cmd = argv[0].lower()
+    rest = argv[1:]
+
+    handler = _COMMANDS.get(cmd)
+    if handler is None:
+        print(f"\n  Unknown command: {cmd}")
+        cmd_help([])
+        sys.exit(1)
+
+    sys.exit(handler(rest))
+
+
+if __name__ == "__main__":
+    main()