bladekit 4.5.0__py3-none-any.whl

bladekit/cli.py

@@ -0,0 +1,2282 @@
+"""``blade`` command-line interface.
+
+Commands:
+  blade setup               authenticate via the browser, save an API token
+  blade run <script.py>     run the @app.local_entrypoint, stream logs live
+  blade logs <run_id>       show / follow logs (with resume)
+  blade status <run_id>     run state + queue position if pending
+  blade runs                list runs
+  blade cancel <run_id>     cancel a run
+  blade nodes               fleet view (GPUs free/busy) — staff session token only
+  blade token set/show      manage ~/.blade/config.toml
+  blade admin …             contain-user / force-stop (staff session token)
+  blade --version           print the installed bladekit version
+
+``forge`` is the same command under its pre-PAAS-771 name (shipped by the
+``forge-shadow`` compatibility distribution).
+
+Heavy modules (httpx, the App machinery) are imported lazily inside commands so
+``blade --help`` stays fast.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Blade AI Fabric — run Python functions on the GPU fleet.",
+)
+
+token_app = typer.Typer(no_args_is_help=True, help="Manage API token / endpoint.")
+app.add_typer(token_app, name="token")
+
+volume_app = typer.Typer(no_args_is_help=True, help="Manage network volumes.")
+app.add_typer(volume_app, name="volume")
+
+secret_app = typer.Typer(no_args_is_help=True, help="Manage secrets.")
+app.add_typer(secret_app, name="secret")
+
+image_app = typer.Typer(no_args_is_help=True, help="Image catalogue / DSL builds.")
+app.add_typer(image_app, name="image")
+
+app_app = typer.Typer(no_args_is_help=True, help="Manage deployed apps.")
+app.add_typer(app_app, name="app")
+
+map_app = typer.Typer(no_args_is_help=True, help="Manage map batch invocations.")
+app.add_typer(map_app, name="map")
+
+cron_app = typer.Typer(no_args_is_help=True, help="Manage cron schedules.")
+app.add_typer(cron_app, name="cron")
+
+queue_app = typer.Typer(no_args_is_help=True, help="Manage distributed queues.")
+app.add_typer(queue_app, name="queue")
+
+dict_app = typer.Typer(no_args_is_help=True, help="Manage distributed key-value stores.")
+app.add_typer(dict_app, name="dict")
+
+sandbox_app = typer.Typer(no_args_is_help=True, help="Manage sandboxes.")
+app.add_typer(sandbox_app, name="sandbox")
+
+admin_app = typer.Typer(
+    no_args_is_help=True,
+    help="Platform-admin containment tools (requires a staff SESSION token: an fg_ key "
+    "carries no compute:admin and is refused 403 INSUFFICIENT_SCOPE).",
+)
+app.add_typer(admin_app, name="admin")
+
+
+def _env_flag(name: str) -> bool:
+    """Read a boolean FABRIC_<name> env var, falling back to FORGE_<name> (repo
+    convention: manual os.environ lookup, see _env.py — not typer's envvar=)."""
+    from ._env import flag
+
+    return flag(name)
+
+
+def _version_callback(value: bool) -> None:
+    """``blade --version``: the compact banner on a terminal, plain text otherwise."""
+    if not value:
+        return
+    from . import DISTRIBUTION, __version__
+    from ._render import print_version
+
+    print_version(f"{DISTRIBUTION} {__version__}")
+    raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Verbose output: raw build steps and per-state transitions "
+        "(also enabled by FABRIC_VERBOSE). Default is a clean phase view.",
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the installed bladekit version and exit.",
+    ),
+):
+    """Blade AI Fabric — run Python functions on the GPU fleet."""
+    from ._render import set_verbose
+
+    set_verbose(verbose or _env_flag("VERBOSE"))
+
+
+# --------------------------------------------------------------------------
+# shared helpers
+# --------------------------------------------------------------------------
+
+
+def _make_client():
+    from ._client import Client
+    from ._render import err_console
+    from .config import load_config
+
+    cfg = load_config()
+    if not cfg.token:
+        err_console.print(
+            "[red]No API token configured.[/red] Run `blade setup` or "
+            "`blade token set`, or set FABRIC_TOKEN."
+        )
+        raise typer.Exit(code=2)
+    client = Client(cfg.api_url, cfg.token)
+    client.warn_if_outdated()
+    return client, cfg
+
+
+def _handle_fabric_error(e: Exception) -> "typer.Exit":
+    """Render any FabricError with its machine code + human message, return Exit."""
+    from ._render import err_console
+    from . import exceptions as exc
+
+    if isinstance(e, exc.ImageBuildError):
+        # Failed DSL build: code + message + the actionable `blade image logs`
+        # hint (already embedded in the message).
+        err_console.print(f"[red]image build failed[/red] [bold]{e.code}[/bold]:")
+        err_console.print(str(e), markup=False, highlight=False)
+    elif isinstance(e, exc.VolumeCommitError):
+        err_console.print(f"[red]volume commit failed[/red] [bold]{e.code}[/bold]: {e}")
+    elif isinstance(e, exc.APIError):
+        err_console.print(f"[red]error[/red] [bold]{e.code}[/bold]: {e.api_message}")
+        if e.details:
+            err_console.print(f"  details: {json.dumps(e.details)}")
+    elif isinstance(e, exc.RunError):
+        # Show code + full message (carries the actionable hint, exceptions.py).
+        err_console.print(f"[red]run failed[/red] [bold]{e.code}[/bold]:")
+        err_console.print(str(e), markup=False, highlight=False)
+    elif isinstance(e, exc.ConnectionFailed):
+        err_console.print(f"[red]connection failed[/red]: {e}")
+    else:
+        err_console.print(f"[red]error[/red]: {e}")
+    return typer.Exit(code=1)
+
+
+# --------------------------------------------------------------------------
+# token
+# --------------------------------------------------------------------------
+
+
+@token_app.command("set")
+def token_set(
+    api_url: Optional[str] = typer.Option(
+        None, "--api-url", help="Control plane base URL to persist."
+    ),
+    from_env: Optional[str] = typer.Option(
+        None,
+        "--from-env",
+        help="Read the token from this environment variable (e.g. FABRIC_TOKEN).",
+    ),
+):
+    """Write the token (and optionally api_url) to ~/.blade/config.toml.
+
+    The token is never accepted as a positional argument — that would leak it
+    into ``ps aux``, shell history, and process monitoring tools. Instead:
+
+    \\b
+      blade token set --from-env FABRIC_TOKEN  # reads $FABRIC_TOKEN
+      echo $TOKEN | blade token set            # reads from stdin
+    """
+    from ._render import console
+    from .config import write_config
+
+    token: Optional[str] = None
+    if from_env:
+        import os
+
+        token = os.environ.get(from_env)
+        if not token:
+            console.print(f"[red]env var not set or empty[/red]: {from_env}")
+            raise typer.Exit(code=2)
+    else:
+        # Read from stdin so the token never appears in argv.
+        if sys.stdin.isatty():
+            console.print("[dim]paste your API token then press Enter (input not echoed)…[/dim]")
+        line = sys.stdin.readline().rstrip("\n\r")
+        if not line:
+            console.print("[red]no token provided[/red] (pass via stdin or --from-env)")
+            raise typer.Exit(code=2)
+        token = line
+
+    path = write_config(token=token, api_url=api_url)
+    console.print(f"[green]Saved[/green] token to {path}")
+    if api_url:
+        console.print(f"[green]Saved[/green] api_url = {api_url}")
+
+
+@token_app.command("show")
+def token_show():
+    """Show the effective token/endpoint and where each came from."""
+    from ._render import console
+    from .config import load_config
+
+    cfg = load_config()
+    console.print(f"api_url : {cfg.api_url}  [dim]({cfg.api_url_source})[/dim]")
+    if cfg.token:
+        masked = cfg.token[:6] + "…" + cfg.token[-4:] if len(cfg.token) > 12 else "set"
+        console.print(f"token   : {masked}  [dim]({cfg.token_source})[/dim]")
+    else:
+        console.print("token   : [yellow]not set[/yellow]")
+
+
+@app.command()
+def setup(
+    api_url: Optional[str] = typer.Option(
+        None, "--api-url", help="Control plane base URL (default: configured value / FABRIC_API_URL)."
+    ),
+):
+    """Authenticate this machine through the browser and save an API token.
+
+    Opens your browser to confirm your identity, mints a token bound to your
+    workspace, and writes it to ~/.blade/config.toml — like ``modal setup``.
+    """
+    import time
+    import webbrowser
+
+    import httpx
+
+    from ._render import console, err_console, print_intro
+    from .config import load_config, write_config
+
+    print_intro()
+    cfg = load_config()
+    base = (api_url or cfg.api_url).rstrip("/")
+
+    token: Optional[str] = None
+    workspace: Optional[str] = None
+    try:
+        with httpx.Client(base_url=base, timeout=35.0) as http:
+            start = http.post("/v1/token-flow/start")
+            start.raise_for_status()
+            data = start.json()
+            flow_id = data["flow_id"]
+            url = data.get("url") or f"{base}/token-flow/{flow_id}"
+
+            console.print(
+                "The web browser should have opened for you to authenticate and "
+                "get an API token.\nIf it didn't, please copy this URL into your "
+                f"web browser manually:\n\n  [cyan]{url}[/cyan]\n"
+            )
+            try:
+                webbrowser.open(url)
+            except Exception:
+                pass
+
+            # Each /wait long-polls ~20s server-side; loop until confirmed.
+            deadline = time.monotonic() + 300  # 5 min
+            with console.status("Waiting for web authentication…"):
+                while time.monotonic() < deadline:
+                    resp = http.get(f"/v1/token-flow/{flow_id}/wait", timeout=35.0)
+                    resp.raise_for_status()
+                    body = resp.json()
+                    if body.get("status") == "confirmed" and body.get("token"):
+                        token = body["token"]
+                        workspace = body.get("workspace")
+                        break
+    except httpx.HTTPError as e:
+        err_console.print(f"[red]Could not reach the control plane at {base}[/red]: {e}")
+        raise typer.Exit(code=1)
+
+    if not token:
+        err_console.print(
+            "[red]Timed out waiting for web authentication.[/red] Re-run `blade setup`."
+        )
+        raise typer.Exit(code=1)
+
+    console.print("[green]Web authentication finished successfully![/green]")
+    if workspace:
+        console.print(f"Token is connected to the [bold]{workspace}[/bold] workspace.")
+    path = write_config(token=token, api_url=base)
+    console.print(f"Token written to [bold]{path}[/bold].")
+
+
+# --------------------------------------------------------------------------
+# run
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def run(
+    script: Path = typer.Argument(..., help="Python script defining the app."),
+    no_logs: bool = typer.Option(
+        False, "--no-logs", help="Do not stream logs (just run and report)."
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v",
+        help="Verbose: per-state transition lines instead of the clean running phase.",
+    ),
+):
+    """Execute the script's @app.local_entrypoint, streaming logs live.
+
+    Ctrl-C cancels the remote run(s). If a node is unreachable the run sits in
+    ``cancelling`` and we print "cancellation pending on node".
+    """
+    from ._loader import load_script, select_app_and_entrypoint
+    from ._render import console, err_console, set_verbose
+    from . import _app as app_mod
+    from . import exceptions as exc
+
+    if verbose:
+        set_verbose(True)
+
+    try:
+        client, cfg = _make_client()
+    except typer.Exit:
+        raise
+
+    try:
+        module, module_name, bundle_root = load_script(script)
+        forge_app, entrypoint = select_app_and_entrypoint(module)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+
+    forge_app._bind_client(client)
+    forge_app._set_bundle_context(bundle_root, module_name)
+
+    # Background log streaming for every run this script opens. We start it lazily
+    # once the first run id is known. For simplicity (one function/run is the
+    # common case) we stream the first opened run.
+    import threading
+
+    stop_event = threading.Event()
+    streamed = {"run_id": None}
+
+    def _log_pump():
+        # Wait for a run to be registered, then stream it.
+        while not stop_event.is_set():
+            run_ids = list(app_mod._SESSION.open_run_ids)
+            if run_ids:
+                streamed["run_id"] = run_ids[0]
+                break
+            stop_event.wait(0.1)
+        rid = streamed["run_id"]
+        if not rid or no_logs:
+            return
+        _stream_run_logs(client, rid, stop_event, phase_ui=True)
+
+    log_thread = threading.Thread(target=_log_pump, daemon=True)
+    if not no_logs:
+        log_thread.start()
+
+    exit_code = 0
+    try:
+        result = entrypoint()
+        if result is not None:
+            console.print(f"[green]entrypoint returned:[/green] {result!r}")
+    except KeyboardInterrupt:
+        _on_ctrl_c(client, app_mod._SESSION.open_run_ids)
+        exit_code = 130
+    except exc.RunError as e:
+        # A run that FAILED for an infrastructure reason. Pilot UX fix
+        # (GPU-PILOT-REPORT §"Findings UX additionnels"): show the RunError
+        # (code + message + hint) and exit 1 — never "run cancelled"/130.
+        # RunError is checked BEFORE RunCancelled because RunLostError, etc. are
+        # RunError subclasses and must not be mistaken for a cancellation.
+        _handle_fabric_error(e)
+        exit_code = 1
+    except exc.RunCancelled as e:
+        err_console.print(f"[magenta]run cancelled[/magenta]: {e.run_id}")
+        exit_code = 130
+    except exc.RemoteFunctionError as e:
+        # A remote *user* exception that bubbled out of the entrypoint.
+        # RemoteFunctionError (RemoteError) is a FabricError subclass, so this
+        # must be checked BEFORE the generic FabricError branch or it would
+        # never be reached (first-match except semantics).
+        err_console.print(f"[red]remote function raised:[/red]\n{e}")
+        exit_code = 1
+    except exc.FabricError as e:
+        _handle_fabric_error(e)
+        exit_code = 1
+    except BaseException as e:  # user exception re-raised from remote
+        # When the SDK re-raised the ORIGINAL user exception, the remote
+        # traceback travels on `_forge_remote_traceback` (set by
+        # Function._build_remote_exception). Print it verbatim so the remote
+        # stacktrace reads "as if local" (criterion) — without it the
+        # user would only see `type: message`.
+        remote_tb = getattr(e, "_forge_remote_traceback", None)
+        if remote_tb:
+            err_console.print("[red]remote function raised:[/red]")
+            err_console.print(str(remote_tb).rstrip("\n"), markup=False, highlight=False)
+        else:
+            err_console.print(f"[red]{type(e).__name__}[/red]: {e}")
+        exit_code = 1
+    finally:
+        if exit_code == 0:
+            # Drain hot containers promptly.
+            try:
+                app_mod.complete_session()
+            except exc.FabricError:
+                pass
+        # Let the log pump flush the tail, then stop.
+        if not no_logs:
+            _join_log_thread(log_thread, stop_event)
+        client.close()
+
+    raise typer.Exit(code=exit_code)
+
+
+def _on_ctrl_c(client, run_ids) -> None:
+    """Cancel open runs; report nodes that are unreachable."""
+    from ._render import err_console
+    from . import exceptions as exc
+
+    err_console.print("\n[magenta]Ctrl-C — cancelling remote run(s)…[/magenta]")
+    for run_id in list(run_ids):
+        try:
+            run = client.cancel_run(run_id)
+        except exc.FabricError as e:
+            err_console.print(f"  cancel {run_id}: [red]{e}[/red]")
+            continue
+        state = run.get("state")
+        if state == "cancelling":
+            node_id = run.get("node_id")
+            unreachable = _node_unreachable(client, node_id)
+            if unreachable:
+                err_console.print(
+                    f"  {run_id}: [yellow]cancellation pending on node[/yellow] "
+                    f"(node {node_id} unreachable)"
+                )
+            else:
+                err_console.print(f"  {run_id}: cancelling…")
+        else:
+            err_console.print(f"  {run_id}: {state}")
+
+
+def _node_unreachable(client, node_id: Optional[str]) -> bool:
+    """Is the node holding a cancelling run unreachable? Best effort.
+
+    Degrades quietly by design: this only decorates a cancellation message, and
+    failing the cancel because the decoration could not be fetched would be
+    worse than the message being vague.
+
+    KNOWN GAP, since `GET /v1/nodes/{node_id}` became staff-only: an ordinary
+    user token now gets `403 PERMISSION_DENIED` here, which is swallowed the
+    same as any other FabricError, so the caller prints "cancelling…" even when
+    the node really is unreachable and the cancellation really is stuck. The
+    answer is wrong in the safe direction (it never claims a node IS
+    unreachable), and it is now wrong for EVERY non-staff caller rather than
+    only when the lookup fails. Not redesigned here — telling the two apart
+    means either a per-run node-health field on `GET /v1/runs/{id}` or
+    distinguishing 403 from the rest, and both are their own change.
+    """
+    from . import exceptions as exc
+
+    if not node_id:
+        return False
+    try:
+        node = client._request("GET", f"/v1/nodes/{node_id}")
+    except exc.FabricError:
+        return False
+    return node.get("state") == "unreachable"
+
+
+def _join_log_thread(thread, stop_event) -> None:
+    # Give the stream a moment to deliver the eof event after the run finishes.
+    thread.join(timeout=5.0)
+    stop_event.set()
+    thread.join(timeout=2.0)
+
+
+# --------------------------------------------------------------------------
+# log streaming (shared by `run` and `logs --follow`)
+# --------------------------------------------------------------------------
+
+
+def _stream_run_logs(
+    client, run_id: str, stop_event=None, phase_ui: bool = False
+) -> Optional[str]:
+    """Stream SSE logs + state events until eof. Returns final run state.
+
+    Resilient to disconnects: on a transport error we reconnect from the last
+    seen seq (resume cursor).
+
+    ``phase_ui=True`` (``blade run``, clean mode) renders a braille spinner
+    while the run is pending/scheduled/starting and a resolved
+    ``✓ succeeded (dur)`` / ``✗ failed (dur)`` line at the end, INSTEAD of the
+    per-transition ``[clock] • state`` lines. The user program's stdout/stderr
+    is streamed unchanged in every mode. In verbose mode (or for ``blade logs
+    -f``, which passes ``phase_ui=False``) the classic state-transition feed is
+    kept.
+    """
+    from ._render import (
+        print_log_chunk,
+        print_state_transition,
+        err_console,
+        flush_log_tail,
+        is_verbose,
+        RunProgress,
+    )
+    from ._constants import RUN_TERMINAL_STATES
+    from . import exceptions as exc
+
+    progress = None
+    if phase_ui and not is_verbose():
+        progress = RunProgress(_run_progress_meta(client, run_id), run_id=run_id)
+        progress.start()
+
+    cursor: Optional[int] = None
+    final_state: Optional[str] = None
+
+    try:
+        while stop_event is None or not stop_event.is_set():
+            try:
+                for event, data, event_id in client.stream_logs(run_id, cursor=cursor):
+                    if stop_event is not None and stop_event.is_set():
+                        return final_state
+                    if event == "log":
+                        # The server is trusted, but a truncated SSE chunk on a flaky
+                        # connection can still yield a non-JSON `data:` or a non-numeric
+                        # `id:`. Skip the unreadable event rather than crash the whole
+                        # `blade run` / `blade logs -f` with a raw stacktrace.
+                        try:
+                            chunk = json.loads(data)
+                        except ValueError:
+                            continue
+                        # Retire the spinner before the first user output so it
+                        # never fights the streamed stdout (never suppress it).
+                        if progress is not None:
+                            progress.before_log()
+                        print_log_chunk(chunk)
+                        if isinstance(chunk, dict) and "seq" in chunk:
+                            cursor = chunk["seq"]
+                        elif event_id is not None:
+                            try:
+                                cursor = int(event_id)
+                            except ValueError:
+                                pass
+                    elif event == "state":
+                        try:
+                            payload = json.loads(data)
+                        except ValueError:
+                            continue
+                        final_state = payload.get("state")
+                        if progress is not None:
+                            progress.on_state(final_state)
+                        else:
+                            print_state_transition(final_state, payload.get("ts"))
+                    elif event == "eof":
+                        return final_state
+                    elif event == "ping":
+                        continue
+                # Generator ended without eof (server closed): stop.
+                return final_state
+            except exc.ConnectionFailed:
+                if stop_event is not None and stop_event.is_set():
+                    return final_state
+                # Don't reconnect forever: if the run is already terminal the server
+                # may have closed the socket without an `eof` (e.g. control-plane
+                # restart / proxy drop after the run finished). Without this guard
+                # `blade logs -f <terminal_run>` (stop_event is None) spins at 2 req/s
+                # for ever. `eof` stays the clean terminator; this is the fallback.
+                try:
+                    run = client.get_run(run_id)
+                except exc.FabricError:
+                    run = None
+                if run is not None:
+                    state = run.get("state")
+                    if state in RUN_TERMINAL_STATES:
+                        final_state = state
+                        return state
+                err_console.print("[dim]log stream dropped, reconnecting…[/dim]")
+                import time
+
+                time.sleep(0.5)
+                continue
+            except exc.FabricError as e:
+                raise _handle_fabric_error(e)
+
+        return final_state
+    finally:
+        if progress is not None:
+            progress.finish(final_state)
+        # Emit any residual unterminated line (chunk boundary mid-line) so it
+        # isn't silently dropped once the stream ends.
+        flush_log_tail()
+
+
+def _run_progress_meta(client, run_id: str) -> str:
+    """Best-effort spinner metadata: ``<gpu> · <short run id>``. The 'state'
+    SSE payload carries no resources, so the GPU type comes from one get_run
+    (recon anchor dto.go:65); a failure just drops the GPU part."""
+    from . import exceptions as exc
+
+    short = run_id[:12] + "…" if len(run_id) > 12 else run_id
+    try:
+        run = client.get_run(run_id)
+    except exc.FabricError:
+        return short
+    gpu = (run.get("resources") or {}).get("gpu_type")
+    if gpu and gpu != "none":
+        return f"{gpu} · {short}"
+    return short
+
+
+# --------------------------------------------------------------------------
+# logs
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def logs(
+    run_id: str = typer.Argument(..., help="Run id."),
+    follow: bool = typer.Option(
+        False, "-f", "--follow", help="Stream live until the run finishes."
+    ),
+    since: Optional[int] = typer.Option(
+        None, "--since", help="Resume from this seq (cursor)."
+    ),
+):
+    """Show a run's logs, optionally following live with resume support."""
+    from ._render import print_log_chunk, flush_log_tail, warn_logs_incomplete
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        if follow:
+            _stream_run_logs(client, run_id)
+        else:
+            cursor = since
+            incomplete = False
+            try:
+                while True:
+                    page = client.get_logs(run_id, cursor=cursor)
+                    for chunk in page.get("items", []):
+                        print_log_chunk(chunk)
+                    incomplete = incomplete or bool(page.get("incomplete"))
+                    nxt = page.get("next_cursor")
+                    if nxt is None:
+                        break
+                    cursor = nxt
+            finally:
+                flush_log_tail()
+            if incomplete:
+                warn_logs_incomplete()
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# --------------------------------------------------------------------------
+# status
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def status(run_id: str = typer.Argument(..., help="Run id.")):
+    """Show a run's state; if pending, its position in the scheduler queue."""
+    from ._render import console, style_state, duration_str
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        run = client.get_run(run_id)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    try:
+        state = run.get("state")
+        console.print(f"run     : {run_id}")
+        console.print("state   : ", style_state(state))
+        if run.get("node_id"):
+            console.print(f"node    : {run['node_id']}")
+        res = run.get("resources") or {}
+        console.print(f"gpu     : {res.get('gpu_type', '-')}")
+        console.print(
+            f"duration: {duration_str(run.get('started_at'), run.get('finished_at'))}"
+        )
+        console.print(
+            f"calls   : {run.get('calls_finished', 0)}/{run.get('calls_total', 0)}"
+        )
+        if state == "pending":
+            pos = _queue_position(client, run)
+            if pos is not None:
+                console.print(f"queue   : position {pos} (waiting for capacity)")
+        err = run.get("error")
+        if err:
+            console.print(
+                f"error   : [red]{err.get('code')}[/red]: {err.get('message')}"
+            )
+    finally:
+        client.close()
+
+
+def _queue_position(client, run: dict) -> Optional[int]:
+    """1-based position of this pending run in the FIFO queue.
+
+    The scheduler queue is FIFO by created_at (schema.sql runs_scheduler_queue);
+    position = number of pending runs created at-or-before this one, including
+    itself. ``GET /v1/runs?state=pending`` returns runs most-recent-first; we
+    page through and count those with created_at <= ours.
+    """
+    target_id = run.get("run_id")
+    target_created = run.get("created_at")
+    if not target_created:
+        return None
+    count = 0
+    cursor = None
+    seen_self = False
+    while True:
+        page = client.list_runs(state=["pending"], limit=200, cursor=cursor)
+        for r in page.get("items", []):
+            if r.get("run_id") == target_id:
+                seen_self = True
+            # Count pending runs ahead (created earlier) plus self.
+            if (r.get("created_at") or "") <= target_created:
+                count += 1
+        cursor = page.get("next_cursor")
+        if cursor is None:
+            break
+    if not seen_self:
+        # Run already left the pending queue between get_run and the list.
+        return None
+    return count
+
+
+# --------------------------------------------------------------------------
+# runs (list)
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def runs(
+    state: Optional[list[str]] = typer.Option(
+        None, "--state", help="Filter by state (repeatable)."
+    ),
+    limit: int = typer.Option(50, "--limit", min=1, max=200),
+):
+    """List runs (most recent first)."""
+    from ._render import console, runs_table
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        page = client.list_runs(state=state, limit=limit)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    try:
+        items = page.get("items", [])
+        if not items:
+            console.print("[dim]no runs[/dim]")
+            return
+        console.print(runs_table(items))
+    finally:
+        client.close()
+
+
+# --------------------------------------------------------------------------
+# cancel
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def cancel(run_id: str = typer.Argument(..., help="Run id.")):
+    """Cancel a run."""
+    from ._render import console, err_console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        run = client.cancel_run(run_id)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    try:
+        state = run.get("state")
+        if state == "cancelling" and _node_unreachable(client, run.get("node_id")):
+            err_console.print(
+                f"[yellow]cancellation pending on node[/yellow] "
+                f"(node {run.get('node_id')} unreachable)"
+            )
+        else:
+            console.print(f"[magenta]cancel[/magenta] {run_id}: {state}")
+    finally:
+        client.close()
+
+
+# --------------------------------------------------------------------------
+# admin (PAAS-24): contain-user / force-stop
+# --------------------------------------------------------------------------
+
+
+_FORCE_STOP_KINDS = ("app", "deployment", "run", "sandbox", "map")
+
+
+@admin_app.command("contain-user")
+def admin_contain_user(
+    user_id: str = typer.Argument(..., help="User id (user_…)."),
+    reason: str = typer.Option(
+        "", "--reason", "-r", help="Operator note, recorded in the audit trail."
+    ),
+):
+    """Stop every workload of an account (graceful, then hard): runs, apps,
+    sandboxes and maps. Idempotent; nothing is restarted later.
+
+    This does NOT suspend the account. Suspension is iam's and is done in the
+    backoffice (the account page's Suspend action), which also calls this;
+    AI Fabric contains every account iam lists as suspended on its own within one
+    tick anyway. Use this command to stop an account's workloads now."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        out = client.admin_contain_user(user_id, reason)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+    c = out.get("contained", {})
+    console.print(
+        f"[magenta]contained[/magenta] {user_id}: "
+        f"{c.get('runs_stopped', 0)} run(s), {c.get('apps_stopped', 0)} app(s), "
+        f"{c.get('sandboxes_stopped', 0)} sandbox(es) stopped, "
+        f"{c.get('maps_cancelled', 0)} map(s) cancelled"
+    )
+
+
+@admin_app.command("force-stop")
+def admin_force_stop(
+    kind: str = typer.Argument(..., help="One of: app, deployment, run, sandbox, map."),
+    ref: str = typer.Argument(..., help="Id (or app name) of the workload."),
+):
+    """Force-stop ANY tenant's workload regardless of ownership. Audited."""
+    from ._render import console, err_console
+    from . import exceptions as exc
+
+    if kind not in _FORCE_STOP_KINDS:
+        err_console.print(
+            f"[red]unknown kind[/red] {kind!r}; expected one of {', '.join(_FORCE_STOP_KINDS)}"
+        )
+        raise typer.Exit(2)
+    client, _ = _make_client()
+    try:
+        out = client.admin_force_stop(kind, ref)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+    console.print(f"[magenta]force-stop[/magenta] {kind} {ref}: {out.get('state')}")
+
+
+# --------------------------------------------------------------------------
+# nodes
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def nodes(
+    state: Optional[list[str]] = typer.Option(
+        None, "--state", help="Filter by node state (repeatable)."
+    ),
+):
+    """Fleet view: GPUs free/busy per node (requires a staff session token).
+
+    STAFF ONLY. `GET /v1/nodes` is the whole physical fleet with no tenant
+    predicate — it names every node and, per GPU, the run id holding it, which
+    belongs to whichever tenant is on that GPU. It is gated on the `ops` or
+    `support` staff persona (contracts/admin-route-policy.json); an ordinary
+    user token gets `403 PERMISSION_DENIED`, and a staff `fg_` key
+    `403 INSUFFICIENT_SCOPE` (it carries no compute:admin, PAAS-630).
+
+    Kept as a top-level command rather than moved under `blade admin` (whose
+    help already says "requires a staff SESSION token"): `blade admin` is the
+    containment surface — contain-user, force-stop — and renaming a shipped
+    command is a breaking change for the operators who run this one. The help
+    text carries the requirement instead.
+    """
+    from ._render import console, nodes_table
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        page = client._request(
+            "GET",
+            "/v1/nodes",
+            params={"limit": 200, **({"state": state} if state else {})},
+        )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    try:
+        items = page.get("items", [])
+        if not items:
+            console.print("[dim]no nodes registered[/dim]")
+            return
+        console.print(nodes_table(items))
+    finally:
+        client.close()
+
+
+# --------------------------------------------------------------------------
+# serve (dev loop)
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def serve(script: Path = typer.Argument(..., help="Python script defining the app.")):
+    """Dev loop: run the entrypoint, watch files, hot-reload the bundle (< 5s).
+
+    The run is created with serve=true so its container never drains on idle.
+    Edit a file → the bundle is re-pushed (deduplicated by sha256) and the
+    container reloads the code while keeping the loaded model hot. Ctrl-C stops.
+    """
+    from ._loader import load_script, select_app_and_entrypoint
+    from ._serve import serve as run_serve
+    from . import exceptions as exc
+
+    client, cfg = _make_client()
+    try:
+        module, module_name, bundle_root = load_script(script)
+        forge_app, entrypoint = select_app_and_entrypoint(module)
+    except exc.FabricError as e:
+        client.close()
+        raise _handle_fabric_error(e)
+
+    forge_app._bind_client(client)
+    forge_app._set_bundle_context(bundle_root, module_name)
+    try:
+        code = run_serve(client, forge_app, entrypoint, bundle_root)
+    finally:
+        client.close()
+    raise typer.Exit(code=code)
+
+
+# --------------------------------------------------------------------------
+# deploy / app
+# --------------------------------------------------------------------------
+
+
+def _parse_labels(labels: Optional[list[str]]) -> dict[str, str]:
+    parsed: dict[str, str] = {}
+    for item in labels or []:
+        if "=" not in item:
+            from ._render import err_console
+
+            err_console.print(f"[red]bad label[/red] {item!r} (expected KEY=VALUE)")
+            raise typer.Exit(code=2)
+        k, v = item.split("=", 1)
+        if not k:
+            from ._render import err_console
+
+            err_console.print(f"[red]bad label[/red] {item!r} (empty key)")
+            raise typer.Exit(code=2)
+        parsed[k] = v
+    return parsed
+
+
+def _select_single_app(module):
+    from ._loader import find_apps
+    from . import exceptions as exc
+
+    apps = find_apps(module)
+    if not apps:
+        raise exc.FabricError("no bladekit.App found in script")
+    if len(apps) > 1:
+        raise exc.FabricError(
+            f"multiple bladekit.App objects found ({len(apps)}); deploy expects one"
+        )
+    return apps[0]
+
+
+@app.command()
+def deploy(
+    script: Path = typer.Argument(..., help="Python script defining the app."),
+    label: Optional[list[str]] = typer.Option(
+        None, "--label", help="Deployment label KEY=VALUE (repeatable)."
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v",
+        help="Verbose: raw build steps instead of the clean phase view.",
+    ),
+):
+    """Create a versioned deployment from @app.web_endpoint()/@app.asgi_app().
+
+    Clean mode renders one status line per phase (registering, building,
+    deployed), a gold-arrow line per endpoint route, and an indented dim
+    summary (autoscaling bounds, best-effort cold start). ``--verbose`` keeps
+    the raw build-step stream.
+    """
+    from ._loader import load_script
+    from ._render import phase, print_deployed, result_line, summary_line, set_verbose
+    from rich.text import Text
+    from . import exceptions as exc
+
+    if verbose:
+        set_verbose(True)
+
+    client, _ = _make_client()
+    try:
+        module, module_name, bundle_root = load_script(script)
+        forge_app = _select_single_app(module)
+        forge_app._bind_client(client)
+        forge_app._set_bundle_context(bundle_root, module_name)
+
+        labels = _parse_labels(label)
+        # Resolve the manifest first — this validates endpoints/crons and (if the
+        # image is a bladekit.Image DSL build) emits the `building` phase — before
+        # any app is registered, so a validation error never leaves an orphan app.
+        manifest = forge_app._deployment_manifest(
+            resolve=True,
+            require_endpoints=True,
+            labels=labels or None,
+        )
+
+        gpu = _manifest_gpu(manifest)
+        reg_meta = forge_app.name if not gpu else f"{forge_app.name} ({gpu})"
+        with phase("registering", reg_meta):
+            app_resp = client.create_app(forge_app.name)
+        app_obj = app_resp["app"]
+
+        url_text = Text(app_obj["url"], style="cyan") if app_obj.get("url") else None
+        with phase("deployed", url_text) as ph:
+            deployment = client.create_deployment(
+                app_obj["app_id"], manifest.to_deployment_request()
+            )
+            ph.update(meta=url_text)
+
+        endpoints = deployment.get("endpoints") or []
+        want_coldstart = any(
+            ((e.get("autoscaling") or {}).get("min_replicas") or 0) > 0
+            for e in endpoints
+        )
+        coldstart = (
+            _best_effort_coldstart(client, app_obj["app_id"]) if want_coldstart else None
+        )
+        for endpoint in endpoints:
+            methods = ",".join(endpoint.get("methods") or [])
+            kind = endpoint.get("kind")
+            route = f"{methods} {endpoint.get('path')}".strip()
+            result_line(f"{route}  {kind}" if kind else route)
+            summary = _endpoint_summary(endpoint, coldstart)
+            if summary:
+                summary_line(summary)
+        print_deployed(forge_app.name, deployment.get("version"))
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+def _manifest_gpu(manifest) -> Optional[str]:
+    """The single GPU type shared by every deployment endpoint, or None (mixed
+    or CPU-only) — used for the `registering` phase metadata."""
+    gpus = set()
+    for ep in getattr(manifest, "endpoints", None) or []:
+        gt = (ep.get("resources") or {}).get("gpu_type")
+        if gt and gt != "none":
+            gpus.add(gt)
+    return next(iter(gpus)) if len(gpus) == 1 else None
+
+
+def _endpoint_summary(endpoint: dict, coldstart: Optional[str]) -> str:
+    """Indented dim summary for one endpoint: autoscaling bounds + optional
+    cold start. Only fields actually present are shown (middot-separated)."""
+    a = endpoint.get("autoscaling") or {}
+    parts: list[str] = []
+    lo, hi = a.get("min_replicas"), a.get("max_replicas")
+    if lo is not None and hi is not None:
+        parts.append(f"min {lo} → max {hi}")
+    if a.get("reserved_replicas"):
+        parts.append(f"reserved {a['reserved_replicas']}")
+    if a.get("max_concurrent_inputs"):
+        parts.append(f"concurrency {a['max_concurrent_inputs']}")
+    if coldstart:
+        parts.append(f"cold-start {coldstart}")
+    return " · ".join(parts)
+
+
+def _best_effort_coldstart(client, app_id: str) -> Optional[str]:
+    """Newest cold-start total for an app as e.g. ``0.41s``; None when there is
+    no ready replica yet (the common case right after deploy) or on any error —
+    the cold-start line is optional, never blocking."""
+    try:
+        resp = client.get_app_coldstarts(app_id, limit=1)
+    except Exception:  # noqa: BLE001 — best-effort, optional summary field
+        return None
+    items = (resp or {}).get("items") or []
+    if not items:
+        return None
+    total = ((items[0] or {}).get("phases") or {}).get("total_s")
+    if not isinstance(total, (int, float)):
+        return None
+    return f"{total:.2f}s"
+
+
+def _resolve_app_id(client, name_or_id: str) -> str:
+    from . import exceptions as exc
+
+    if name_or_id.startswith("app_"):
+        return name_or_id
+    page = client.list_apps(name=name_or_id, limit=1)
+    items = page.get("items", [])
+    if not items:
+        raise exc.NotFoundError("APP_NOT_FOUND", f"no app named {name_or_id!r}")
+    return items[0]["app_id"]
+
+
+@app_app.command("list")
+def app_list(
+    state: Optional[str] = typer.Option(None, "--state", help="Filter by state."),
+    limit: int = typer.Option(50, "--limit", min=1, max=200),
+):
+    """List deployed apps."""
+    from rich.table import Table
+    from ._render import console, clock_from_ts
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        page = client.list_apps(state=state, limit=limit)
+        items = page.get("items", [])
+        if not items:
+            console.print("[dim]no apps[/dim]")
+            return
+        table = Table(title="apps", header_style="bold")
+        table.add_column("app_id", overflow="fold")
+        table.add_column("name")
+        table.add_column("state")
+        table.add_column("active_deployment")
+        table.add_column("created")
+        for item in items:
+            table.add_row(
+                item.get("app_id", "-"),
+                item.get("name", "-"),
+                item.get("state", "-"),
+                item.get("active_deployment_id") or "-",
+                clock_from_ts(item.get("created_at")),
+            )
+        console.print(table)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@app_app.command("history")
+def app_history(
+    app_name_or_id: str = typer.Argument(..., help="App name or app_ id."),
+    limit: int = typer.Option(20, "--limit", min=1, max=200),
+):
+    """Show deployment history for an app."""
+    from rich.table import Table
+    from ._render import console, clock_from_ts
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        app_id = _resolve_app_id(client, app_name_or_id)
+        page = client.list_deployments(app_id, limit=limit)
+        items = page.get("items", [])
+        if not items:
+            console.print("[dim]no deployments[/dim]")
+            return
+        table = Table(title="deployments", header_style="bold")
+        table.add_column("deployment_id", overflow="fold")
+        table.add_column("version")
+        table.add_column("state")
+        table.add_column("endpoints")
+        table.add_column("created")
+        for dep in items:
+            table.add_row(
+                dep.get("deployment_id", "-"),
+                str(dep.get("version", "-")),
+                dep.get("state", "-"),
+                str(len(dep.get("endpoints") or [])),
+                clock_from_ts(dep.get("created_at")),
+            )
+        console.print(table)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@app_app.command("rollback")
+def app_rollback(
+    app_name_or_id: str = typer.Argument(..., help="App name or app_ id."),
+    deployment_id: Optional[str] = typer.Option(None, "--deployment-id"),
+    version: Optional[int] = typer.Option(None, "--version", min=1),
+):
+    """Rollback an app to a previous deployment id or version."""
+    from ._render import console, err_console
+    from . import exceptions as exc
+
+    if (deployment_id is None) == (version is None):
+        err_console.print("[red]choose exactly one[/red]: --deployment-id or --version")
+        raise typer.Exit(code=2)
+    client, _ = _make_client()
+    try:
+        app_id = _resolve_app_id(client, app_name_or_id)
+        app_obj = client.rollback_app(
+            app_id, deployment_id=deployment_id, version=version
+        )
+        console.print(
+            f"[green]rolled back[/green] {app_obj.get('name', app_id)} -> "
+            f"{app_obj.get('active_deployment_id') or '-'}"
+        )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@app_app.command("stop")
+def app_stop(app_name_or_id: str = typer.Argument(..., help="App name or app_ id.")):
+    """Stop an app and drain its active deployment replicas."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        app_id = _resolve_app_id(client, app_name_or_id)
+        app_obj = client.stop_app(app_id)
+        console.print(f"[magenta]stopped[/magenta] {app_obj.get('name', app_id)}")
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@app_app.command("scale")
+def app_scale(
+    app_name_or_id: str = typer.Argument(..., help="App name or app_ id."),
+    endpoint: Optional[str] = typer.Option(
+        None, "--endpoint", "-e",
+        help="Endpoint name to scale. Defaults to the only endpoint if there is one.",
+    ),
+    min_replicas: Optional[int] = typer.Option(None, "--min", help="Minimum replicas (0-50)."),
+    max_replicas: Optional[int] = typer.Option(None, "--max", help="Maximum replicas (1-50)."),
+    concurrency: Optional[int] = typer.Option(
+        None, "--concurrency", help="Max concurrent inputs per replica (1-100)."
+    ),
+    idle: Optional[int] = typer.Option(
+        None, "--idle", help="Scale-down idle seconds (30-3600)."
+    ),
+    reserved: Optional[int] = typer.Option(
+        None, "--reserved",
+        help="Hybrid: replicas kept on reserved (always-on); the rest burst on the endpoint's class.",
+    ),
+    target: Optional[int] = typer.Option(
+        None, "--target",
+        help="Autoscaling v2: per-replica concurrency the autoscaler AIMS for (1-100, <= concurrency).",
+    ),
+    buffer: Optional[int] = typer.Option(
+        None, "--buffer",
+        help="Autoscaling v2: warm spare replicas kept while active (0-10; 0 removes the buffer).",
+    ),
+    vllm_waiting: Optional[int] = typer.Option(
+        None, "--vllm-waiting",
+        help="vLLM preset: target requests waiting in vLLM's queue per replica (1-1000; 0 removes the preset; web_server only).",
+    ),
+    clear_policy: bool = typer.Option(
+        False, "--clear-policy",
+        help="Clear the scaling policy entirely (back to default concurrency autoscaling).",
+    ),
+):
+    """Update a deployed endpoint's autoscaling bounds live (no redeploy).
+
+    Only the flags you pass change; the autoscaler applies the new bounds within
+    seconds. Example: blade app scale my-api --min 2 --max 8 --reserved 2
+    (2 always-on reserved replicas, bursting up to 6 more on spot.)
+
+    The v2 policy flags (--target/--buffer/--vllm-waiting) are merged into the
+    endpoint's current policy client-side, then sent as a full replacement.
+    Like every scale edit, they last until the next deploy (code wins).
+    """
+    from ._render import console
+    from . import exceptions as exc
+
+    if (min_replicas is None and max_replicas is None and concurrency is None
+            and idle is None and reserved is None
+            and target is None and buffer is None and vllm_waiting is None
+            and not clear_policy):
+        console.print(
+            "[red]Nothing to change.[/red] Pass at least one of "
+            "--min/--max/--concurrency/--idle/--reserved/--target/--buffer/--vllm-waiting/--clear-policy."
+        )
+        raise typer.Exit(2)
+    if clear_policy and (target is not None or buffer is not None or vllm_waiting is not None):
+        console.print("[red]--clear-policy cannot be combined with --target/--buffer/--vllm-waiting.[/red]")
+        raise typer.Exit(2)
+
+    client, _ = _make_client()
+    try:
+        app_id = _resolve_app_id(client, app_name_or_id)
+        app_obj = client.get_app(app_id)
+        endpoints = (app_obj.get("active_deployment") or {}).get("endpoints") or []
+        if not endpoints:
+            console.print("[red]No active deployment / endpoints to scale.[/red]")
+            raise typer.Exit(1)
+        target_ep = endpoint
+        if target_ep is None:
+            if len(endpoints) == 1:
+                target_ep = endpoints[0]["name"]
+            else:
+                names = ", ".join(e["name"] for e in endpoints)
+                console.print(f"[red]Multiple endpoints[/red] — pass --endpoint <name>: {names}")
+                raise typer.Exit(2)
+
+        # v2 policy: read-modify-write. The server replaces the policy wholesale
+        # (never merges), so the CLI merges the flags into the CURRENT policy.
+        policy: Optional[dict] = None
+        if target is not None or buffer is not None or vllm_waiting is not None:
+            cur = next((e for e in endpoints if e["name"] == target_ep), None)
+            policy = dict(((cur or {}).get("autoscaling") or {}).get("scaling_policy") or {})
+            policy["v"] = 1
+            if target is not None:
+                policy["target_inputs"] = target
+            if buffer is not None:
+                if buffer > 0:
+                    policy["buffer_replicas"] = buffer
+                else:
+                    policy.pop("buffer_replicas", None)
+            if vllm_waiting is not None:
+                if vllm_waiting > 0:
+                    policy["vllm"] = {"target_waiting": vllm_waiting}
+                else:
+                    policy.pop("vllm", None)
+            if set(policy.keys()) == {"v"}:
+                # Everything removed → clear rather than send an empty policy.
+                policy = None
+                clear_policy = True
+
+        updated = client.scale_endpoint(
+            app_id,
+            target_ep,
+            min_replicas=min_replicas,
+            max_replicas=max_replicas,
+            max_concurrent_inputs=concurrency,
+            scale_down_idle_seconds=idle,
+            reserved_replicas=reserved,
+            scaling_policy=policy,
+            clear_scaling_policy=clear_policy,
+        )
+        ep = next(
+            (e for e in (updated.get("active_deployment") or {}).get("endpoints", []) if e["name"] == target_ep),
+            None,
+        )
+        a = ep["autoscaling"] if ep else {}
+        rsv = a.get("reserved_replicas") or 0
+        hybrid = f", reserved {rsv}" if rsv else ""
+        pol = a.get("scaling_policy") or {}
+        extras = ""
+        if pol.get("target_inputs"):
+            extras += f", target {pol['target_inputs']}"
+        if pol.get("buffer_replicas"):
+            extras += f", buffer {pol['buffer_replicas']}"
+        if (pol.get("vllm") or {}).get("target_waiting"):
+            extras += f", vllm-waiting {pol['vllm']['target_waiting']}"
+        console.print(
+            f"[green]scaled[/green] {app_obj.get('name', app_id)} / {target_ep} → "
+            f"replicas {a.get('min_replicas')}-{a.get('max_replicas')}{hybrid}, "
+            f"concurrency {a.get('max_concurrent_inputs')}, idle {a.get('scale_down_idle_seconds')}s{extras}"
+        )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# --------------------------------------------------------------------------
+# volume
+# --------------------------------------------------------------------------
+
+
+@volume_app.command("list")
+def volume_list():
+    """List volumes (generation, size, file count)."""
+    from ._render import console, volumes_table
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        page = client.list_volumes(limit=200)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    try:
+        items = page.get("items", [])
+        if not items:
+            console.print("[dim]no volumes[/dim]")
+            return
+        console.print(volumes_table(items))
+    finally:
+        client.close()
+
+
+def _resolve_volume_id(client, name_or_id: str) -> str:
+    """Accept a volume name or a vol_ id; return the id (404 if unknown name)."""
+    from . import exceptions as exc
+
+    if name_or_id.startswith("vol_"):
+        return name_or_id
+    page = client.list_volumes(name=name_or_id, limit=1)
+    items = page.get("items", [])
+    if not items:
+        raise exc.NotFoundError("VOLUME_NOT_FOUND", f"no volume named {name_or_id!r}")
+    return items[0]["volume_id"]
+
+
+@volume_app.command("put")
+def volume_put(
+    volume: str = typer.Argument(..., help="Volume name or id."),
+    local_path: Path = typer.Argument(..., help="Local file to upload."),
+    remote_path: str = typer.Argument(..., help="Destination path inside the volume."),
+):
+    """Upload a single file into the volume as a new generation (presigned)."""
+    import hashlib
+
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        if not local_path.is_file():
+            console.print(f"[red]not a file[/red]: {local_path}")
+            raise typer.Exit(code=1)
+        data = local_path.read_bytes()
+        sha = hashlib.sha256(data).hexdigest()
+        rel = remote_path.lstrip("/")
+        if ".." in Path(rel).parts:
+            console.print(
+                f"[red]invalid path[/red]: {remote_path!r} — '..' components are not allowed"
+            )
+            raise typer.Exit(code=2)
+        volume_id = _resolve_volume_id(client, volume)
+        body = {
+            "entries": [
+                {"path": rel, "type": "file", "size_bytes": len(data), "sha256": sha}
+            ]
+        }
+        resp = client.create_volume_commit(volume_id, body)
+        commit = resp["commit"]
+        for up in resp.get("missing_uploads", []):
+            if up["sha256"] == sha:
+                client.upload_to_presigned(
+                    up["put_url"], data, "application/octet-stream"
+                )
+        final = client.finalize_volume_commit(volume_id, commit["commit_id"])
+        gen = final.get("generation")
+        console.print(
+            f"[green]put[/green] {rel} → generation {gen} "
+            f"[dim]({len(data)} bytes)[/dim]"
+        )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@volume_app.command("get")
+def volume_get(
+    volume: str = typer.Argument(..., help="Volume name or id."),
+    remote_path: str = typer.Argument(..., help="Path inside the volume."),
+    out: Path = typer.Argument(..., help="Local destination file."),
+    generation: Optional[int] = typer.Option(None, "--generation"),
+):
+    """Download a single file from the volume (presigned)."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        rel = remote_path.lstrip("/")
+        if ".." in Path(rel).parts:
+            from ._render import err_console as _ec
+
+            _ec.print(
+                f"[red]invalid path[/red]: {remote_path!r} — '..' components are not allowed"
+            )
+            raise typer.Exit(code=2)
+        volume_id = _resolve_volume_id(client, volume)
+        info = client.get_volume_file_content(
+            volume_id, rel, generation=generation
+        )
+        data = client.download_presigned(info["get_url"])
+        out.write_bytes(data)
+        console.print(
+            f"[green]got[/green] {remote_path} → {out} [dim]({len(data)} bytes)[/dim]"
+        )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@volume_app.command("ls")
+def volume_ls(
+    volume: str = typer.Argument(..., help="Volume name or id."),
+    path: str = typer.Option("/", "--path", help="Directory to list."),
+    generation: Optional[int] = typer.Option(None, "--generation"),
+):
+    """List entries under a path in the volume (from the manifest)."""
+    from ._render import console, volume_files_table
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        volume_id = _resolve_volume_id(client, volume)
+        page = client.list_volume_files(
+            volume_id, path=path, generation=generation, limit=200
+        )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    try:
+        items = page.get("items", [])
+        console.print(f"[dim]generation {page.get('generation')}[/dim]")
+        if not items:
+            console.print("[dim](empty)[/dim]")
+            return
+        console.print(volume_files_table(items))
+    finally:
+        client.close()
+
+
+@volume_app.command("rm")
+def volume_rm(volume: str = typer.Argument(..., help="Volume name or id.")):
+    """Delete a volume (refused if mounted by an active run: VOLUME_IN_USE)."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        volume_id = _resolve_volume_id(client, volume)
+        client.delete_volume(volume_id)
+        console.print(f"[magenta]deleted[/magenta] volume {volume}")
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# --------------------------------------------------------------------------
+# secret
+# --------------------------------------------------------------------------
+
+
+@secret_app.command("set")
+def secret_set(
+    name: str = typer.Argument(..., help="Secret name."),
+    from_env: Optional[list[str]] = typer.Option(
+        None,
+        "--from-env",
+        help="Read KEY from the environment (repeatable: --from-env HF_TOKEN).",
+    ),
+):
+    """Create or replace a secret. Values come from --from-env or stdin — NEVER argv.
+
+    Reading values from a positional argument would leak them into ``ps``/shell
+    history, so it is intentionally impossible. With no --from-env, the secret is
+    read from stdin as ``KEY=VALUE`` lines (one per line).
+    """
+    import os
+
+    from ._render import console
+    from . import exceptions as exc
+
+    values: dict[str, str] = {}
+    if from_env:
+        for key in from_env:
+            if key not in os.environ:
+                console.print(f"[red]env var not set[/red]: {key}")
+                raise typer.Exit(code=2)
+            values[key] = os.environ[key]
+    else:
+        # Read KEY=VALUE lines from stdin (so the value never appears in argv).
+        if sys.stdin.isatty():
+            console.print(
+                "[dim]reading KEY=VALUE lines from stdin (Ctrl-D to finish)…[/dim]"
+            )
+        for line in sys.stdin:
+            line = line.rstrip("\n")
+            if not line or line.startswith("#"):
+                continue
+            if "=" not in line:
+                console.print(f"[red]bad line[/red] (expected KEY=VALUE): {line!r}")
+                raise typer.Exit(code=2)
+            k, v = line.split("=", 1)
+            values[k.strip()] = v
+    if not values:
+        console.print("[red]no values provided[/red]")
+        raise typer.Exit(code=2)
+
+    client, _ = _make_client()
+    try:
+        secret = client.set_secret(name, values)
+        console.print(
+            f"[green]set[/green] secret {secret['name']} "
+            f"[dim](keys: {', '.join(secret.get('env_keys', []))})[/dim]"
+        )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@secret_app.command("list")
+def secret_list():
+    """List secrets — names and env key names only (never values)."""
+    from ._render import console, secrets_table
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        page = client.list_secrets(limit=200)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    try:
+        items = page.get("items", [])
+        if not items:
+            console.print("[dim]no secrets[/dim]")
+            return
+        console.print(secrets_table(items))
+    finally:
+        client.close()
+
+
+@secret_app.command("rm")
+def secret_rm(name: str = typer.Argument(..., help="Secret name or id.")):
+    """Delete a secret (never blocked; pending runs referencing it will fail)."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        secret_id = name
+        if not name.startswith("scr_"):
+            page = client.list_secrets(name=name, limit=1)
+            items = page.get("items", [])
+            if not items:
+                raise exc.NotFoundError(
+                    "SECRET_NOT_FOUND", f"no secret named {name!r}"
+                )
+            secret_id = items[0]["secret_id"]
+        client.delete_secret(secret_id)
+        console.print(f"[magenta]deleted[/magenta] secret {name}")
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# --------------------------------------------------------------------------
+# image
+# --------------------------------------------------------------------------
+
+
+def _load_image_from_script(module, script: Path):
+    """Return the module-level ``image`` (a ``bladekit.Image``) that ``blade image
+    build`` needs, or a clear :class:`bladekit.FabricError` otherwise.
+
+    Mirrors ``_select_single_app``'s "clear error, not a raw AttributeError/
+    TypeError" pattern so a missing/wrong-type ``image`` hits the standard
+    ``_handle_fabric_error`` rendering like every other script-loading error.
+    """
+    from ._image import Image
+    from . import exceptions as exc
+
+    image_obj = getattr(module, "image", None)
+    if image_obj is None:
+        raise exc.FabricError(
+            f"no module-level `image` found in {script} "
+            "(expected `image = bladekit.Image(...)`)"
+        )
+    if not isinstance(image_obj, Image):
+        raise exc.FabricError(
+            f"`image` in {script} must be a bladekit.Image, got "
+            f"{type(image_obj).__name__}"
+        )
+    return image_obj
+
+
+@image_app.command("build")
+def image_build(
+    script: Path = typer.Argument(
+        ..., help="Python script with a module-level `image = bladekit.Image(...)`."
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Force a fresh build even if a succeeded build for this definition "
+        "hash is already cached. Needed after a catalog base re-pin: the "
+        "definition hash covers the alias, not the resolved digest, so an "
+        "unchanged definition would otherwise dedup to the pre-re-pin build.",
+    ),
+    force_compression: bool = typer.Option(
+        False,
+        "--force-compression",
+        help="Ask the control plane to force zstd recompression of inherited "
+        "layers for this build (admin-authed callers only). Always set by the "
+        "catalog:build:* CI jobs.",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Print a single JSON object to stdout "
+        "({build_id, state, image_ref, definition_hash}) and nothing else — "
+        "for CI to parse. Build logs still stream to stderr.",
+    ),
+):
+    """Build a standalone bladekit.Image, outside of run/deploy.
+
+    Imports <script.py> as a module and requires a module-level `image`
+    attribute (a bladekit.Image). Computes its definition + definition_hash the
+    same way the implicit build path (run/deploy) does, then drives it
+    through POST /v1/images/builds to a terminal state — its own command so
+    CI can build (and promote) catalog base images
+    (docs/specs/phase2-dogfood-catalog-build.md §4b).
+    """
+    from ._build import run_standalone_build
+    from ._loader import load_script
+    from ._render import console, result_line
+    from . import exceptions as exc
+
+    try:
+        module, _module_name, _bundle_root = load_script(script)
+        image_obj = _load_image_from_script(module, script)
+        definition = image_obj.to_definition()
+        definition_hash = image_obj.definition_hash()
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+
+    client, _ = _make_client()
+    try:
+        build = run_standalone_build(
+            client,
+            definition,
+            definition_hash,
+            force=force,
+            force_compression=force_compression,
+            context_data=getattr(image_obj, "_context_data", None),
+        )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+    image_ref = build.get("image_ref")
+    if json_output:
+        # Plain print, not console.print: a rich Console can soft-wrap long
+        # lines to the terminal width, which would corrupt this as JSON once
+        # piped/redirected (the CI case) — stdout must be EXACTLY one
+        # parseable line, nothing else.
+        print(
+            json.dumps(
+                {
+                    "build_id": build.get("build_id"),
+                    "state": build.get("state"),
+                    "image_ref": image_ref,
+                    "definition_hash": build.get("definition_hash", definition_hash),
+                }
+            )
+        )
+        return
+
+    console.print(f"[green]image built[/green] [dim]{definition_hash[:12]}…[/dim]")
+    if image_ref:
+        result_line(image_ref)
+
+
+@image_app.command("list")
+def image_list():
+    """List the image catalogue aliases (maintained images)."""
+    from ._render import console, images_table
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        page = client.list_images(limit=200)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    try:
+        items = page.get("items", [])
+        if not items:
+            console.print("[dim]no image aliases[/dim]")
+            return
+        console.print(images_table(items))
+    finally:
+        client.close()
+
+
+@image_app.command("builds")
+def image_builds(limit: int = typer.Option(50, "--limit", min=1, max=200)):
+    """List recent DSL image builds (state, hash)."""
+    from ._render import console, builds_table
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        page = client.list_image_builds(limit=limit)
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    try:
+        items = page.get("items", [])
+        if not items:
+            console.print("[dim]no builds[/dim]")
+            return
+        console.print(builds_table(items))
+    finally:
+        client.close()
+
+
+@image_app.command("logs")
+def image_logs(
+    build_id: str = typer.Argument(..., help="Image build id (ibld_…)."),
+    follow: bool = typer.Option(False, "-f", "--follow", help="Stream live."),
+):
+    """Show an image build's logs (the failed-build hint points here)."""
+    from ._render import print_log_chunk, flush_log_tail
+    from ._build import _stream_build_logs
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        if follow:
+            _stream_build_logs(client, build_id)
+        else:
+            cursor = None
+            try:
+                while True:
+                    page = client.get_build_logs(build_id, cursor=cursor)
+                    for chunk in page.get("items", []):
+                        print_log_chunk(chunk)
+                    nxt = page.get("next_cursor")
+                    if nxt is None:
+                        break
+                    cursor = nxt
+            finally:
+                flush_log_tail()
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# map commands
+# ---------------------------------------------------------------------------
+
+
+@map_app.command("status")
+def map_status(
+    map_id: str = typer.Argument(..., help="Map invocation ID (map_…)."),
+):
+    """Show the status of a map batch invocation."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        m = client.get_map(map_id)
+        state = m.get("state", "unknown")
+        input_count = m.get("input_count", 0)
+        result_count = m.get("result_count", 0)
+        console.print(f"[bold]{map_id}[/bold]  state=[cyan]{state}[/cyan]")
+        console.print(f"  inputs: {input_count}  completed: {result_count}")
+        if m.get("finalized_at"):
+            console.print(f"  finalized_at: {m['finalized_at']}")
+        if m.get("completed_at"):
+            console.print(f"  completed_at: {m['completed_at']}")
+        if m.get("error"):
+            err = m["error"]
+            console.print(
+                f"  [red]error[/red]: [{err.get('code')}] {err.get('message')}"
+            )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@map_app.command("results")
+def map_results(
+    map_id: str = typer.Argument(..., help="Map invocation ID (map_…)."),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="Resume from cursor."),
+    order: str = typer.Option("index", "--order", help="index or arrival."),
+    return_exceptions: bool = typer.Option(
+        False, "--return-exceptions", help="Yield exceptions instead of raising."
+    ),
+    limit: int = typer.Option(200, "--limit", help="Results per page."),
+):
+    """Stream results from a map batch (or resume from a cursor)."""
+    from ._render import console
+    from ._map import _stream_results
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        for i, result in enumerate(_stream_results(
+            client,
+            map_id,
+            order=order,
+            return_exceptions=return_exceptions,
+            cursor=cursor,
+        )):
+            if isinstance(result, BaseException):
+                console.print(f"[{i}] [red]exception[/red]: {result}")
+            else:
+                console.print(f"[{i}] {result!r}")
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# cron commands
+# ---------------------------------------------------------------------------
+
+
+@cron_app.command("list")
+def cron_list(
+    app_id: str = typer.Argument(..., help="App ID (app_…)."),
+):
+    """List cron schedules for an app."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        resp = client.list_crons(app_id)
+        items = resp.get("items", [])
+        if not items:
+            console.print("[dim]no crons[/dim]")
+            return
+        for c in items:
+            state = c.get("state", "unknown")
+            expr = c.get("cron_expr", "?")
+            cid = c.get("cron_id", "?")
+            console.print(
+                f"[bold]{cid}[/bold]  expr=[cyan]{expr}[/cyan]  state={state}"
+            )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@cron_app.command("history")
+def cron_history(
+    cron_id: str = typer.Argument(..., help="Cron ID (cron_…)."),
+    limit: int = typer.Option(20, "--limit", help="Max executions to show."),
+):
+    """Show recent cron executions."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        resp = client.list_cron_executions(cron_id, limit=limit)
+        items = resp.get("items", [])
+        if not items:
+            console.print("[dim]no executions[/dim]")
+            return
+        for ex in items:
+            eid = ex.get("execution_id", "?")
+            state = ex.get("state", "?")
+            sched = ex.get("scheduled_at", "?")
+            console.print(
+                f"[bold]{eid}[/bold]  scheduled={sched}  state=[cyan]{state}[/cyan]"
+            )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@cron_app.command("trigger")
+def cron_trigger(
+    cron_id: str = typer.Argument(..., help="Cron ID (cron_…)."),
+):
+    """Trigger a one-off cron execution immediately."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        ex = client.trigger_cron(cron_id)
+        eid = ex.get("execution_id", "?")
+        console.print(
+            f"[green]triggered[/green] execution [bold]{eid}[/bold]"
+        )
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# queue commands
+# ---------------------------------------------------------------------------
+
+
+@queue_app.command("len")
+def queue_len(
+    name: str = typer.Argument(..., help="Queue name."),
+):
+    """Show the number of items in a queue."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        resp = client.get_queue(name)
+        console.print(f"[cyan]{name}[/cyan]: {resp.get('len', 0)} items")
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# dict commands
+# ---------------------------------------------------------------------------
+
+
+@dict_app.command("get")
+def dict_get_cmd(
+    name: str = typer.Argument(..., help="Dict name."),
+    key: str = typer.Argument(..., help="Key to retrieve."),
+):
+    """Get a value from a distributed dict."""
+    from ._render import console
+    from ._dict import Dict as DictClass
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        d = DictClass._from_client(name, client)
+        value = d.get(key)
+        if value is None:
+            console.print(f"[dim]key {key!r} not found[/dim]")
+        else:
+            console.print(repr(value))
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@dict_app.command("set")
+def dict_set_cmd(
+    name: str = typer.Argument(..., help="Dict name."),
+    key: str = typer.Argument(..., help="Key to set."),
+    value: str = typer.Argument(..., help="JSON-encoded value."),
+):
+    """Set a value in a distributed dict (value must be JSON)."""
+    from ._render import console
+    from ._dict import Dict as DictClass
+    from . import exceptions as exc
+
+    try:
+        import json as json_mod
+        parsed = json_mod.loads(value)
+    except json.JSONDecodeError as e:
+        from ._render import err_console
+        err_console.print(f"[red]error[/red]: value must be valid JSON: {e}")
+        raise typer.Exit(code=1)
+
+    client, _ = _make_client()
+    try:
+        d = DictClass._from_client(name, client)
+        d.put(key, parsed)
+        console.print(f"[green]ok[/green] set [bold]{key}[/bold]")
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# sandbox commands
+# ---------------------------------------------------------------------------
+
+
+def _fmt_sandbox_row(sb: dict) -> str:
+    """One-line summary for a sandbox object."""
+    sid = sb.get("sandbox_id", "?")
+    state = sb.get("state", "?")
+    rt = sb.get("runtime", "?")
+    image = sb.get("image_alias") or sb.get("image_ref", "?")
+    created = sb.get("created_at", "")[:19].replace("T", " ")
+    # A sealed sandbox looks identical to any other otherwise, and "why can't this
+    # thing resolve anything" is the first question it raises.
+    net = " no-network" if sb.get("block_network") else ""
+    return f"{sid}  {state:<12} {rt:<6} {image:<30} {created}{net}"
+
+
+@sandbox_app.command("list")
+def sandbox_list(
+    state: Optional[str] = typer.Option(
+        None, "--state", help="Filter by state (creating/running/terminating/terminated/failed)."
+    ),
+    limit: int = typer.Option(50, "--limit", min=1, max=200),
+):
+    """List sandboxes (most recent first)."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        states = [state] if state else None
+        page = client.list_sandboxes(state=states, limit=limit)
+        items = page.get("items", [])
+        if not items:
+            console.print("[dim]no sandboxes[/dim]")
+            return
+        console.print(f"{'SANDBOX ID':<32} {'STATE':<12} {'RUNTIME':<6} {'IMAGE':<30} CREATED")
+        console.print("-" * 100)
+        for sb in items:
+            console.print(_fmt_sandbox_row(sb))
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+@sandbox_app.command("terminate")
+def sandbox_terminate(
+    sandbox_id: str = typer.Argument(..., help="Sandbox ID (sb_…)."),
+):
+    """Terminate a running sandbox (SIGTERM -> grace -> SIGKILL)."""
+    from ._render import console
+    from . import exceptions as exc
+
+    client, _ = _make_client()
+    try:
+        client.sandbox_terminate(sandbox_id)
+        console.print(f"[magenta]terminating[/magenta] sandbox {sandbox_id}")
+    except exc.NotFoundError:
+        console.print(f"[yellow]not found[/yellow]: sandbox {sandbox_id} (already gone?)")
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# blade shell — interactive shell inside a sandbox
+# ---------------------------------------------------------------------------
+
+
+@app.command("shell")
+def shell(
+    image: str = typer.Option("fabric/base", "--image", "-i", help="Image alias or ref."),
+    gpu: Optional[str] = typer.Option(None, "--gpu", "-g", help="GPU type (e.g. RTX-A4500)."),
+    runtime: str = typer.Option("runsc", "--runtime", help="Runtime: runsc (default) or runc."),
+    timeout: int = typer.Option(3600, "--timeout", help="Sandbox lifetime in seconds."),
+    block_network: bool = typer.Option(
+        False,
+        "--block-network",
+        help="No network at all: loopback only, no DNS, no Internet (image/volumes still work).",
+    ),
+    cmd: Optional[list[str]] = typer.Argument(None, help="Command to run (default: /bin/bash)."),
+):
+    """Open an interactive shell inside a GPU sandbox.
+
+    Equivalent to: Sandbox.create(...) then exec /bin/bash (or the given cmd).
+    Streams stdin/stdout/stderr interactively via the sandbox exec WebSocket.
+
+    \\b
+      blade shell                       # /bin/bash in a CPU sandbox (runsc)
+      blade shell --gpu RTX-A4500            # GPU sandbox
+      blade shell --runtime runc        # trusted-only debug (runc)
+      blade shell --block-network       # sealed: no Internet from inside
+      blade shell -- python3 script.py  # run a command and stream output
+    """
+    from ._render import err_console
+    from ._sandbox import Sandbox
+    from . import exceptions as exc
+
+    argv = list(cmd) if cmd else ["/bin/bash"]
+
+    client, _ = _make_client()
+
+    try:
+        net = ", network=blocked" if block_network else ""
+        err_console.print(
+            f"[dim]Creating sandbox (image={image!r}, runtime={runtime!r}{net})...[/dim]"
+        )
+        sb = Sandbox.create(
+            image,
+            gpu=gpu,
+            timeout=timeout,
+            runtime=runtime,
+            block_network=block_network,
+            client=client,
+        )
+        err_console.print(f"[dim]Sandbox {sb.sandbox_id} created. Waiting for running...[/dim]")
+        try:
+            sb.wait_for_running(timeout=120.0)
+        except (TimeoutError, exc.SandboxFailedError) as e:
+            err_console.print(f"[red]sandbox failed to start[/red]: {e}")
+            raise typer.Exit(code=1)
+
+        err_console.print(f"[green]Connected[/green] ({sb.sandbox_id}). Type 'exit' to quit.")
+
+        # Use streaming exec for interactive shell
+        proc = sb.exec(*argv, stream=True)
+
+        # Interactive I/O pump: forward local stdin to the WebSocket and print
+        # remote stdout/stderr.  The websockets library is required for streaming.
+        # For simplicity in CI/headless environments, fall back to one-shot mode.
+        if proc.stdin is not None:
+            # Streaming mode: drive stdin from the local terminal in a thread.
+            import threading as _threading
+
+            def _feed_stdin() -> None:
+                import sys as _sys
+                stdin = proc.stdin
+                assert stdin is not None  # guarded by `if proc.stdin is not None`
+                try:
+                    while True:
+                        line = _sys.stdin.readline()
+                        if not line:
+                            stdin.close()
+                            break
+                        stdin.write(line.encode())
+                except Exception:  # noqa: BLE001
+                    try:
+                        stdin.close()
+                    except Exception:  # noqa: BLE001
+                        pass
+
+            feeder = _threading.Thread(target=_feed_stdin, daemon=True)
+            feeder.start()
+
+        # Print stdout/stderr as they arrive.
+        import sys as _sys
+        for chunk in proc.stdout:
+            _sys.stdout.buffer.write(chunk)
+            _sys.stdout.buffer.flush()
+        for chunk in proc.stderr:
+            _sys.stderr.buffer.write(chunk)
+            _sys.stderr.buffer.flush()
+
+        rc = proc.wait(timeout=float(timeout))
+        raise typer.Exit(code=rc)
+
+    except exc.FabricError as e:
+        raise _handle_fabric_error(e)
+    finally:
+        try:
+            sb.terminate()  # type: ignore[possibly-undefined]
+        except Exception:  # noqa: BLE001
+            pass
+        client.close()
+
+
+def main() -> None:  # console_script entry indirection if ever needed
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()