verulla-cli 0.0.2__py3-none-any.whl

verulla_cli/main.py

@@ -0,0 +1,1000 @@
+from __future__ import annotations
+
+from pathlib import Path
+import json
+import os
+import re
+import shutil
+import tempfile
+import uuid
+
+import typer
+
+from verulla_cli.auth import DeviceLoginError, get_token, run_device_login
+from verulla_manifest import load_manifest, translate
+from verulla_cli.apps_client import (
+    AppsError,
+    activate_app,
+    delete_app as api_delete_app,
+    delete_customer as api_delete_customer,
+    export_customers as api_export_customers,
+    get_app,
+    get_app_logs,
+
+    get_sketch_events,
+
+    get_pricing,
+
+    get_sketch_status,
+    get_owner_claim_status,
+    get_spend_summary,
+    get_usage_summary,
+    get_term_usage,
+    get_wallet_summary,
+    create_topup,
+    get_auth_policy,
+    invite_customer as api_invite_customer,
+    issue_owner_claim,
+    list_apps,
+    list_customers as api_list_customers,
+    lock_customer as api_lock_customer,
+    rollback_app as api_rollback_app,
+    set_auth_policy,
+    unlock_customer as api_unlock_customer,
+)
+from verulla_cli.deploy_client import DeployError, create_deployment
+from verulla_cli.emulate import DockerRunner, EmulationError, emulate_function
+from verulla_cli.buildkit import BuildKitRunner, select_builder, check_dockerfile
+from verulla_cli.packaging import PackagingError, build_source_tarball
+from verulla_cli.secrets_client import SecretsError, delete_secret as api_delete_secret, list_secret_keys, set_secret, _auth_headers
+
+app = typer.Typer(
+    name="verulla",
+    help="Verulla: AI-agent-friendly deployment & hosting CLI.",
+    no_args_is_help=True,
+)
+sketch_app = typer.Typer(name="sketch", help="Inspect Sketch trial lifecycle status.", no_args_is_help=True)
+app.add_typer(sketch_app, name="sketch")
+owner_app = typer.Typer(name="owner", help="Manage the verified owner hand-off.", no_args_is_help=True)
+app.add_typer(owner_app, name="owner")
+
+_SKETCH_RECEIPT_FIELDS = {
+    "app", "tier", "slug", "status", "lifecycle_state", "trial_started_at",
+    "expires_at", "retention_ends_at", "purge_eligible", "claim_status", "claim_url",
+    "claim_expires_at", "limits", "limits_url", "console_url", "url",
+}
+
+
+def _safe_sketch_receipt(receipt: dict) -> dict:
+    return {key: receipt[key] for key in _SKETCH_RECEIPT_FIELDS if key in receipt}
+
+
+def _not_implemented(command: str) -> None:
+    typer.echo(f"verulla {command}: not yet implemented (coming in a later milestone)")
+    raise typer.Exit(code=1)
+
+
+@app.command()
+def login(
+    api_url: str = typer.Option(
+        ...,
+        "--api-url",
+        envvar="VERULLA_API_URL",
+        help="Verulla control plane base URL.",
+    ),
+) -> None:
+    """Authenticate via the OIDC device authorization grant."""
+    try:
+        run_device_login(api_url.rstrip("/"))
+    except DeviceLoginError as exc:
+        typer.echo(f"Login failed: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo("Logged in.")
+
+
+@app.command()
+def dev(
+    path: str = typer.Argument(".", help="Path to the directory containing verulla.yml"),
+    check: bool = typer.Option(False, "--check", help="Build and smoke-check manifest routes."),
+    json_output: bool = typer.Option(False, "--json", help="Print route results as JSON (with --check)."),
+    builder: str = typer.Option("auto", "--builder", help="Builder backend: auto, docker, or buildkit."),
+) -> None:
+    """Run a local preview with Docker, or build with BuildKit."""
+    base_dir = Path(path).resolve()
+    manifest_path = base_dir / "verulla.yml"
+    if not manifest_path.is_file():
+        typer.echo(f"Error: {manifest_path} not found.", err=True)
+        raise typer.Exit(code=1)
+    try:
+        manifest = load_manifest(manifest_path)
+        result = translate(manifest, base_dir)
+    except ValueError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    try:
+        docker_runner = None
+        try:
+            docker_runner = DockerRunner()
+        except EmulationError:
+            pass
+        selected = select_builder(builder, docker_runner is not None)
+        if selected == "buildkit":
+            kit = BuildKitRunner()
+            for function in result.functions:
+                plan = function.build_plan
+                filename = plan.dockerfile_path or ".verulla.Dockerfile"
+                if check:
+                    with tempfile.TemporaryDirectory(prefix="verulla-check-") as temp:
+                        dockerfile_dir = Path(temp)
+                        if plan.dockerfile_path is None:
+                            from verulla_manifest.dockerfile import generate_dockerfile
+                            (dockerfile_dir / filename).write_text(generate_dockerfile(plan))
+                        check_file = check_dockerfile(function, manifest.routes, dockerfile_dir)
+                        output = kit.build(function.src_root, check_file, check=True, dockerfile_dir=dockerfile_dir)
+                    statuses = _route_statuses(output)
+                    for status in statuses:
+                        typer.echo(f"ROUTE {status['route']} {status['status']}")
+                    if json_output:
+                        typer.echo(json.dumps(statuses) if statuses else json.dumps({"error": "BuildKit check failed", "output": output}))
+                    if not statuses:
+                        typer.echo(output.rstrip() or "BuildKit check failed without route results", err=True)
+                        raise typer.Exit(code=1)
+                    if any(status["status"] < 200 or status["status"] >= 400 for status in statuses):
+                        raise typer.Exit(code=1)
+                else:
+                    if plan.dockerfile_path is None:
+                        from verulla_manifest.dockerfile import generate_dockerfile
+                        (function.src_root / filename).write_text(generate_dockerfile(plan))
+                    output = kit.build(function.src_root, filename)
+                    typer.echo(f"{function.name}: built with BuildKit")
+                    if output.strip():
+                        typer.echo(output.rstrip())
+            if not check:
+                typer.echo("Interactive local preview requires Docker; use verulla deploy to a Sketch app for the remote runtime.")
+                return
+            return
+        runner = docker_runner
+    except EmulationError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    if check:
+        statuses = []
+        for function in result.functions:
+            plan = function.build_plan
+            filename = plan.dockerfile_path or ".verulla.Dockerfile"
+            generated = []
+            try:
+                if plan.dockerfile_path is None:
+                    from verulla_manifest.dockerfile import generate_dockerfile
+                    (function.src_root / filename).write_text(generate_dockerfile(plan))
+                    generated.append(function.src_root / filename)
+                test_file = check_dockerfile(function, manifest.routes)
+                generated.append(function.src_root / test_file)
+                output = runner.check_image(function.src_root, test_file, f"verulla-check-{function.name}:latest")
+                statuses.extend(_route_statuses(output))
+                if not _route_statuses(output):
+                    if json_output:
+                        typer.echo(json.dumps({"error": "Docker check failed", "output": output}))
+                    typer.echo(output.rstrip() or "Docker check failed without route results", err=True)
+                    raise typer.Exit(code=1)
+            except EmulationError as exc:
+                if json_output:
+                    typer.echo(json.dumps({"error": str(exc), "output": str(exc)}))
+                typer.echo(str(exc), err=True)
+                raise typer.Exit(code=1) from exc
+            finally:
+                for generated_file in generated:
+                    generated_file.unlink(missing_ok=True)
+        _print_route_results(statuses, json_output)
+        if not statuses or any(not 200 <= item["status"] < 400 for item in statuses):
+            raise typer.Exit(code=1)
+        return
+    host_port = 8000
+    for build in result.functions:
+        try:
+            url = emulate_function(build, runner, host_port)
+        except EmulationError as exc:
+            typer.echo(f"Error building/running {build.name!r}: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+        typer.echo(f"{build.name}: {url}")
+        host_port += 1
+
+
+def _route_statuses(output: str) -> list[dict[str, int | str]]:
+    statuses = []
+    for line in output.splitlines():
+        match = re.search(r"(?:^|\s)ROUTE\s+(\S+)\s+(\d{3})(?:\s|$)", line)
+        if match:
+            statuses.append({"route": match.group(1), "status": int(match.group(2))})
+    seen: set[tuple[str, int]] = set()
+    unique = []
+    for status in statuses:
+        key = (str(status["route"]), int(status["status"]))
+        if key not in seen:
+            seen.add(key)
+            unique.append(status)
+    return unique
+
+
+def _print_route_results(statuses: list[dict[str, int | str]], json_output: bool) -> None:
+    for status in statuses:
+        typer.echo(f"ROUTE {status['route']} {status['status']}")
+    if json_output:
+        typer.echo(json.dumps(statuses))
+
+
+@app.command()
+def deploy(
+    path: str = typer.Argument(".", help="Path to the directory containing verulla.yml"),
+    api_url: str = typer.Option(
+        ...,
+        "--api-url",
+        envvar="VERULLA_API_URL",
+        help="Verulla control plane base URL.",
+    ),
+) -> None:
+    """Deploy the app described by verulla.yml to your Verulla tenant."""
+    base_dir = Path(path).resolve()
+    manifest_path = base_dir / "verulla.yml"
+    if not manifest_path.is_file():
+        typer.echo(f"Error: {manifest_path} not found.", err=True)
+        raise typer.Exit(code=1)
+    # Validate locally with the same translator the server uses, before the
+    # login check, so manifest problems fail fast and offline.
+    try:
+        translate(load_manifest(manifest_path), base_dir)
+    except ValueError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    try:
+        token = get_token()
+    except DeviceLoginError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    try:
+        tarball = build_source_tarball(base_dir)
+    except PackagingError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"Uploading {len(tarball) / 1024:.1f} KB...")
+    try:
+        deployment = create_deployment(api_url.rstrip("/"), token, tarball)
+    except DeployError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"App {deployment.get('app_action', 'deployed')}: {deployment['app']} ({deployment['id']})")
+    if deployment.get("url"):
+        typer.echo(deployment["url"])
+    for fn in deployment.get("functions", []):
+        typer.echo(f"  {fn['name']} ({fn['adapter']})")
+
+
+secrets_app = typer.Typer(help="Manage per-tenant secrets and environment variables.")
+app.add_typer(secrets_app, name="secrets")
+
+
+def _secret_scope(app_name: str | None, shared: bool) -> str | None:
+    if app_name and shared:
+        typer.echo("Use either --app APP or --shared, not both.", err=True)
+        raise typer.Exit(code=2)
+    if app_name:
+        return app_name
+    if shared:
+        return None
+    manifest = Path.cwd() / "verulla.yml"
+    if manifest.is_file():
+        try:
+            return load_manifest(manifest).app
+        except ValueError as exc:
+            typer.echo(f"Error reading {manifest}: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+    return None
+
+
+@secrets_app.command("list")
+def secrets_list(
+    app_name: str | None = typer.Option(None, "--app", help="Scope secrets to APP."),
+    shared: bool = typer.Option(False, "--shared", help="Use tenant-shared scope."),
+    api_url: str = typer.Option(
+        ...,
+        "--api-url",
+        envvar="VERULLA_API_URL",
+        help="Verulla control plane base URL.",
+    ),
+) -> None:
+    """List secret keys (values are never printed)."""
+    scope = _secret_scope(app_name, shared)
+    try:
+        token = get_token()
+    except DeviceLoginError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    try:
+        keys = list_secret_keys(api_url.rstrip("/"), token, app=scope)
+    except SecretsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    if not keys:
+        typer.echo("No secrets set.")
+        return
+    for key in keys:
+        typer.echo(key)
+
+
+@secrets_app.command("set")
+def secrets_set(
+    key: str = typer.Argument(..., help="Secret key name"),
+    app_name: str | None = typer.Option(None, "--app", help="Scope secret to APP."),
+    shared: bool = typer.Option(False, "--shared", help="Use tenant-shared scope."),
+    api_url: str = typer.Option(
+        ...,
+        "--api-url",
+        envvar="VERULLA_API_URL",
+        help="Verulla control plane base URL.",
+    ),
+) -> None:
+    """Set a secret value (you'll be prompted; never pass secrets on the command line)."""
+    scope = _secret_scope(app_name, shared)
+    try:
+        token = get_token()
+    except DeviceLoginError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    value = typer.prompt(f"Value for {key}", hide_input=True)
+    try:
+        set_secret(api_url.rstrip("/"), token, key, value, app=scope)
+    except SecretsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"Secret {key!r} set.")
+
+
+@secrets_app.command("delete")
+def secrets_delete(
+    key: str = typer.Argument(..., help="Secret key name"),
+    app_name: str | None = typer.Option(None, "--app", help="Scope secret to APP."),
+    shared: bool = typer.Option(False, "--shared", help="Use tenant-shared scope."),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Delete a secret without displaying its value."""
+    scope = _secret_scope(app_name, shared)
+    try:
+        token = get_token()
+    except DeviceLoginError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    try:
+        api_delete_secret(api_url.rstrip("/"), token, key, app=scope)
+    except SecretsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"Secret {key!r} deleted.")
+
+
+@app.command()
+def logs(
+    app_name: str = typer.Argument(..., metavar="APP", help="App name"),
+    function: str | None = typer.Argument(None, help="Optional function name (reserved for runtime logs)"),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Show latest deployment status and build log tail (runtime logs are not available yet)."""
+    del function
+    try:
+        token = get_token()
+    except DeviceLoginError:
+        typer.echo("Not logged in. Run `verulla login` first.", err=True)
+        raise typer.Exit(code=1)
+    try:
+        result = get_app_logs(api_url.rstrip("/"), token, app_name)
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    for key in ("app", "deployment_id", "status", "error"):
+        typer.echo(f"{key}: {result.get(key)}")
+    typer.echo("build_log_tail:")
+    typer.echo(result.get("build_log_tail") or "(no build log available)")
+    typer.echo("Runtime/pod logs are not available yet.")
+
+
+def _resolve_app(name: str | None) -> str:
+    if name:
+        return name
+    manifest = Path.cwd() / "verulla.yml"
+    if manifest.is_file():
+        try:
+            return load_manifest(manifest).app
+        except ValueError as exc:
+            typer.echo(f"Error reading {manifest}: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+    typer.echo("Provide APP or run inside a directory containing verulla.yml.", err=True)
+    raise typer.Exit(code=2)
+
+
+@app.command()
+def apps(
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """List apps in your tenant."""
+    try:
+        token = get_token()
+    except DeviceLoginError:
+        typer.echo("Not logged in. Run `verulla login` first.", err=True)
+        raise typer.Exit(code=1)
+    try:
+        rows = list_apps(api_url.rstrip("/"), token)
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    if not rows:
+        typer.echo("No apps.")
+        return
+    for row in rows:
+        typer.echo(f"{row['app']}  {row['status']}  {row.get('url') or '-'}")
+
+
+@app.command()
+def wallet(
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Show wallet balance, ledger and spending-limit summary as JSON."""
+    try:
+        typer.echo(json.dumps(get_wallet_summary(api_url.rstrip("/"), get_token()), indent=2))
+    except (DeviceLoginError, AppsError) as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def usage(
+    app_name: str | None = typer.Argument(None, help="Optional Live app name; omit to show all Live apps."),
+    month: str | None = typer.Option(None, "--month", help="Calendar usage month in YYYY-MM format (legacy view)."),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Show Live term allowances, usage, projected costs and spending headroom."""
+    try:
+        if month is not None:
+            result = get_usage_summary(api_url.rstrip("/"), get_token(), month=month)
+        else:
+            result = get_term_usage(api_url.rstrip("/"), get_token(), app=app_name)
+        typer.echo(json.dumps(result, indent=2))
+    except (DeviceLoginError, AppsError) as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def spend(
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Show current spend and spending-limit headroom as JSON."""
+    try:
+        typer.echo(json.dumps(get_spend_summary(api_url.rstrip("/"), get_token()), indent=2))
+    except (DeviceLoginError, AppsError) as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def pricing(
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Show the USD/CAD fixed-price contract as JSON."""
+    try:
+        typer.echo(json.dumps(get_pricing(api_url.rstrip("/"), get_token()), indent=2))
+    except (DeviceLoginError, AppsError) as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def topup(
+    amount_cents: int = typer.Argument(..., min=1, help="Top-up amount in minor units (cents)."),
+    currency: str = typer.Option("USD", "--currency", help="Wallet currency: USD or CAD (chosen on first top-up)."),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Create a wallet top-up intent; currency becomes fixed after funding."""
+    if currency not in {"USD", "CAD"}:
+        typer.echo("Currency must be USD or CAD.", err=True)
+        raise typer.Exit(code=2)
+    try:
+        result = create_topup(api_url.rstrip("/"), get_token(), amount_cents, currency)
+    except (DeviceLoginError, AppsError) as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command()
+def live(
+    app_name: str = typer.Argument(..., metavar="APP", help="App to upgrade to Live."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Upgrade an app to Live at the published price in its wallet currency."""
+    try:
+        token = get_token()
+    except DeviceLoginError:
+        typer.echo("Not logged in. Run `verulla login` first.", err=True)
+        raise typer.Exit(code=1)
+    try:
+        app_status = get_app(api_url.rstrip("/"), token, app_name)
+        if app_status.get("live_activation_available") is not True:
+            typer.echo("Live activation is not currently available for this app.", err=True)
+            raise typer.Exit(code=1)
+        spend = get_spend_summary(api_url.rstrip("/"), token)
+        currency = spend.get("currency", "USD")
+        contract = get_pricing(api_url.rstrip("/"), token)
+    except AppsError as exc:
+        typer.echo(f"Error checking Live availability or spending-limit headroom: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    live_tier = next((tier for tier in contract.get("tiers", []) if tier.get("id") == "live"), {})
+    prices = live_tier.get("prices_cents", {})
+    price_cents = prices.get(currency)
+    if price_cents is None:
+        price_cents = live_tier.get("price_usd_cents") if currency == "USD" else live_tier.get("price_cad_cents")
+    if currency not in {"USD", "CAD"} or not isinstance(price_cents, int):
+        typer.echo(f"Unsupported wallet currency {currency!r} for Live pricing.", err=True)
+        raise typer.Exit(code=1)
+    symbol = "C$" if currency == "CAD" else "US$"
+    price_text = f"{symbol}{price_cents // 100:,}.{price_cents % 100:02d}"
+    remaining = spend.get("remaining_cents")
+    if isinstance(remaining, int) and not isinstance(remaining, bool):
+        headroom = f"{symbol}{remaining // 100:,}.{remaining % 100:02d}"
+    else:
+        headroom = "no spending limit set"
+    typer.echo(f"Live costs {price_text} per 30 days ({currency}).")
+    typer.echo(f"Spending-limit headroom: {headroom}.")
+    if not yes:
+        typer.confirm(f"Make {app_name!r} Live for {price_text} per 30 days?", abort=True)
+    try:
+        result = activate_app(api_url.rstrip("/"), token, app_name, str(uuid.uuid4()))
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"{app_name} is Live through {result.get('paid_through')} (price {result.get('pricing_version')}).")
+
+
+@app.command()
+def status(
+    app_name: str | None = typer.Argument(None, metavar="APP"),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Show app overview, or detailed status for APP."""
+    try:
+        token = get_token()
+    except DeviceLoginError:
+        typer.echo("Not logged in. Run `verulla login` first.", err=True)
+        raise typer.Exit(code=1)
+    try:
+        if app_name is None:
+            rows = list_apps(api_url.rstrip("/"), token)
+            for row in rows:
+                typer.echo(f"{row['app']}  {row['status']}  {row.get('url') or '-'}")
+        else:
+            row = get_app(api_url.rstrip("/"), token, app_name)
+            for key in ("app", "tier_id", "pricing_version", "paid_through", "renewal_date", "status", "latest_deployment_id", "source_sha", "function_count", "url", "updated_at", "error", "functions"):
+                if key in row:
+                    typer.echo(f"{key}: {row[key]}")
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@sketch_app.command("events")
+def sketch_events(
+    app_name: str = typer.Argument(..., metavar="APP"),
+    cursor: str | None = typer.Option(None, "--cursor", help="Resume after this event cursor."),
+    limit: int = typer.Option(100, min=1, max=500),
+    json_output: bool = typer.Option(False, "--json", help="Print the shared API event envelope as JSON."),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL"),
+) -> None:
+    """Poll durable Sketch countdown events after the supplied cursor."""
+    result = _auth_api_call(
+        get_sketch_events, api_url.rstrip("/"), _agent_token(), app_name,
+        cursor=cursor, limit=limit,
+    )
+    if json_output:
+        typer.echo(json.dumps(result))
+        return
+    for event in result["events"]:
+        typer.echo(f"{event['occurred_at']}  {event['type']}  {event['app']}")
+    if result["next_cursor"]:
+        typer.echo(f"next_cursor: {result['next_cursor']}")
+    typer.echo(f"has_more: {str(result['has_more']).lower()}")
+@sketch_app.command("status")
+def sketch_status(
+    app_name: str = typer.Argument(..., metavar="APP"),
+    json_output: bool = typer.Option(False, "--json", help="Print the receipt as JSON."),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Show the shared Sketch lifecycle receipt for APP."""
+    try:
+        token = get_token()
+    except DeviceLoginError:
+        typer.echo("Not logged in. Run `verulla login` first.", err=True)
+        raise typer.Exit(code=1)
+    try:
+        receipt = _safe_sketch_receipt(get_sketch_status(api_url.rstrip("/"), token, app_name))
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    if json_output:
+        typer.echo(json.dumps(receipt))
+        return
+    for key in ("app", "status", "url", "lifecycle_state", "expires_at", "retention_ends_at", "claim_status", "limits_url", "console_url"):
+        if key in receipt:
+            typer.echo(f"{key}: {receipt[key]}")
+
+
+@owner_app.command("claim")
+def owner_claim(
+    app_name: str = typer.Argument(..., metavar="APP"),
+    email: str = typer.Option(..., "--email", help="Verified owner's email address."),
+    json_output: bool = typer.Option(False, "--json", help="Print the one-time hand-off as JSON."),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Issue a one-time claim link for the owner of APP's tenant."""
+    try:
+        token = get_token()
+        receipt = get_sketch_status(api_url.rstrip("/"), token, app_name)
+        if not receipt.get("url"):
+            typer.echo("Error: APP has no public app URL yet; deploy it before issuing an owner claim.", err=True)
+            raise typer.Exit(code=1)
+        claim = issue_owner_claim(api_url.rstrip("/"), token, email, str(uuid.uuid4()))
+    except DeviceLoginError:
+        typer.echo("Not logged in. Run `verulla login` first.", err=True)
+        raise typer.Exit(code=1)
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    result = {
+        "app": app_name,
+        "url": receipt.get("url"),
+        "claim_url": claim.get("claim_url"),
+        "expires_at": claim.get("expires_at"),
+        "status": claim.get("status", "pending"),
+    }
+    if not result["url"] or not result["claim_url"] or not result["expires_at"]:
+        typer.echo("Error: owner claim response was incomplete.", err=True)
+        raise typer.Exit(code=1)
+    if json_output:
+        typer.echo(json.dumps(result))
+        return
+    for key, value in result.items():
+        typer.echo(f"{key}: {value}")
+
+
+@owner_app.command("status")
+def owner_status(
+    app_name: str = typer.Argument(..., metavar="APP"),
+    json_output: bool = typer.Option(False, "--json", help="Print safe claim status as JSON."),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Show safe owner-claim status for APP without revealing its link or email."""
+    try:
+        token = get_token()
+        receipt = get_sketch_status(api_url.rstrip("/"), token, app_name)
+        claim = get_owner_claim_status(api_url.rstrip("/"), token)
+    except DeviceLoginError:
+        typer.echo("Not logged in. Run `verulla login` first.", err=True)
+        raise typer.Exit(code=1)
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    result = {"app": app_name, "url": receipt.get("url"), "status": claim.get("status")}
+    if claim.get("expires_at") is not None:
+        result["expires_at"] = claim["expires_at"]
+    if json_output:
+        typer.echo(json.dumps(result))
+        return
+    for key, value in result.items():
+        typer.echo(f"{key}: {value}")
+
+
+@app.command()
+def delete(
+    app_name: str | None = typer.Argument(None, metavar="APP"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Delete an app and its deployments."""
+    name = _resolve_app(app_name)
+    if not yes:
+        typer.confirm(f"Delete app {name!r} and its deployments?", abort=True)
+    try:
+        token = get_token()
+    except DeviceLoginError:
+        typer.echo("Not logged in. Run `verulla login` first.", err=True)
+        raise typer.Exit(code=1)
+    try:
+        api_delete_app(api_url.rstrip("/"), token, name)
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"Deletion queued for {name}.")
+
+
+@app.command()
+def rollback(
+    app_name: str | None = typer.Argument(None, metavar="APP"),
+    api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL", help="Verulla control plane base URL."),
+) -> None:
+    """Redeploy the previous successful app snapshot."""
+    name = _resolve_app(app_name)
+    try:
+        token = get_token()
+    except DeviceLoginError:
+        typer.echo("Not logged in. Run `verulla login` first.", err=True)
+        raise typer.Exit(code=1)
+    try:
+        result = api_rollback_app(api_url.rstrip("/"), token, name)
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"Rollback deployment {result['id']} queued for {name}.")
+
+
+@app.command()
+def keys_mint(
+    name: str = typer.Argument(..., help="Key name"),
+    scopes: list[str] = typer.Option(
+        [],
+        "--scopes",
+        help="Space-separated list of scopes (defaults to all except keys:admin)",
+    ),
+    expires_in_days: int | None = typer.Option(
+        None,
+        "--expires-in-days",
+        min=1,
+        max=3650,
+        help="Key expiration in days (1-3650)",
+    ),
+    api_url: str = typer.Option(
+        ...,
+        "--api-url",
+        envvar="VERULLA_API_URL",
+        help="Verulla control plane base URL.",
+    ),
+) -> None:
+    """Mint a new tenant-scoped API key.
+
+    Requires `keys:admin` scope on the authenticated principal. The plaintext
+    token is returned once and never persisted. Only ``token_hash`` (SHA-256
+    hex) is stored at rest.
+    """
+    try:
+        token = get_token()
+    except DeviceLoginError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    import httpx
+
+    owns_client = True
+    client = httpx.Client(timeout=10)
+    try:
+        # Verify the token works
+        response = client.get(f"{api_url.rstrip('/')}/v1/me", headers={"Authorization": f"Bearer {token}"})
+        if response.status_code == 401:
+            typer.echo("Invalid API token", err=True)
+            raise typer.Exit(code=1)
+        if response.status_code != 200:
+            typer.echo(f"Unexpected response: {response.status_code}", err=True)
+            raise typer.Exit(code=1)
+        # Query parameters follow the route's repeated `scopes` contract.
+        params = {"name": name, "scopes": scopes}
+        if expires_in_days is not None:
+            params["expires_in_days"] = str(expires_in_days)
+        mint_response = client.post(
+            f"{api_url.rstrip('/')}/v1/keys",
+            params=params,
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        if mint_response.status_code == 403:
+            typer.echo("Missing required scope keys:admin", err=True)
+            raise typer.Exit(code=1)
+        if mint_response.status_code != 201:
+            typer.echo(f"Mint failed: {mint_response.text}", err=True)
+            raise typer.Exit(code=1)
+        data = mint_response.json()
+        typer.echo(f"Key minted: {data.get('prefix', 'unknown')}...{data.get('name', name)}")
+        typer.echo(f"Scopes: {data.get('scopes', [])}")
+        typer.echo(f"Token: {data.get('token', '')}")
+    finally:
+        if owns_client:
+            client.close()
+
+
+@app.command()
+def keys_revoke(
+    key_id: str = typer.Argument(..., help="ID of the key to revoke"),
+    api_url: str = typer.Option(
+        ...,
+        "--api-url",
+        envvar="VERULLA_API_URL",
+        help="Verulla control plane base URL.",
+    ),
+) -> None:
+    """Soft-revoke an API key in your tenant.
+
+    Idempotent: revoking an already-revoked key keeps its original
+    revoked_at.
+    """
+    try:
+        token = get_token()
+    except DeviceLoginError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    import httpx
+
+    owns_client = True
+    client = httpx.Client(timeout=10)
+    try:
+        revoke_response = client.delete(
+            f"{api_url.rstrip('/')}/v1/keys/{key_id}",
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        if revoke_response.status_code == 404:
+            typer.echo("API key not found in this tenant", err=True)
+            raise typer.Exit(code=1)
+        if revoke_response.status_code != 204:
+            typer.echo(f"Revoke failed: {revoke_response.text}", err=True)
+            raise typer.Exit(code=1)
+        typer.echo(f"Key {key_id} revoked.")
+    finally:
+        if owns_client:
+            client.close()
+
+
+auth_app = typer.Typer(help="Manage app customer authentication policy.", no_args_is_help=True)
+customers_app = typer.Typer(help="Manage customers for an app.", no_args_is_help=True)
+app.add_typer(auth_app, name="auth")
+app.add_typer(customers_app, name="customers")
+
+
+def _agent_token() -> str:
+    try:
+        return get_token()
+    except DeviceLoginError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+def _auth_api_call(fn, *args, **kwargs):
+    try:
+        return fn(*args, **kwargs)
+    except AppsError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@auth_app.command("show")
+def auth_show(app_name: str = typer.Argument(..., metavar="APP"), api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL")) -> None:
+    """Show the app's AuthPolicy and version."""
+    data = _auth_api_call(get_auth_policy, api_url.rstrip("/"), _agent_token(), app_name)
+    typer.echo(json.dumps(data, indent=2))
+
+
+@auth_app.command("set")
+def auth_set(app_name: str = typer.Argument(..., metavar="APP"), policy_file: Path = typer.Argument(..., exists=True, readable=True),
+             api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL"),
+             version: int | None = typer.Option(None, "--version", min=0)) -> None:
+    """Set policy from a JSON file, optionally pinning the expected version."""
+    try:
+        policy = json.loads(policy_file.read_text())
+        if not isinstance(policy, dict):
+            raise ValueError("policy must be a JSON object")
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        typer.echo(f"Invalid policy JSON: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+    if version is None:
+        typer.echo(
+            "Warning: no --version supplied; updating the latest policy. "
+            "Pass the version from `verulla auth show APP` with --version to reject stale updates.",
+            err=True,
+        )
+        current = _auth_api_call(get_auth_policy, api_url.rstrip("/"), _agent_token(), app_name)
+        version = current["version"]
+    result = _auth_api_call(set_auth_policy, api_url.rstrip("/"), _agent_token(), app_name, version, policy)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@customers_app.command("list")
+def customers_list(app_name: str = typer.Argument(..., metavar="APP"), search: str | None = typer.Option(None, "--search"),
+                   limit: int = typer.Option(50, min=1, max=100), offset: int = typer.Option(0, min=0),
+                   api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL")) -> None:
+    """List customers (requires auth:customers scope)."""
+    result = _auth_api_call(api_list_customers, api_url.rstrip("/"), _agent_token(), app_name, search=search, limit=limit, offset=offset)
+    typer.echo(json.dumps(result, indent=2))
+
+
+@customers_app.command("lock")
+def customers_lock(app_name: str, customer_id: str, api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL")) -> None:
+    """Lock a customer account."""
+    typer.echo(json.dumps(_auth_api_call(api_lock_customer, api_url.rstrip("/"), _agent_token(), app_name, customer_id), indent=2))
+
+
+@customers_app.command("unlock")
+def customers_unlock(app_name: str, customer_id: str, api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL")) -> None:
+    """Unlock a customer account."""
+    typer.echo(json.dumps(_auth_api_call(api_unlock_customer, api_url.rstrip("/"), _agent_token(), app_name, customer_id), indent=2))
+
+
+@customers_app.command("delete")
+def customers_delete(app_name: str, customer_id: str, yes: bool = typer.Option(False, "--yes", "-y"),
+                     api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL")) -> None:
+    """Soft-delete a customer after confirmation."""
+    if not yes:
+        typer.confirm(f"Delete customer {customer_id!r} from {app_name!r}?", abort=True)
+    _auth_api_call(api_delete_customer, api_url.rstrip("/"), _agent_token(), app_name, customer_id)
+    typer.echo("Customer deleted.")
+
+
+@customers_app.command("export")
+def customers_export(app_name: str, output: Path = typer.Option(..., "--output", writable=True),
+                     api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL")) -> None:
+    """Export customer PII as CSV to OUTPUT (requires auth:customers scope)."""
+    csv_data = _auth_api_call(api_export_customers, api_url.rstrip("/"), _agent_token(), app_name)
+    descriptor = os.open(output, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w") as export_file:
+            descriptor = -1
+            export_file.write(csv_data)
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+    typer.echo(f"Customer export written to {output}.")
+
+
+@customers_app.command("invite")
+def customers_invite(app_name: str, email: str, api_url: str = typer.Option(..., "--api-url", envvar="VERULLA_API_URL")) -> None:
+    """Invite a customer; delivery may be logging-only until email is configured."""
+    typer.echo(json.dumps(_auth_api_call(api_invite_customer, api_url.rstrip("/"), _agent_token(), app_name, email), indent=2))
+
+
+admin_app = typer.Typer(help="Operator commands (need the operator role; tailnet only).", no_args_is_help=True)
+app.add_typer(admin_app, name="admin")
+
+
+@admin_app.command("whoami")
+def admin_whoami(
+    admin_url: str = typer.Option(
+        ...,
+        "--admin-url",
+        envvar="VERULLA_ADMIN_URL",
+        help="Admin API base URL (tailnet host; /v1/admin is blocked on the public API host).",
+    ),
+) -> None:
+    """Show who the admin API thinks you are (sub, roles, scopes, client)."""
+    import httpx
+
+    try:
+        token = get_token()
+    except DeviceLoginError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    try:
+        response = httpx.get(
+            f"{admin_url.rstrip('/')}/v1/admin/whoami",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10,
+        )
+    except httpx.HTTPError as exc:
+        typer.echo(f"Error: cannot reach {admin_url}: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    if response.status_code != 200:
+        typer.echo(f"Error: {response.status_code} {response.text[:300]}", err=True)
+        raise typer.Exit(code=1)
+    data = response.json()
+    typer.echo(f"sub:    {data.get('sub')}")
+    typer.echo(f"client: {data.get('client')}")
+    typer.echo(f"roles:  {', '.join(data.get('roles') or []) or '(none)'}")
+    typer.echo(f"scopes: {', '.join(data.get('scopes') or []) or '(none)'}")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()