sagex-cli 1.0.0__py3-none-any.whl

sagex/__main__.py

@@ -0,0 +1,2907 @@
+"""sagex entry point.
+
+    sagex                 -> launch the terminal app (TUI)
+    sagex <group> <verb>  -> run one command and exit, e.g. `sagex list workflow`
+
+Typer parses the command line: with no subcommand, the callback launches the TUI;
+otherwise the matching command runs as a plain CLI action. `sagex --help` lists
+every group.
+"""
+
+import json
+import os
+import sys
+import time
+import uuid
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+
+# Windows terminals often default to a legacy code page (cp1252) that can't encode
+# characters like ✓/✗, which would crash typer.echo / Rich mid-output. Force UTF-8
+# so output is safe regardless of the console's codepage.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8")
+    except (AttributeError, ValueError):
+        pass
+
+from sagex import __version__, config, copier, pusher, render, runner, runview
+from sagex.api import ApiClient, ApiError, build_client, resources
+from sagex.api import store
+from sagex.api.client import set_wait_indicator
+from sagex.app import SagexApp
+
+app = typer.Typer(
+    help="sagex — Autosage in your terminal. Run with no command to open the terminal app.",
+    add_completion=False,
+    no_args_is_help=False,          # no args -> run the callback (launch the TUI)
+    # Typer's crash report prints every frame's local variables by default — which
+    # would include the API key (client.api_key) and any secret being prompted for.
+    pretty_exceptions_show_locals=False,
+)
+auth_app = typer.Typer(help="Manage authentication (API key).")
+app.add_typer(auth_app, name="auth")
+
+workspace_app = typer.Typer(help="Manage the local workspace folder.")
+app.add_typer(workspace_app, name="workspace")
+
+show_app = typer.Typer(help="Show a single resource's details in the terminal.")
+app.add_typer(show_app, name="show")
+
+render_app = typer.Typer(help="Render a workflow as a flow tree in the terminal.")
+app.add_typer(render_app, name="render")
+
+list_app = typer.Typer(help="List resources in a compact table.")
+app.add_typer(list_app, name="list")
+
+copy_app = typer.Typer(help="Copy resources to your local workspace.")
+app.add_typer(copy_app, name="copy")
+
+push_app = typer.Typer(help="Push local resource files to the server (create/update).")
+app.add_typer(push_app, name="push")
+
+new_app = typer.Typer(help="Scaffold new local resource files ready to edit and push.")
+app.add_typer(new_app, name="new")
+
+create_app = typer.Typer(help="Create server-side resources (vaults, servers, keys).")
+app.add_typer(create_app, name="create")
+
+update_app = typer.Typer(help="Update server-side resources (vaults, servers, keys).")
+app.add_typer(update_app, name="update")
+
+delete_app = typer.Typer(help="Delete server-side resources (asks for confirmation).")
+app.add_typer(delete_app, name="delete")
+
+trigger_app = typer.Typer(help="Configure workflow triggers (HTTP webhooks and schedules).")
+app.add_typer(trigger_app, name="trigger")
+
+rename_app = typer.Typer(help="Rename a resource (workflow, script, vault, server, key).")
+app.add_typer(rename_app, name="rename")
+
+run_app = typer.Typer(help="Run a script or workflow now and watch it live.")
+app.add_typer(run_app, name="run")
+
+# Lightweight authenticated endpoint used to verify a key.
+_VERIFY_PATH = "/api/users/profile/"
+
+# ---------------------------------------------------------------------------
+# Workflow scaffold template — embedded in files created by `sagex new workflow`.
+# _doc is stripped by workflow_payload() so it's never sent to the server.
+# ---------------------------------------------------------------------------
+_WORKFLOW_TEMPLATE: dict = {
+    "_doc": [
+        "Workflow file created by `sagex new workflow`.",
+        "Edit it, then run: sagex push workflow <this-file>",
+        "Get a full copy-paste snippet for any node/edge with: sagex syntax <kind>",
+        "",
+        "REQUIRED TOP-LEVEL FIELDS",
+        "  name        (string)  display name shown in the web app",
+        "  description (string)  optional free text",
+        "  nodes       (list)    each node needs: id, type, position {x, y}, data",
+        "  edges       (list)    each edge needs: id, source, target",
+        "  (a new file has no 'id' -- push creates the workflow and writes its id back here)",
+        "",
+        "NODE TYPES",
+        "  'trigger'  -- entry point; every workflow needs exactly one.",
+        "               data.type: 'manual' | 'schedule' | 'http'",
+        "",
+        "  'action' + data.type 'script' -- runs a script on a server.",
+        "     data.selectedScript.scriptId    (required) id (string) from `sagex list script`",
+        "     data.selectedScript.type        script kind label, e.g. 'Shell Script'",
+        "     data.vaultDetails.vaultId       (required) id from `sagex list vault`",
+        "     data.vaultDetails.serverId      (required) id from `sagex list server`",
+        "     data.vaultDetails.credentialId  (required) id from `sagex list key`",
+        "     data.executionMode              'remote' (run on the vault's server)",
+        "     data.outputFormat               'json' | 'text'",
+        "     data.parameters[]               {id, name, type, value, sourceType, description}",
+        "                                     sourceType 'manual' = literal; 'output' = {{node-id.output.key}}",
+        "                                     type: string | number | boolean | password",
+        "     data.jsonSchema[]               {name, type} -- declares this script's output fields",
+        "",
+        "  'action' + data.type 'email' -- sends an email.",
+        "     data.smtpConfig.{host, port, vaultId, credentialId}  (required; credential = username_password)",
+        "     data.smtpConfig.secure          true to use TLS",
+        "     data.to (list) and data.subject (string)             (required)",
+        "     data.from / data.cc / data.bcc / data.body           (optional)",
+        "",
+        "  'decision' -- conditional branch; needs exactly 2 outgoing edges.",
+        "     data.conditions[]   {id, field, operator, value, fieldSource, valueSource}",
+        "                         operator e.g. '==' / '!=';  *Source: 'output' ({{...}}) or 'manual'",
+        "     data.trueLabel      list of node ids taken when conditions pass",
+        "     data.falseLabel     list of node ids taken otherwise",
+        "     Its two edges must carry sourceHandle: 'true' and 'false'.",
+        "",
+        "EDGES",
+        "  {id, source, target} connect nodes; type 'smoothstep' + style are UI hints.",
+        "  A decision node's two edges also need sourceHandle 'true' / 'false'.",
+        "",
+        "CREATE vs UPDATE",
+        "  No 'id' field  -> push creates a new workflow and writes the id back here.",
+        "  Has 'id' field -> push updates that workflow (asks for confirmation).",
+        "  Wrong/stale id -> server returns 404; re-run push with --new to force-create.",
+    ],
+    "name": "",
+    "description": "",
+    "nodes": [
+        {
+            "id": "trigger-1",
+            "type": "trigger",
+            "position": {"x": 0, "y": 200},
+            "data": {"type": "manual", "label": "Manual Trigger", "description": ""},
+            "measured": {"width": 160, "height": 160},
+        },
+        {
+            "id": "action-1",
+            "type": "action",
+            "position": {"x": 250, "y": 200},
+            "data": {
+                "type": "script",
+                "label": "Run Script",
+                "description": "",
+                "executionMode": "remote",
+                "outputFormat": "json",
+                "selectedScript": {"type": "Shell Script", "scriptId": "REPLACE_WITH_SCRIPT_ID"},
+                "vaultDetails": {
+                    "vaultId": "REPLACE_WITH_VAULT_ID",
+                    "serverId": "REPLACE_WITH_SERVER_ID",
+                    "credentialId": "REPLACE_WITH_CREDENTIAL_ID",
+                },
+                "parameters": [],
+                "jsonSchema": [],
+            },
+            "measured": {"width": 275, "height": 102},
+        },
+    ],
+    "edges": [
+        {
+            "id": "xy-edge__trigger-1-action-1",
+            "type": "smoothstep",
+            "source": "trigger-1",
+            "target": "action-1",
+            "style": {"stroke": "#9CA3AF", "strokeWidth": 2},
+        }
+    ],
+}
+
+
+# Snippets mirror the web app's export shape (see a real export for reference).
+# ids/values are placeholders; REPLACE_WITH_* markers are the ones you must fill in.
+_SYNTAX_SNIPPETS: dict[str, object] = {
+    "trigger": {
+        "id": "trigger-1",
+        "type": "trigger",
+        "position": {"x": 0, "y": 200},
+        "data": {"type": "manual", "label": "Manual Trigger", "description": ""},
+        "measured": {"width": 160, "height": 160},
+    },
+    "script": {
+        "id": "action-1",
+        "type": "action",
+        "position": {"x": 250, "y": 200},
+        "data": {
+            "type": "script",
+            "label": "Run Script",
+            "description": "",
+            "executionMode": "remote",
+            "outputFormat": "json",
+            "selectedScript": {"type": "Shell Script", "scriptId": "REPLACE_WITH_SCRIPT_ID"},
+            "vaultDetails": {
+                "vaultId": "REPLACE_WITH_VAULT_ID",
+                "serverId": "REPLACE_WITH_SERVER_ID",
+                "credentialId": "REPLACE_WITH_CREDENTIAL_ID",
+            },
+            "parameters": [
+                {
+                    "id": "param-1",
+                    "name": "SERVICE_NAME",
+                    "type": "string",
+                    "value": "nginx",
+                    "sourceType": "manual",
+                    "description": "",
+                }
+            ],
+            "jsonSchema": [
+                {"name": "service_name", "type": "string"},
+                {"name": "status", "type": "string"},
+            ],
+        },
+        "measured": {"width": 275, "height": 102},
+    },
+    "email": {
+        "id": "action-1",
+        "type": "action",
+        "position": {"x": 250, "y": 200},
+        "data": {
+            "type": "email",
+            "label": "Send Email",
+            "description": "",
+            "from": "sender@example.com",
+            "to": ["recipient@example.com"],
+            "cc": [],
+            "bcc": [],
+            "subject": "Subject here",
+            "body": "Email body here.",
+            "smtpConfig": {
+                "host": "smtp.gmail.com",
+                "port": 587,
+                "secure": False,
+                "vaultId": "REPLACE_WITH_VAULT_ID",
+                "credentialId": "REPLACE_WITH_CREDENTIAL_ID",
+            },
+        },
+        "measured": {"width": 185, "height": 102},
+    },
+    "decision": {
+        "id": "decision-1",
+        "type": "decision",
+        "position": {"x": 500, "y": 200},
+        "data": {
+            "label": "Condition Check",
+            "description": "",
+            "conditions": [
+                {
+                    "id": "cond-1",
+                    "field": "{{action-1.output.exists}}",
+                    "value": "true",
+                    "operator": "==",
+                    "fieldSource": "output",
+                    "valueSource": "manual",
+                }
+            ],
+            "trueLabel": ["action-on-true"],
+            "falseLabel": ["action-on-false"],
+        },
+        "measured": {"width": 160, "height": 160},
+    },
+    "edge": {
+        "id": "xy-edge__source-target",
+        "type": "smoothstep",
+        "source": "source-node-id",
+        "target": "target-node-id",
+        "style": {"stroke": "#9CA3AF", "strokeWidth": 2},
+    },
+    "decision-edge": [
+        {
+            "id": "decision-1-action-on-true-true",
+            "type": "smoothstep",
+            "label": "True",
+            "source": "decision-1",
+            "target": "action-on-true",
+            "sourceHandle": "true",
+            "style": {"stroke": "#10b981", "strokeWidth": 2},
+        },
+        {
+            "id": "decision-1-action-on-false-false",
+            "type": "smoothstep",
+            "label": "False",
+            "source": "decision-1",
+            "target": "action-on-false",
+            "sourceHandle": "false",
+            "style": {"stroke": "#ef4444", "strokeWidth": 2},
+        },
+    ],
+}
+
+_SYNTAX_NOTES: dict[str, list[str]] = {
+    "trigger": [
+        "Entry point — exactly one per workflow. Required: id, type, position, data.type, data.label.",
+        "data.type: 'manual' | 'schedule' | 'http' (schedule/http need their trigger settings from the web app).",
+    ],
+    "script": [
+        "Action that runs a script on a server.",
+        "Required: selectedScript.scriptId, vaultDetails.{vaultId, serverId, credentialId}.",
+        "parameters[].sourceType: 'manual' (literal value) or 'output' (value is a {{node-id.output.key}} reference).",
+        "parameters[].type: string | number | boolean | password.   outputFormat: 'json' | 'text'.",
+        "jsonSchema declares this script's outputs so later nodes can read {{this-id.output.<name>}}.",
+    ],
+    "email": [
+        "Action that sends an email.",
+        "Required: smtpConfig.{host, port, vaultId, credentialId}, subject, to[].",
+        "credentialId must be a username_password credential. from / cc / bcc / body are optional.",
+    ],
+    "decision": [
+        "Branch node — needs exactly 2 outgoing edges (see: sagex syntax decision-edge).",
+        "conditions[].operator is a comparison such as '==' or '!=' (see the web condition editor for the full set).",
+        "conditions[].fieldSource / valueSource: 'output' (a {{...}} reference) or 'manual' (a literal).",
+        "trueLabel / falseLabel list the target node ids taken on each branch.",
+    ],
+    "edge": [
+        "Connection between two nodes. Required: id, source, target.",
+        "type ('smoothstep') and style are UI hints — safe to keep as-is.",
+    ],
+    "decision-edge": [
+        "The two required edges out of a decision node.",
+        "sourceHandle 'true'/'false' is mandatory; label and coloured style match the web app.",
+    ],
+}
+
+_SYNTAX_KINDS = " | ".join(_SYNTAX_SNIPPETS)
+
+
+def _version_callback(value: bool) -> None:
+    """Print the version and exit (an 'eager' option, handled before anything else)."""
+    if value:
+        typer.echo(f"sagex {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def _default(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """Launch the terminal app when no subcommand is given."""
+    if ctx.invoked_subcommand is None:
+        SagexApp().run()               # the TUI shows its own loaders, never the CLI line
+    else:
+        set_wait_indicator(render.waiting)
+
+
+@app.command("syntax")
+def syntax_cmd(
+    kind: str = typer.Argument(..., help=f"Snippet to print: {_SYNTAX_KINDS}"),
+) -> None:
+    """Print a ready-to-copy JSON snippet for a workflow node or edge.
+
+    Paste the output into your workflow file's 'nodes' or 'edges' array,
+    then replace the TODO placeholders with real ids and values.
+
+    Run `sagex list script` / `sagex list vault` to find the ids you need.
+    """
+    snippet = _SYNTAX_SNIPPETS.get(kind)
+    if snippet is None:
+        typer.echo(f"✗ Unknown kind '{kind}'. Choose one of: {_SYNTAX_KINDS}")
+        raise typer.Exit(code=1)
+    for line in _SYNTAX_NOTES.get(kind, []):
+        render.note(f"# {line}")
+    typer.echo(json.dumps(snippet, indent=2))
+
+
+@auth_app.command("login")
+def auth_login() -> None:
+    """Log in with your sagex API key (paste it when prompted)."""
+    render.note(f"sagex is in early access — API keys are issued on request: {config.WEB_URL}/contact")
+    key = typer.prompt("Paste your sagex API key", hide_input=True).strip()
+    if not key:
+        typer.echo("No key entered.")
+        raise typer.Exit(code=1)
+    if not key.startswith("sgx_"):
+        typer.echo("✗ That doesn't look like a sagex API key (they start with sgx_).")
+        raise typer.Exit(code=1)
+
+    # Verify BEFORE storing, so a mistyped or revoked key never lands in the keychain.
+    # Only a 401/403 proves the key is bad; if the server is down we can't tell, so
+    # save it anyway and say it's unverified.
+    problem = None
+    try:
+        ApiClient(config.api_url(), key).get(_VERIFY_PATH)
+    except ApiError as exc:
+        if exc.status in (401, 403):
+            typer.echo("✗ That key wasn't accepted — check you pasted all of it, or request a new one.")
+            raise typer.Exit(code=1)
+        problem = exc.message
+
+    try:
+        store.set_key(key)
+    except store.KeyStoreError:
+        typer.echo("✗ No OS keychain is available on this machine to store the key.")
+        typer.echo(f"  Set it in your environment instead:  {store.ENV_VAR}=<your key>")
+        raise typer.Exit(code=1)
+
+    if problem:
+        typer.echo("Key saved to your OS keychain, but it couldn't be verified right now:")
+        typer.echo(f"  {problem}")
+    else:
+        typer.echo("✓ Logged in — key saved to your OS keychain.")
+    if store.key_from_env():
+        render.note(f"{store.ENV_VAR} is set in your environment and takes precedence over the saved key.")
+
+
+@auth_app.command("status")
+def auth_status() -> None:
+    """Show whether you're logged in, and check the key still works."""
+    key = store.get_key()
+    if not key:
+        typer.echo("Not logged in. Run:  sagex auth login")
+        raise typer.Exit(code=1)
+
+    client = build_client()
+    try:
+        client.get(_VERIFY_PATH)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+
+    # Name the server only when it isn't the hosted one (i.e. a SAGEX_API_URL override).
+    where = "" if client.base_url == config.DEFAULT_API_URL else f" at {client.base_url}"
+    source = f" via {store.ENV_VAR}" if store.key_from_env() else ""
+    typer.echo(f"✓ Logged in to Autosage{where} · key sgx_…{key[-4:]}{source}")
+
+
+@auth_app.command("logout")
+def auth_logout() -> None:
+    """Remove the stored API key from your OS keychain."""
+    store.delete_key()
+    typer.echo("Logged out — API key removed from your OS keychain.")
+    if store.key_from_env():
+        render.note(f"{store.ENV_VAR} is still set in your environment, so sagex will keep using it.")
+
+
+@workspace_app.command("set")
+def workspace_set(path: str) -> None:
+    """Set the local workspace folder (relative or absolute path)."""
+    try:
+        resolved = config.resolve_workspace(path)
+    except ValueError as exc:
+        typer.echo(str(exc))
+        raise typer.Exit(code=1)
+    settings = config.load()
+    settings["workspace"] = resolved
+    config.save(settings)
+    typer.echo(f"Workspace set to: {resolved}")
+
+
+@workspace_app.command("show")
+def workspace_show() -> None:
+    """Show the current workspace folder."""
+    ws = config.load().get("workspace")
+    typer.echo(ws or "(not set — defaults to the current directory)")
+
+
+def _client_or_exit() -> "build_client":
+    """Return an API client, or exit early with a friendly message if no key."""
+    if not store.get_key():
+        typer.echo("Not logged in. Run:  sagex auth login")
+        raise typer.Exit(code=1)
+    return build_client()
+
+
+def _resolve_or_exit(resolve, client, ref: str, kind: str):
+    """Run a resolver, turning its expected errors into clean CLI exits."""
+    try:
+        return resolve(client, ref)
+    except resources.AmbiguousResource as exc:
+        render.ambiguous(exc)
+        raise typer.Exit(code=1)
+    except resources.ResourceNotFound as exc:
+        typer.echo(str(exc))
+        raise typer.Exit(code=1)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+
+
+# ---------------------------------------------------------------------------
+# Credential (key) input helpers. Secrets are entered interactively (hidden) or
+# read from an existing file; they are NEVER accepted as flag values (which would
+# leak into shell history / ps) and are NEVER written to disk by us.
+# ---------------------------------------------------------------------------
+
+_KEY_TYPES = {
+    "username_password": "username_password", "up": "username_password",
+    "user": "username_password", "password": "username_password",
+    "ssh_key": "ssh_key", "ssh": "ssh_key", "key": "ssh_key",
+    "certificate": "certificate", "cert": "certificate",
+}
+_KEY_TYPE_CHOICES = "username_password | ssh_key | certificate"
+
+
+def _normalize_key_type(value: str) -> str:
+    """Map a user-supplied --type (incl. aliases like 'ssh'/'cert') to a server value."""
+    ctype = _KEY_TYPES.get(value.strip().lower())
+    if not ctype:
+        typer.echo(f"✗ --type must be one of: {_KEY_TYPE_CHOICES}.")
+        raise typer.Exit(code=1)
+    return ctype
+
+
+def _prompt_secret(label: str, *, confirm: bool) -> str:
+    """Prompt for a single-line secret with hidden input (optionally confirmed)."""
+    return typer.prompt(label, hide_input=True, confirmation_prompt=confirm)
+
+
+def _prompt_optional_secret(label: str) -> str:
+    """Prompt for an optional single-line secret (hidden); '' if left blank."""
+    return typer.prompt(label, hide_input=True, default="", show_default=False)
+
+
+def _read_secret_file(path_str: str) -> str:
+    """Read a multi-line secret (key/cert) from an existing file. Never written back."""
+    p = Path(path_str).expanduser()
+    if not p.is_file():
+        typer.echo(f"✗ No such file: {p}")
+        raise typer.Exit(code=1)
+    try:
+        return p.read_text(encoding="utf-8")
+    except OSError as exc:
+        typer.echo(f"✗ Couldn't read {p}: {exc}")
+        raise typer.Exit(code=1)
+
+
+def _paste_secret(label: str) -> str:
+    """Read a multi-line secret pasted into the terminal, ended with EOF."""
+    typer.echo(f"  Paste the {label}, then press Ctrl-D (Ctrl-Z then Enter on Windows) on a blank line:")
+    return sys.stdin.read()
+
+
+def _acquire_multiline(label: str, file_opt: str | None, *, paste_when_none: bool) -> str | None:
+    """Get a multi-line secret from a file path, from '-' (paste), or by paste.
+
+    file_opt: a path, or '-' to paste, or None. When None: paste if paste_when_none
+    (the create flow), else return None (the update flow — leave the field unchanged).
+    """
+    if file_opt == "-":
+        content = _paste_secret(label)
+    elif file_opt:
+        content = _read_secret_file(file_opt)
+    elif paste_when_none:
+        content = _paste_secret(label)
+    else:
+        return None
+    if not content.strip():
+        typer.echo(f"✗ {label} is empty.")
+        raise typer.Exit(code=1)
+    return content
+
+
+@show_app.command("workflow")
+def show_workflow_cmd(
+    ref: str = typer.Argument(..., help="Workflow name or id."),
+    json_out: bool = typer.Option(False, "--json", help="Print the raw record as JSON."),
+) -> None:
+    """Show a workflow's details (including its nodes and edges). Use `sagex render` for the flow tree."""
+    client = _client_or_exit()
+    wf = _resolve_or_exit(resources.resolve_workflow, client, ref, "workflow")
+    render.print_json(wf) if json_out else render.workflow(wf)
+
+
+@render_app.command("workflow")
+def render_workflow_cmd(
+    ref: str = typer.Argument(None, help="Workflow name or id (omit when using --file)."),
+    file: str = typer.Option(None, "--file", "-f", help="Render a local file: a path, or a name under <workspace>/workflows/."),
+) -> None:
+    """Render a workflow's flow as boxed nodes + edges. Works on a local file too (--file)."""
+    if file:
+        workspace = Path(config.workspace_dir())
+        try:
+            path = pusher.resolve_workflow_file(workspace, file)
+        except pusher.WorkflowFileNotFound as exc:
+            typer.echo(f"No workflow file for '{exc.ref}'. Looked at:")
+            for p in exc.looked:
+                typer.echo(f"  {p}")
+            raise typer.Exit(code=1)
+        try:
+            wf = pusher.load_doc(path)
+        except ValueError as exc:
+            typer.echo(f"✗ {exc}")
+            raise typer.Exit(code=1)
+    else:
+        if not ref:
+            typer.echo("Give a workflow name/id, or pass --file <path-or-name>.")
+            raise typer.Exit(code=1)
+        client = _client_or_exit()
+        wf = _resolve_or_exit(resources.resolve_workflow, client, ref, "workflow")
+    render.workflow_graph(wf)
+
+
+@show_app.command("script")
+def show_script_cmd(
+    ref: str = typer.Argument(..., help="Script name or id."),
+    json_out: bool = typer.Option(False, "--json", help="Print the raw record as JSON."),
+    no_content: bool = typer.Option(False, "--no-content", help="Skip the code body."),
+) -> None:
+    """Show a script's metadata and (by default) its code, syntax-highlighted."""
+    client = _client_or_exit()
+    meta = _resolve_or_exit(resources.resolve_script, client, ref, "script")
+    if json_out:
+        render.print_json(meta)
+        return
+    content = None
+    if not no_content:
+        try:
+            content = resources.get_script_content(client, meta["id"])
+        except ApiError as exc:
+            typer.echo(f"(couldn't load code body: {exc.message})")   # still show metadata
+    render.script(meta, content)
+
+
+@show_app.command("run")
+def show_run_cmd(
+    ref: str = typer.Argument(..., help="Run id (or an id prefix)."),
+    json_out: bool = typer.Option(False, "--json", help="Print the raw record as JSON."),
+    logs: bool = typer.Option(False, "--logs", help="Also download and print each node's stdout/stderr."),
+) -> None:
+    """Show a run's status and per-node results (and optionally its logs)."""
+    client = _client_or_exit()
+    run = _resolve_or_exit(resources.resolve_run, client, ref, "run")
+    if json_out:
+        render.print_json(run)
+        return
+
+    nodes: list = []
+    try:
+        nodes = resources.get_run_nodes(client, run["id"])
+    except ApiError as exc:
+        typer.echo(f"(couldn't load node results: {exc.message})")
+
+    render.run(run, nodes)
+
+    # Logs live in GCS behind signed URLs and are swept after ~90 days; the server
+    # tells us via `logs_expired` on any node (it's keyed off the run's age).
+    if any(n.get("logs_expired") for n in nodes):
+        render.note("Logs are not available for this run — we keep logs for 90 days.")
+    elif logs:
+        entries = []
+        for n in nodes:
+            label = n.get("node_label") or n.get("node_id") or "node"
+            for stream in ("stdout", "stderr"):
+                url = n.get(f"{stream}_signed_url")
+                if url:
+                    try:
+                        text = resources.fetch_log_text(url)
+                    except ApiError as exc:
+                        text = f"({exc.message})"
+                    entries.append((label, stream, text))
+        render.run_logs(entries)
+    elif any(n.get("stdout_signed_url") or n.get("stderr_signed_url") for n in nodes):
+        render.note("Logs available — pass --logs to print them.")
+
+
+@show_app.command("trigger")
+def show_trigger_cmd(
+    ref: str = typer.Argument(..., help="Trigger id or workflow name."),
+    json_out: bool = typer.Option(False, "--json", help="Print the raw record as JSON."),
+) -> None:
+    """Show a trigger's detail (schedule or HTTP). Never prints the full secret."""
+    client = _client_or_exit()
+    kind, detail = _resolve_or_exit(resources.resolve_trigger, client, ref, "trigger")
+    render.print_json(detail) if json_out else render.trigger(kind, detail)
+
+
+@show_app.command("key")
+def show_key_cmd(
+    ref: str = typer.Argument(..., help="Credential (key) id or name."),
+    reveal: bool = typer.Option(False, "--reveal", help="Fetch and display the secret values (asks first)."),
+) -> None:
+    """Show a vault credential. Secrets stay hidden unless you pass --reveal."""
+    client = _client_or_exit()
+    cred = _resolve_or_exit(resources.resolve_credential, client, ref, "key")
+
+    secrets = None
+    if reveal:
+        name = cred.get("name") or cred.get("id")
+        if not typer.confirm(f"Reveal plaintext secrets for '{name}'? They will be printed here."):
+            typer.echo("Aborted — secrets not fetched.")
+            raise typer.Exit(code=1)
+        try:
+            secrets = resources.reveal_credential(client, cred["id"])
+        except ApiError as exc:
+            typer.echo(f"✗ {exc.message}")
+            raise typer.Exit(code=1)
+    render.credential(cred, secrets)
+
+
+@show_app.command("server")
+def show_server_cmd(
+    ref: str = typer.Argument(..., help="Server id or name."),
+    json_out: bool = typer.Option(False, "--json", help="Print the raw record as JSON."),
+) -> None:
+    """Show a vault server (host, connection method, linked credential, vault)."""
+    client = _client_or_exit()
+    server = _resolve_or_exit(resources.resolve_server, client, ref, "server")
+    render.print_json(server) if json_out else render.server(server)
+
+
+@show_app.command("vault")
+def show_vault_cmd(
+    ref: str = typer.Argument(..., help="Vault id or name."),
+    json_out: bool = typer.Option(False, "--json", help="Print the raw record as JSON."),
+) -> None:
+    """Show a vault and the credentials and servers it contains."""
+    client = _client_or_exit()
+    vault = _resolve_or_exit(resources.resolve_vault, client, ref, "vault")
+    render.print_json(vault) if json_out else render.vault(vault)
+
+
+def _list_or_exit(fn, client, **kwargs):
+    """Call a list_*_full function and return items, or exit on ApiError."""
+    try:
+        return fn(client, **kwargs)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+
+
+@list_app.command("workflow")
+def list_workflow_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Print raw JSON."),
+) -> None:
+    """List all workflows."""
+    client = _client_or_exit()
+    items = _list_or_exit(resources.list_workflows_full, client)
+    render.print_json(render.slim_items(items, "workflow")) if json_out else render.list_workflows(items)
+
+
+@list_app.command("script")
+def list_script_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Print raw JSON."),
+) -> None:
+    """List all scripts."""
+    client = _client_or_exit()
+    items = _list_or_exit(resources.list_scripts_full, client)
+    render.print_json(render.slim_items(items, "script")) if json_out else render.list_scripts(items)
+
+
+@list_app.command("run")
+def list_run_cmd(
+    limit: int = typer.Option(20, "--limit", help="Max runs to show (newest first)."),
+    json_out: bool = typer.Option(False, "--json", help="Print raw JSON."),
+) -> None:
+    """List recent runs, newest first."""
+    client = _client_or_exit()
+    items = _list_or_exit(resources.list_runs_full, client, limit=limit)
+    render.print_json(render.slim_items(items, "run")) if json_out else render.list_runs(items)
+
+
+@list_app.command("trigger")
+def list_trigger_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Print raw JSON."),
+) -> None:
+    """List all configured triggers."""
+    client = _client_or_exit()
+    items = _list_or_exit(resources.list_triggers_full, client)
+    render.print_json(render.slim_items(items, "trigger")) if json_out else render.list_triggers(items)
+
+
+@list_app.command("key")
+def list_key_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Print raw JSON."),
+) -> None:
+    """List all vault credentials (no secrets shown)."""
+    client = _client_or_exit()
+    items = _list_or_exit(resources.list_credentials_full, client)
+    render.print_json(render.slim_items(items, "credential")) if json_out else render.list_credentials(items)
+
+
+@list_app.command("server")
+def list_server_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Print raw JSON."),
+) -> None:
+    """List all vault servers."""
+    client = _client_or_exit()
+    items = _list_or_exit(resources.list_servers_full, client)
+    render.print_json(render.slim_items(items, "server")) if json_out else render.list_servers(items)
+
+
+@list_app.command("vault")
+def list_vault_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Print raw JSON."),
+) -> None:
+    """List all vaults."""
+    client = _client_or_exit()
+    items = _list_or_exit(resources.list_vaults_full, client)
+    render.print_json(render.slim_vaults(items)) if json_out else render.list_vaults(items)
+
+
+def _wrote(paths) -> None:
+    """Report the files a copy command wrote (one dim line each)."""
+    for p in paths:
+        render.note(f"  wrote {p}")
+
+
+@copy_app.command("workflow")
+def copy_workflow_cmd(
+    ref: str = typer.Argument(None, help="Workflow name or id (omit with --all)."),
+    all_: bool = typer.Option(False, "--all", help="Copy every workflow."),
+) -> None:
+    """Copy a workflow (or all) as JSON to <workspace>/workflows/."""
+    client = _client_or_exit()
+    workspace = Path(config.workspace_dir())
+    if all_:
+        try:
+            paths = copier.copy_all_workflows(client, workspace)
+        except ApiError as exc:
+            typer.echo(f"✗ {exc.message}"); raise typer.Exit(code=1)
+        _wrote(paths)
+        render.note(f"Copied {len(paths)} workflow(s) to {workspace / 'workflows'}")
+        return
+    if not ref:
+        typer.echo("Give a workflow name/id, or pass --all."); raise typer.Exit(code=1)
+    wf = _resolve_or_exit(resources.resolve_workflow, client, ref, "workflow")
+    _wrote([copier.copy_workflow(workspace, wf)])
+
+
+@copy_app.command("script")
+def copy_script_cmd(
+    ref: str = typer.Argument(None, help="Script name or id (omit with --all)."),
+    all_: bool = typer.Option(False, "--all", help="Copy every script."),
+) -> None:
+    """Copy a script's code (or all) to <workspace>/scripts/."""
+    client = _client_or_exit()
+    workspace = Path(config.workspace_dir())
+    if all_:
+        try:
+            paths = copier.copy_all_scripts(client, workspace)
+        except ApiError as exc:
+            typer.echo(f"✗ {exc.message}"); raise typer.Exit(code=1)
+        _wrote(paths)
+        render.note(f"Copied {len(paths)} script(s) to {workspace / 'scripts'}")
+        return
+    if not ref:
+        typer.echo("Give a script name/id, or pass --all."); raise typer.Exit(code=1)
+    meta = _resolve_or_exit(resources.resolve_script, client, ref, "script")
+    try:
+        content = resources.get_script_content(client, meta["id"])
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}"); raise typer.Exit(code=1)
+    _wrote([copier.copy_script(workspace, meta, content)])
+
+
+@copy_app.command("run")
+def copy_run_cmd(
+    ref: str = typer.Argument(None, help="Run id/prefix (omit when using --since)."),
+    since: str = typer.Option(
+        None, "--since",
+        help="Copy all runs in a window instead of one: 1day | 7days | 1month | all.",
+    ),
+) -> None:
+    """Copy a run's metadata + logs to <workspace>/runs/ (one folder per run)."""
+    client = _client_or_exit()
+    workspace = Path(config.workspace_dir())
+
+    if since is not None:
+        if since != "all" and since not in copier.WINDOWS:
+            typer.echo("--since must be one of: 1day, 7days, 1month, all."); raise typer.Exit(code=1)
+        try:
+            runs = copier.runs_in_window(resources.list_runs_full(client, limit=None), since)
+        except ApiError as exc:
+            typer.echo(f"✗ {exc.message}"); raise typer.Exit(code=1)
+        if not runs:
+            render.note(f"No runs in the last {since}."); return
+        render.note(f"Copying {len(runs)} run(s)…")
+        total = 0
+        for r in runs:
+            try:
+                paths = copier.copy_run(client, workspace, r)
+            except ApiError as exc:
+                typer.echo(f"✗ {r.get('id')}: {exc.message}"); continue
+            _wrote(paths); total += len(paths)
+        render.note(f"Copied {len(runs)} run(s) to {workspace / 'runs'}")
+        return
+
+    if not ref:
+        typer.echo("Give a run id/prefix, or pass --since <window>."); raise typer.Exit(code=1)
+    run = _resolve_or_exit(resources.resolve_run, client, ref, "run")
+    try:
+        _wrote(copier.copy_run(client, workspace, run))
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}"); raise typer.Exit(code=1)
+
+
+@copy_app.command("key")
+def copy_key_cmd(
+    ref: str = typer.Argument(None, help="(unused)"),
+) -> None:
+    """Keys/credentials cannot be copied — secrets never touch local disk."""
+    typer.echo("Keys can't be copied — secrets are never written to disk.")
+    typer.echo("To view a secret value interactively, use:  sagex show key <ref> --reveal")
+    raise typer.Exit(code=1)
+
+
+@new_app.command("workflow")
+def new_workflow_cmd(
+    name: str = typer.Argument(..., help="Workflow display name."),
+    output: str = typer.Option(None, "--output", "-o", help="Output path (default: <workspace>/workflows/<name>.json)."),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite if the file already exists."),
+) -> None:
+    """Create a template workflow JSON file in your workspace, ready to edit and push."""
+    from sagex.copier import safe_name
+
+    workspace = Path(config.workspace_dir())
+    if output:
+        dest = Path(output)
+    else:
+        stem = safe_name(name, "workflow")
+        dest = workspace / "workflows" / f"{stem}.json"
+
+    if dest.exists() and not force:
+        typer.echo(f"✗ {dest} already exists. Pass --force to overwrite, or choose a different name.")
+        raise typer.Exit(code=1)
+
+    doc = dict(_WORKFLOW_TEMPLATE)
+    doc["name"] = name
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(json.dumps(doc, indent=2), encoding="utf-8")
+
+    typer.echo(f"✓ Created {dest}")
+    render.note("  Edit the file (fill in node ids, scriptId, vaultDetails, etc.)")
+    render.note(f"  Push when ready:  sagex push workflow \"{dest}\"")
+    render.note("  See the '_doc' field in the file for a full field reference.")
+
+
+@new_app.command("script")
+def new_script_cmd(
+    name: str = typer.Argument(..., help="Script name (letters, numbers, _ and - only)."),
+    language: str = typer.Option(None, "--language", "--lang", help="Language, e.g. shell, python, powershell (inferred from --output's extension if omitted)."),
+    output: str = typer.Option(None, "--output", "-o", help="Output path (default: <workspace>/scripts/<name>.<ext>)."),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite if the file already exists."),
+) -> None:
+    """Create a starter script file with a header explaining how params & secrets reach it."""
+    workspace = Path(config.workspace_dir())
+
+    lang = language or (pusher.infer_script_language(Path(output)) if output else None)
+    if not lang:
+        typer.echo("Give a --language (e.g. shell, python, powershell), or an --output path with a known extension.")
+        raise typer.Exit(code=1)
+
+    try:
+        filename, content = pusher.script_scaffold(name, lang)
+    except ValueError as exc:
+        typer.echo(f"✗ {exc}")
+        raise typer.Exit(code=1)
+
+    dest = Path(output) if output else workspace / "scripts" / filename
+    if dest.exists() and not force:
+        typer.echo(f"✗ {dest} already exists. Pass --force to overwrite, or choose a different name.")
+        raise typer.Exit(code=1)
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(content, encoding="utf-8")
+
+    typer.echo(f"✓ Created {dest}")
+    render.note("  Read the header — it explains how parameters and secrets reach the script.")
+    render.note(f"  Push when ready:  sagex push script \"{dest}\"")
+
+
+@create_app.command("vault")
+def create_vault_cmd(
+    name: str = typer.Argument(..., help="Vault name (must be unique among your vaults)."),
+    description: str = typer.Option("", "--description", "-d", help="Optional description."),
+) -> None:
+    """Create a new vault — a container for servers and credentials."""
+    client = _client_or_exit()
+
+    # Name is unique per owner; check first (the server's duplicate error shape varies).
+    try:
+        existing = resources.find_vault_by_name(client, name)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    if existing:
+        typer.echo(f"✗ You already have a vault named '{name}' (id {existing.get('id')}).")
+        typer.echo(f"  To change it, run:  sagex update vault \"{name}\" --description \"…\"")
+        raise typer.Exit(code=1)
+
+    try:
+        created = resources.create_vault(client, {"name": name, "description": description})
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Created vault '{created.get('name')}' (id {created.get('id')})")
+
+
+@update_app.command("vault")
+def update_vault_cmd(
+    ref: str = typer.Argument(..., help="Vault name or id."),
+    name: str = typer.Option(None, "--name", help="New name for the vault."),
+    description: str = typer.Option(None, "--description", "-d", help="New description."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Update a vault's name and/or description."""
+    if name is None and description is None:
+        typer.echo("Nothing to update — pass --name and/or --description.")
+        raise typer.Exit(code=1)
+
+    client = _client_or_exit()
+    vault = _resolve_or_exit(resources.resolve_vault, client, ref, "vault")
+
+    payload: dict = {}
+    if name is not None:
+        payload["name"] = name
+    if description is not None:
+        payload["description"] = description
+
+    # Guard a rename against colliding with another of your vaults.
+    if name is not None and name.strip().lower() != str(vault.get("name") or "").lower():
+        clash = resources.find_vault_by_name(client, name)
+        if clash and str(clash.get("id")) != str(vault.get("id")):
+            typer.echo(f"✗ You already have another vault named '{name}' (id {clash.get('id')}).")
+            raise typer.Exit(code=1)
+
+    typer.echo(f"Updating vault '{vault.get('name')}' (id {str(vault.get('id'))[:8]}…)")
+    if not yes and not typer.confirm("  Apply these changes?"):
+        typer.echo("Aborted — nothing changed.")
+        raise typer.Exit(code=1)
+
+    try:
+        updated = resources.update_vault(client, vault["id"], payload)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Updated vault '{updated.get('name')}' (id {updated.get('id')})")
+
+
+@create_app.command("server")
+def create_server_cmd(
+    name: str = typer.Argument(..., help="Server name (unique within the vault)."),
+    vault: str = typer.Option(..., "--vault", help="Vault name or id to create the server in (required)."),
+    host: str = typer.Option(..., "--host", help="Hostname or IP address (required)."),
+    method: str = typer.Option(..., "--method", "-m", help="Connection method: ssh or winrm (required)."),
+    port: int = typer.Option(None, "--port", "-p", help="Port (default: 22 for ssh, 5985 for winrm)."),
+    key: str = typer.Option(None, "--key", "-k", help="Credential (key) name or id to attach — must be in the same vault."),
+) -> None:
+    """Create a vault server (SSH or WinRM). Optionally attach a credential with --key."""
+    method = method.lower()
+    if method not in ("ssh", "winrm"):
+        typer.echo("✗ --method must be 'ssh' or 'winrm'.")
+        raise typer.Exit(code=1)
+    if port is None:
+        port = 22 if method == "ssh" else 5985
+    elif not 1 <= port <= 65535:
+        typer.echo("✗ --port must be between 1 and 65535.")
+        raise typer.Exit(code=1)
+
+    client = _client_or_exit()
+    v = _resolve_or_exit(resources.resolve_vault, client, vault, "vault")
+
+    # Server name is unique within its vault — check the vault's existing servers.
+    for s in (v.get("servers") or []):
+        if str(s.get("name") or "").lower() == name.strip().lower():
+            typer.echo(f"✗ Vault '{v.get('name')}' already has a server named '{name}' (id {s.get('id')}).")
+            raise typer.Exit(code=1)
+
+    payload = {
+        "vault": v["id"],
+        "name": name,
+        "host": host,
+        "connection_method": method,
+        "port": port,
+    }
+
+    cred = None
+    if key:
+        cred = resources.find_credential_in_vault(v, key)
+        if not cred:
+            typer.echo(f"✗ No credential '{key}' in vault '{v.get('name')}'.")
+            typer.echo(f"  A server's key must live in the same vault. See:  sagex show vault \"{v.get('name')}\"")
+            raise typer.Exit(code=1)
+        payload["credential"] = cred["id"]
+
+    try:
+        created = resources.create_server(client, payload)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+
+    typer.echo(f"✓ Created server '{created.get('name')}' (id {created.get('id')}) in vault '{v.get('name')}'")
+    attached = f" · key: {cred.get('name')}" if cred else " · no key attached"
+    render.note(f"  {method} · {host}:{port}{attached}")
+
+
+@create_app.command("key")
+def create_key_cmd(
+    name: str = typer.Argument(..., help="Credential name (unique within the vault)."),
+    vault: str = typer.Option(..., "--vault", help="Vault name or id to create the key in (required)."),
+    type_: str = typer.Option(..., "--type", "-t", help=f"Credential type: {_KEY_TYPE_CHOICES} (aliases: ssh, cert)."),
+    username: str = typer.Option(None, "--username", "-u", help="Username (username_password type; prompted if omitted)."),
+    key_file: str = typer.Option(None, "--key-file", help="SSH private key file path, or - to paste (ssh_key type)."),
+    cert_file: str = typer.Option(None, "--cert-file", help="Certificate PEM file path, or - to paste (certificate type)."),
+) -> None:
+    """Create a vault credential (key). Secrets are entered securely — never via flags."""
+    ctype = _normalize_key_type(type_)
+
+    # Reject flags that don't match the chosen type (fast, before any network/prompt).
+    if username is not None and ctype != "username_password":
+        typer.echo("✗ --username only applies to a username_password key.")
+        raise typer.Exit(code=1)
+    if key_file is not None and ctype != "ssh_key":
+        typer.echo("✗ --key-file only applies to an ssh_key key.")
+        raise typer.Exit(code=1)
+    if cert_file is not None and ctype != "certificate":
+        typer.echo("✗ --cert-file only applies to a certificate key.")
+        raise typer.Exit(code=1)
+
+    client = _client_or_exit()
+    v = _resolve_or_exit(resources.resolve_vault, client, vault, "vault")
+
+    # Name is unique within the vault — check BEFORE prompting for any secret.
+    if resources.find_credential_in_vault(v, name):
+        typer.echo(f"✗ Vault '{v.get('name')}' already has a key named '{name}'.")
+        raise typer.Exit(code=1)
+
+    payload = {"vault": v["id"], "name": name, "credential_type": ctype}
+    if ctype == "username_password":
+        payload["username"] = username if username is not None else typer.prompt("Username")
+        payload["password"] = _prompt_secret("Password", confirm=True)
+    elif ctype == "ssh_key":
+        payload["ssh_key"] = _acquire_multiline("SSH private key", key_file, paste_when_none=True)
+        passphrase = _prompt_optional_secret("Key passphrase (leave blank if none)")
+        if passphrase:
+            payload["key_passphrase"] = passphrase
+    else:  # certificate
+        payload["cert_pem"] = _acquire_multiline("certificate PEM", cert_file, paste_when_none=True)
+
+    try:
+        created = resources.create_credential(client, payload)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Created key '{created.get('name')}' (id {created.get('id')}, type {ctype}) in vault '{v.get('name')}'")
+
+
+@update_app.command("server")
+def update_server_cmd(
+    ref: str = typer.Argument(..., help="Server name or id."),
+    name: str = typer.Option(None, "--name", help="New server name (unique within its vault)."),
+    host: str = typer.Option(None, "--host", help="New hostname or IP address."),
+    method: str = typer.Option(None, "--method", "-m", help="New connection method: ssh or winrm."),
+    port: int = typer.Option(None, "--port", "-p", help="New port (1-65535)."),
+    key: str = typer.Option(None, "--key", "-k", help="Attach a credential (name or id) from the same vault."),
+    unlink_key: bool = typer.Option(False, "--unlink-key", help="Detach the currently attached credential."),
+    vault: str = typer.Option(None, "--vault", help="Scope the lookup to this vault (name or id) — use when the same server name exists in multiple vaults."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Update a vault server's fields and/or its attached credential."""
+    if key and unlink_key:
+        typer.echo("✗ Use either --key or --unlink-key, not both.")
+        raise typer.Exit(code=1)
+    if name is None and host is None and method is None and port is None and not key and not unlink_key:
+        typer.echo("Nothing to update — pass --name/--host/--method/--port/--key/--unlink-key.")
+        raise typer.Exit(code=1)
+
+    if method is not None:
+        method = method.lower()
+        if method not in ("ssh", "winrm"):
+            typer.echo("✗ --method must be 'ssh' or 'winrm'.")
+            raise typer.Exit(code=1)
+    if port is not None and not 1 <= port <= 65535:
+        typer.echo("✗ --port must be between 1 and 65535.")
+        raise typer.Exit(code=1)
+
+    client = _client_or_exit()
+
+    # --vault scopes the lookup to one vault (names are unique there); otherwise
+    # resolve globally, which reports an ambiguity if the name spans vaults.
+    vault_detail = None
+    if vault:
+        vault_detail = _resolve_or_exit(resources.resolve_vault, client, vault, "vault")
+        server = resources.find_server_in_vault(vault_detail, ref)
+        if not server:
+            typer.echo(f"✗ No server '{ref}' in vault '{vault_detail.get('name')}'.")
+            raise typer.Exit(code=1)
+    else:
+        server = _resolve_or_exit(resources.resolve_server, client, ref, "server")
+
+    payload: dict = {}
+    if name is not None:
+        payload["name"] = name
+    if host is not None:
+        payload["host"] = host
+    if method is not None:
+        payload["connection_method"] = method
+    if port is not None:
+        payload["port"] = port
+
+    # A rename or a key change both need the vault detail (its servers + credentials
+    # lists). Reuse the one fetched for --vault, else fetch by the server's vault id.
+    if (name is not None or key) and vault_detail is None:
+        vault_detail = _resolve_or_exit(resources.resolve_vault, client, server.get("vault"), "vault")
+
+    if name is not None:
+        for s in (vault_detail.get("servers") or []):
+            if str(s.get("id")) != str(server.get("id")) and str(s.get("name") or "").lower() == name.strip().lower():
+                typer.echo(f"✗ Vault '{vault_detail.get('name')}' already has another server named '{name}'.")
+                raise typer.Exit(code=1)
+
+    cred = None
+    if key:
+        cred = resources.find_credential_in_vault(vault_detail, key)
+        if not cred:
+            typer.echo(f"✗ No credential '{key}' in this server's vault '{vault_detail.get('name')}'.")
+            typer.echo(f"  A server's key must live in the same vault. See:  sagex show vault \"{vault_detail.get('name')}\"")
+            raise typer.Exit(code=1)
+        payload["credential"] = cred["id"]
+    elif unlink_key:
+        payload["credential"] = None
+
+    typer.echo(f"Updating server '{server.get('name')}' (id {str(server.get('id'))[:8]}…)")
+    if not yes and not typer.confirm("  Apply these changes?"):
+        typer.echo("Aborted — nothing changed.")
+        raise typer.Exit(code=1)
+
+    try:
+        updated = resources.update_server(client, server["id"], payload)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+
+    typer.echo(f"✓ Updated server '{updated.get('name')}' (id {updated.get('id')})")
+
+
+@update_app.command("key")
+def update_key_cmd(
+    ref: str = typer.Argument(..., help="Credential (key) name or id."),
+    vault: str = typer.Option(None, "--vault", help="Scope the lookup to this vault (name or id) — for a name shared across vaults."),
+    name: str = typer.Option(None, "--name", help="New name for the key."),
+    username: str = typer.Option(None, "--username", "-u", help="New username (username_password keys)."),
+    set_password: bool = typer.Option(False, "--set-password", help="Prompt for a new password (hidden)."),
+    key_file: str = typer.Option(None, "--key-file", help="Replace the SSH key from this file path, or - to paste."),
+    set_passphrase: bool = typer.Option(False, "--set-passphrase", help="Prompt for a new key passphrase (blank clears it)."),
+    cert_file: str = typer.Option(None, "--cert-file", help="Replace the certificate PEM from this file path, or - to paste."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Update a vault credential — rename or rotate a secret. Secrets entered securely."""
+    if not (name is not None or username is not None or set_password
+            or set_passphrase or key_file is not None or cert_file is not None):
+        typer.echo("Nothing to update — pass --name/--username/--set-password/--key-file/--set-passphrase/--cert-file.")
+        raise typer.Exit(code=1)
+
+    client = _client_or_exit()
+
+    # --vault scopes the lookup (names are unique per vault); else resolve globally.
+    if vault:
+        vd = _resolve_or_exit(resources.resolve_vault, client, vault, "vault")
+        cred = resources.find_credential_in_vault(vd, ref)
+        if not cred:
+            typer.echo(f"✗ No key '{ref}' in vault '{vd.get('name')}'.")
+            raise typer.Exit(code=1)
+    else:
+        cred = _resolve_or_exit(resources.resolve_credential, client, ref, "key")
+        vd = None
+
+    ctype = cred.get("credential_type")
+
+    # Only allow changes that match the key's type (update can't change the type).
+    if (username is not None or set_password) and ctype != "username_password":
+        typer.echo(f"✗ This key is type '{ctype}'; --username/--set-password only apply to username_password.")
+        raise typer.Exit(code=1)
+    if (key_file is not None or set_passphrase) and ctype != "ssh_key":
+        typer.echo(f"✗ This key is type '{ctype}'; --key-file/--set-passphrase only apply to ssh_key.")
+        raise typer.Exit(code=1)
+    if cert_file is not None and ctype != "certificate":
+        typer.echo(f"✗ This key is type '{ctype}'; --cert-file only applies to certificate.")
+        raise typer.Exit(code=1)
+
+    # Rename clash guard within the same vault.
+    if name is not None:
+        if vd is None:
+            vd = _resolve_or_exit(resources.resolve_vault, client, cred.get("vault"), "vault")
+        clash = resources.find_credential_in_vault(vd, name)
+        if clash and str(clash.get("id")) != str(cred.get("id")):
+            typer.echo(f"✗ Vault '{vd.get('name')}' already has another key named '{name}'.")
+            raise typer.Exit(code=1)
+
+    # Confirm the intended changes BEFORE entering any secret value.
+    changes = []
+    if name is not None:        changes.append(f"rename to '{name}'")
+    if username is not None:     changes.append("set username")
+    if set_password:            changes.append("new password")
+    if key_file is not None:     changes.append("replace SSH key")
+    if set_passphrase:          changes.append("new passphrase")
+    if cert_file is not None:    changes.append("replace certificate")
+    typer.echo(f"Updating key '{cred.get('name')}' (id {str(cred.get('id'))[:8]}…): {', '.join(changes)}")
+    if not yes and not typer.confirm("  Proceed?"):
+        typer.echo("Aborted — nothing changed.")
+        raise typer.Exit(code=1)
+
+    # Collect values (prompts / files) only after confirmation.
+    payload: dict = {}
+    if name is not None:
+        payload["name"] = name
+    if username is not None:
+        payload["username"] = username
+    if set_password:
+        payload["password"] = _prompt_secret("New password", confirm=True)
+    if key_file is not None:
+        payload["ssh_key"] = _acquire_multiline("SSH private key", key_file, paste_when_none=False)
+    if set_passphrase:
+        payload["key_passphrase"] = _prompt_optional_secret("New key passphrase (blank to clear)")
+    if cert_file is not None:
+        payload["cert_pem"] = _acquire_multiline("certificate PEM", cert_file, paste_when_none=False)
+
+    try:
+        updated = resources.update_credential(client, cred["id"], payload)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Updated key '{updated.get('name')}' (id {updated.get('id')})")
+
+
+# ---------------------------------------------------------------------------
+# Delete commands. Resolution reuses the resolve_* helpers, so an ambiguous name
+# prints the matching records (with ids) and aborts. Deletes are irreversible.
+# ---------------------------------------------------------------------------
+
+
+def _confirm_delete_or_abort(kind: str, name, ident, yes: bool) -> None:
+    """Standard delete confirmation (skipped when --yes). Aborts via typer.Exit."""
+    if yes:
+        return
+    typer.echo(f"About to delete {kind} '{name}' (id {ident}). This cannot be undone.")
+    if not typer.confirm("  Delete it?"):
+        typer.echo("Aborted — nothing deleted.")
+        raise typer.Exit(code=1)
+
+
+@delete_app.command("workflow")
+def delete_workflow_cmd(
+    ref: str = typer.Argument(..., help="Workflow name or id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Delete a workflow."""
+    client = _client_or_exit()
+    wf = _resolve_or_exit(resources.resolve_workflow, client, ref, "workflow")
+    _confirm_delete_or_abort("workflow", wf.get("name"), wf.get("id"), yes)
+    try:
+        resources.delete_workflow(client, wf["id"])
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Deleted workflow '{wf.get('name')}' (id {wf.get('id')})")
+
+
+@delete_app.command("script")
+def delete_script_cmd(
+    ref: str = typer.Argument(..., help="Script name or id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Delete a script."""
+    client = _client_or_exit()
+    meta = _resolve_or_exit(resources.resolve_script, client, ref, "script")
+    _confirm_delete_or_abort("script", meta.get("name"), meta.get("id"), yes)
+    try:
+        resources.delete_script(client, meta["id"])
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Deleted script '{meta.get('name')}' (id {meta.get('id')})")
+
+
+@delete_app.command("vault")
+def delete_vault_cmd(
+    ref: str = typer.Argument(..., help="Vault name or id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation (and the cascade name check)."),
+) -> None:
+    """Delete a vault. This CASCADES — every server and credential inside it is deleted too."""
+    client = _client_or_exit()
+    v = _resolve_or_exit(resources.resolve_vault, client, ref, "vault")
+    name = v.get("name")
+    servers = v.get("servers") or []
+    creds = v.get("credentials") or []
+
+    if not yes:
+        typer.echo(f"⚠ Deleting vault '{name}' (id {v.get('id')}) will ALSO delete everything inside it:")
+        typer.echo(f"    {len(servers)} server(s) and {len(creds)} credential(s).")
+        typer.echo("  This cannot be undone.")
+        typed = typer.prompt("  Type the vault name to confirm")
+        if typed.strip() != name:
+            typer.echo("Name did not match — aborted.")
+            raise typer.Exit(code=1)
+
+    try:
+        resources.delete_vault(client, v["id"])
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Deleted vault '{name}' (and {len(servers)} server(s), {len(creds)} credential(s))")
+
+
+@delete_app.command("server")
+def delete_server_cmd(
+    ref: str = typer.Argument(..., help="Server name or id."),
+    vault: str = typer.Option(None, "--vault", help="Scope the lookup to this vault (name or id) — for a name shared across vaults."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Delete a vault server."""
+    client = _client_or_exit()
+    if vault:
+        vd = _resolve_or_exit(resources.resolve_vault, client, vault, "vault")
+        server = resources.find_server_in_vault(vd, ref)
+        if not server:
+            typer.echo(f"✗ No server '{ref}' in vault '{vd.get('name')}'.")
+            raise typer.Exit(code=1)
+    else:
+        server = _resolve_or_exit(resources.resolve_server, client, ref, "server")
+
+    _confirm_delete_or_abort("server", server.get("name"), server.get("id"), yes)
+    try:
+        resources.delete_server(client, server["id"])
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Deleted server '{server.get('name')}' (id {server.get('id')})")
+
+
+@delete_app.command("key")
+def delete_key_cmd(
+    ref: str = typer.Argument(..., help="Credential (key) name or id."),
+    vault: str = typer.Option(None, "--vault", help="Scope the lookup to this vault (name or id) — for a name shared across vaults."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Delete a vault credential (key)."""
+    client = _client_or_exit()
+    if vault:
+        vd = _resolve_or_exit(resources.resolve_vault, client, vault, "vault")
+        cred = resources.find_credential_in_vault(vd, ref)
+        if not cred:
+            typer.echo(f"✗ No key '{ref}' in vault '{vd.get('name')}'.")
+            raise typer.Exit(code=1)
+    else:
+        cred = _resolve_or_exit(resources.resolve_credential, client, ref, "key")
+
+    if not yes:
+        typer.echo(f"About to delete key '{cred.get('name')}' (id {cred.get('id')}). This cannot be undone.")
+        typer.echo("  Any server using this key will have its credential unset.")
+        if not typer.confirm("  Delete it?"):
+            typer.echo("Aborted — nothing deleted.")
+            raise typer.Exit(code=1)
+
+    try:
+        resources.delete_credential(client, cred["id"])
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Deleted key '{cred.get('name')}' (id {cred.get('id')})")
+
+
+@delete_app.command("trigger")
+def delete_trigger_cmd(
+    ref: str = typer.Argument(..., help="Workflow name, or trigger id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Delete a trigger (HTTP or schedule)."""
+    client = _client_or_exit()
+    kind, t = _resolve_or_exit(resources.resolve_trigger, client, ref, "trigger")
+    _confirm_delete_or_abort("trigger", f"{t.get('workflow_name')} ({kind})", t.get("id"), yes)
+    try:
+        resources.delete_trigger(client, t.get("workflow_id"), kind, t.get("node_id"))
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Deleted {kind} trigger for '{t.get('workflow_name')}'")
+
+
+# ---------------------------------------------------------------------------
+# Trigger configuration (dedicated `trigger` sub-app). create/regenerate target a
+# workflow's trigger NODE; enable/disable/invoke act on an existing trigger.
+# ---------------------------------------------------------------------------
+
+
+def _pick_trigger_node(wf: dict, dtype: str, node_opt: str | None) -> str:
+    """Return the id of the workflow's <dtype> trigger node, or exit with guidance."""
+    if node_opt:
+        ids = {n.get("id") for n in (wf.get("nodes") or [])}
+        if node_opt not in ids:
+            typer.echo(f"✗ Node '{node_opt}' not found in workflow '{wf.get('name')}'.")
+            raise typer.Exit(code=1)
+        return node_opt
+    nodes = resources.find_trigger_nodes(wf, dtype)
+    if not nodes:
+        typer.echo(f"✗ Workflow '{wf.get('name')}' has no {dtype} trigger node.")
+        typer.echo(f"  Add a trigger node with data.type '{dtype}' (see: sagex syntax trigger), or pass --node <id>.")
+        raise typer.Exit(code=1)
+    if len(nodes) > 1:
+        typer.echo(f"Workflow '{wf.get('name')}' has multiple {dtype} trigger nodes — pass --node <id>:")
+        for n in nodes:
+            typer.echo(f"  {n.get('id')}  {(n.get('data') or {}).get('label') or ''}")
+        raise typer.Exit(code=1)
+    return nodes[0].get("id")
+
+
+_TRIGGER_LABELS = {"http": "HTTP Trigger", "schedule": "Schedule Trigger"}
+
+
+def _offer_trigger_switch(client, wf: dict, dtype: str, yes: bool) -> dict:
+    """A workflow has exactly one trigger node. If it's a manual one, offer to make it
+    a <dtype> trigger (on-demand runs keep working); returns the updated workflow."""
+    triggers = [n for n in wf.get("nodes") or [] if n.get("type") == "trigger"]
+    if len(triggers) != 1:
+        return wf                                # _pick_trigger_node explains the problem
+    node = triggers[0]
+    data = node.get("data") if isinstance(node.get("data"), dict) else {}
+    current = data.get("type") or "manual"
+    if current != "manual":
+        typer.echo(f"✗ Workflow '{wf.get('name')}' uses a {current} trigger node, and a workflow has only one.")
+        typer.echo(f"  To switch, remove that trigger (sagex delete trigger \"{wf.get('name')}\"), then set the")
+        typer.echo(f"  node's data.type to '{dtype}' in the workflow file and push it.")
+        raise typer.Exit(code=1)
+
+    kind = "an HTTP webhook" if dtype == "http" else "a schedule"
+    typer.echo(f"Workflow '{wf.get('name')}' has a manual trigger. It can be switched to {kind};")
+    typer.echo("  on-demand runs (sagex run workflow) keep working either way.")
+    if not yes and not typer.confirm("  Switch the trigger node?"):
+        typer.echo("Aborted — nothing changed.")
+        raise typer.Exit(code=1)
+
+    new_data = {**data, "type": dtype}
+    if data.get("label") in (None, "", "Trigger", "Manual Trigger"):
+        new_data["label"] = _TRIGGER_LABELS[dtype]
+    nodes = [{**n, "data": new_data} if n is node else n for n in wf["nodes"]]
+    try:
+        resources.update_workflow_nodes(client, wf["id"], nodes)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Switched the trigger node to {dtype}.")
+    return {**wf, "nodes": nodes}
+
+
+@trigger_app.command("create")
+def trigger_create_cmd(
+    workflow: str = typer.Argument(..., help="Workflow name or id."),
+    type_: str = typer.Option(..., "--type", "-t", help="Trigger type: http or schedule."),
+    cron: str = typer.Option(None, "--cron", help="Cron expression (5 fields, UTC) — required for schedule."),
+    node: str = typer.Option(None, "--node", help="Trigger node id (auto-detected if the workflow has exactly one)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmations (switching a manual trigger node, rotating an HTTP secret)."),
+) -> None:
+    """Create or update a workflow trigger. HTTP prints its secret once + how to call it.
+
+    If the workflow's trigger node is manual, this offers to switch it to the requested type first.
+    """
+    ttype = type_.lower()
+    if ttype not in ("http", "schedule"):
+        typer.echo("✗ --type must be 'http' or 'schedule'.")
+        raise typer.Exit(code=1)
+    if ttype == "schedule":
+        if not cron:
+            typer.echo("✗ A schedule trigger needs --cron \"<min> <hour> <day-of-month> <month> <day-of-week>\".")
+            raise typer.Exit(code=1)
+        if len(cron.split()) != 5:
+            typer.echo("✗ --cron must have exactly 5 whitespace-separated fields.")
+            raise typer.Exit(code=1)
+    elif cron:
+        typer.echo("✗ --cron only applies to a schedule trigger.")
+        raise typer.Exit(code=1)
+
+    client = _client_or_exit()
+    wf = _resolve_or_exit(resources.resolve_workflow, client, workflow, "workflow")
+    if not node and not resources.find_trigger_nodes(wf, ttype):
+        wf = _offer_trigger_switch(client, wf, ttype, yes)
+    node_id = _pick_trigger_node(wf, ttype, node)
+
+    if ttype == "http":
+        exists = False
+        try:
+            resources.get_http_trigger(client, wf["id"], node_id)
+            exists = True
+        except ApiError as exc:
+            if exc.status != 404:
+                typer.echo(f"✗ {exc.message}")
+                raise typer.Exit(code=1)
+        if exists and not yes:
+            typer.echo("⚠ An HTTP trigger already exists for this node.")
+            typer.echo("  Recreating ROTATES the secret and invalidates the current one.")
+            if not typer.confirm("  Rotate it now?"):
+                typer.echo("Aborted — trigger unchanged.")
+                raise typer.Exit(code=1)
+        try:
+            data = resources.create_http_trigger(client, wf["id"], node_id)
+        except ApiError as exc:
+            typer.echo(f"✗ {exc.message}")
+            raise typer.Exit(code=1)
+        render.http_trigger_result(data)
+    else:
+        try:
+            data = resources.upsert_schedule_trigger(client, wf["id"], node_id, cron)
+        except ApiError as exc:
+            detail = (exc.errors or {}).get("cron_expression") if isinstance(exc.errors, dict) else None
+            typer.echo(f"✗ {detail[0] if isinstance(detail, list) and detail else exc.message}")
+            raise typer.Exit(code=1)
+        render.schedule_trigger_result(data, wf.get("name"))
+        # Scheduled runs are started with no inputs, so a parameter without a saved
+        # value runs empty every time.
+        empty = [s["name"] for s in runner.workflow_params(wf.get("nodes"))
+                 if s["source"] == "manual" and not s["default"]]
+        if empty:
+            typer.echo(f"⚠ Scheduled runs pass no parameters, so these will run empty: {', '.join(empty)}.")
+            typer.echo("  Give them a saved value in the workflow (sagex copy workflow … → edit → push).")
+
+
+@trigger_app.command("regenerate")
+def trigger_regenerate_cmd(
+    workflow: str = typer.Argument(..., help="Workflow name or id."),
+    node: str = typer.Option(None, "--node", help="Trigger node id (auto-detected if one)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt."),
+) -> None:
+    """Rotate an HTTP trigger's secret (same URL). The current secret stops working."""
+    client = _client_or_exit()
+    wf = _resolve_or_exit(resources.resolve_workflow, client, workflow, "workflow")
+    node_id = _pick_trigger_node(wf, "http", node)
+    if not yes and not typer.confirm("Rotate the secret? The current one will stop working."):
+        typer.echo("Aborted — secret unchanged.")
+        raise typer.Exit(code=1)
+    try:
+        data = resources.regenerate_http_trigger(client, wf["id"], node_id)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    render.http_trigger_result(data)
+
+
+def _set_trigger_active(ref: str, active: bool) -> None:
+    """Enable/disable an existing trigger via the global PATCH (keyed by its uuid)."""
+    client = _client_or_exit()
+    kind, t = _resolve_or_exit(resources.resolve_trigger, client, ref, "trigger")
+    try:
+        resources.set_trigger_active(client, kind, t.get("id"), active)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ {'Enabled' if active else 'Disabled'} {kind} trigger for '{t.get('workflow_name')}'")
+
+
+@trigger_app.command("enable")
+def trigger_enable_cmd(
+    ref: str = typer.Argument(..., help="Workflow name, or trigger id."),
+) -> None:
+    """Enable a trigger (is_active = true)."""
+    _set_trigger_active(ref, True)
+
+
+@trigger_app.command("disable")
+def trigger_disable_cmd(
+    ref: str = typer.Argument(..., help="Workflow name, or trigger id."),
+) -> None:
+    """Disable a trigger without deleting it (is_active = false)."""
+    _set_trigger_active(ref, False)
+
+
+@trigger_app.command("invoke")
+def trigger_invoke_cmd(
+    ref: str = typer.Argument(..., help="Workflow name, or trigger id."),
+) -> None:
+    """Show how to call an HTTP trigger (URL, headers, body, curl). Secret is not shown."""
+    client = _client_or_exit()
+    kind, t = _resolve_or_exit(resources.resolve_trigger, client, ref, "trigger")
+    if kind != "http":
+        typer.echo("✗ Only HTTP triggers are called via URL — this is a schedule trigger.")
+        raise typer.Exit(code=1)
+    render.http_trigger_invocation(t)
+
+
+# ---------------------------------------------------------------------------
+# Rename commands. Low-risk and reversible, so they run without a confirmation
+# prompt (they're meant to double as Autobot tools). Name-uniqueness is guarded
+# where the server enforces it (vault per-owner; server/key per-vault).
+# ---------------------------------------------------------------------------
+
+
+@rename_app.command("workflow")
+def rename_workflow_cmd(
+    ref: str = typer.Argument(..., help="Workflow name or id."),
+    new_name: str = typer.Argument(..., help="New workflow name."),
+) -> None:
+    """Rename a workflow (leaves its nodes and edges untouched)."""
+    client = _client_or_exit()
+    wf = _resolve_or_exit(resources.resolve_workflow, client, ref, "workflow")
+    try:
+        updated = resources.rename_workflow(client, wf["id"], new_name)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Renamed workflow to '{updated.get('name') or new_name}' (id {wf.get('id')})")
+
+
+@rename_app.command("script")
+def rename_script_cmd(
+    ref: str = typer.Argument(..., help="Script name or id."),
+    new_name: str = typer.Argument(..., help="New script name (no extension — it's kept automatically)."),
+) -> None:
+    """Rename a script. Give the bare name; the file extension is preserved."""
+    if not pusher.is_valid_script_name(new_name):
+        typer.echo("✗ A script name can only contain letters, numbers, '_' and '-' "
+                   "(no extension or dot — the extension is kept automatically).")
+        raise typer.Exit(code=1)
+    client = _client_or_exit()
+    meta = _resolve_or_exit(resources.resolve_script, client, ref, "script")
+    try:
+        updated = resources.rename_script(client, meta["id"], new_name)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Renamed script to '{updated.get('name') or new_name}' (id {meta.get('id')})")
+
+
+@rename_app.command("vault")
+def rename_vault_cmd(
+    ref: str = typer.Argument(..., help="Vault name or id."),
+    new_name: str = typer.Argument(..., help="New vault name (unique among your vaults)."),
+) -> None:
+    """Rename a vault."""
+    client = _client_or_exit()
+    v = _resolve_or_exit(resources.resolve_vault, client, ref, "vault")
+    clash = resources.find_vault_by_name(client, new_name)
+    if clash and str(clash.get("id")) != str(v.get("id")):
+        typer.echo(f"✗ You already have another vault named '{new_name}' (id {clash.get('id')}).")
+        raise typer.Exit(code=1)
+    try:
+        updated = resources.update_vault(client, v["id"], {"name": new_name})
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Renamed vault to '{updated.get('name') or new_name}' (id {v.get('id')})")
+
+
+@rename_app.command("server")
+def rename_server_cmd(
+    ref: str = typer.Argument(..., help="Server name or id."),
+    new_name: str = typer.Argument(..., help="New server name (unique within its vault)."),
+    vault: str = typer.Option(None, "--vault", help="Scope the lookup to this vault — for a name shared across vaults."),
+) -> None:
+    """Rename a vault server."""
+    client = _client_or_exit()
+    if vault:
+        vd = _resolve_or_exit(resources.resolve_vault, client, vault, "vault")
+        server = resources.find_server_in_vault(vd, ref)
+        if not server:
+            typer.echo(f"✗ No server '{ref}' in vault '{vd.get('name')}'.")
+            raise typer.Exit(code=1)
+    else:
+        server = _resolve_or_exit(resources.resolve_server, client, ref, "server")
+        vd = _resolve_or_exit(resources.resolve_vault, client, server.get("vault"), "vault")
+
+    clash = resources.find_server_in_vault(vd, new_name)
+    if clash and str(clash.get("id")) != str(server.get("id")):
+        typer.echo(f"✗ Vault '{vd.get('name')}' already has another server named '{new_name}'.")
+        raise typer.Exit(code=1)
+    try:
+        updated = resources.update_server(client, server["id"], {"name": new_name})
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Renamed server to '{updated.get('name') or new_name}' (id {server.get('id')})")
+
+
+@rename_app.command("key")
+def rename_key_cmd(
+    ref: str = typer.Argument(..., help="Credential (key) name or id."),
+    new_name: str = typer.Argument(..., help="New key name (unique within its vault)."),
+    vault: str = typer.Option(None, "--vault", help="Scope the lookup to this vault — for a name shared across vaults."),
+) -> None:
+    """Rename a vault credential (key)."""
+    client = _client_or_exit()
+    if vault:
+        vd = _resolve_or_exit(resources.resolve_vault, client, vault, "vault")
+        cred = resources.find_credential_in_vault(vd, ref)
+        if not cred:
+            typer.echo(f"✗ No key '{ref}' in vault '{vd.get('name')}'.")
+            raise typer.Exit(code=1)
+    else:
+        cred = _resolve_or_exit(resources.resolve_credential, client, ref, "key")
+        vd = _resolve_or_exit(resources.resolve_vault, client, cred.get("vault"), "vault")
+
+    clash = resources.find_credential_in_vault(vd, new_name)
+    if clash and str(clash.get("id")) != str(cred.get("id")):
+        typer.echo(f"✗ Vault '{vd.get('name')}' already has another key named '{new_name}'.")
+        raise typer.Exit(code=1)
+    try:
+        updated = resources.update_credential(client, cred["id"], {"name": new_name})
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Renamed key to '{updated.get('name') or new_name}' (id {cred.get('id')})")
+
+
+@push_app.command("workflow")
+def push_workflow_cmd(
+    ref: str = typer.Argument(..., help="Workflow file path, or a name under <workspace>/workflows/."),
+    new: bool = typer.Option(False, "--new", help="Force-create a new workflow even if the file has an id."),
+    name: str = typer.Option(None, "--name", help="Override the workflow name (useful with --new)."),
+    yes: bool = typer.Option(False, "--yes", help="Skip the update confirmation prompt."),
+) -> None:
+    """Push a workflow file to the server — creates if new, updates if it carries an id."""
+    client = _client_or_exit()
+    workspace = Path(config.workspace_dir())
+
+    try:
+        path = pusher.resolve_workflow_file(workspace, ref)
+    except pusher.WorkflowFileNotFound as exc:
+        typer.echo(f"No workflow file for '{exc.ref}'. Looked at:")
+        for p in exc.looked:
+            typer.echo(f"  {p}")
+        raise typer.Exit(code=1)
+
+    try:
+        doc = pusher.load_doc(path)
+    except ValueError as exc:
+        typer.echo(f"✗ {exc}")
+        raise typer.Exit(code=1)
+
+    problems = pusher.validate_workflow_doc(doc)
+    if problems:
+        typer.echo(f"✗ {path} is not a valid workflow:")
+        for p in problems:
+            typer.echo(f"  - {p}")
+        raise typer.Exit(code=1)
+
+    payload = pusher.workflow_payload(doc, name)
+    wid = None if new else doc.get("id")
+    label = payload["name"]
+
+    if wid:
+        # UPDATE — fetch the server copy first (confirms it's ours + stale-write guard).
+        try:
+            server = resources.get_workflow_detail(client, wid)
+        except ApiError as exc:
+            if exc.status == 404:
+                typer.echo(f"No workflow {wid} on the server (deleted, or not yours).")
+                typer.echo("To create a fresh copy instead, re-run with --new.")
+            else:
+                typer.echo(f"✗ {exc.message}")
+            raise typer.Exit(code=1)
+
+        typer.echo(f"Updating '{label}' (id {str(wid)[:8]}…)")
+        if pusher.server_is_newer(server.get("modified_at"), doc.get("modified_at")):
+            typer.echo(f"  ⚠ server copy is newer (server {server.get('modified_at')} "
+                       f"vs local {doc.get('modified_at')}) — pushing overwrites it.")
+        if not yes and not typer.confirm("  Overwrite the server copy?"):
+            typer.echo("Aborted — nothing pushed.")
+            raise typer.Exit(code=1)
+
+        try:
+            updated = resources.update_workflow(client, wid, payload)
+        except ApiError as exc:
+            typer.echo(f"✗ {exc.message}")
+            raise typer.Exit(code=1)
+        pusher.sync_meta_back(path, doc, updated)
+        typer.echo(f"✓ Updated '{updated.get('name')}' (id {updated.get('id')})")
+        return
+
+    # CREATE
+    typer.echo(f"Creating '{label}'…")
+    try:
+        created = resources.create_workflow(client, payload)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    pusher.sync_meta_back(path, doc, created)
+    typer.echo(f"✓ Created '{created.get('name')}' (id {created.get('id')})")
+    render.note(f"  wrote id back to {path}")
+
+
+@push_app.command("script")
+def push_script_cmd(
+    ref: str = typer.Argument(..., help="Script file path, or a name under <workspace>/scripts/."),
+    name: str = typer.Option(None, "--name", help="Override the script name (letters, numbers, _ and - only)."),
+    language: str = typer.Option(None, "--language", "--lang", help="Override the language (else inferred from the file extension)."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the update confirmation prompt."),
+) -> None:
+    """Push a script file — creates it, or updates the existing one after confirming.
+
+    A script's code can't carry a server id, so this matches by filename: it looks
+    for one of yours with the same name and, if found, offers to update it (bumping
+    its version); otherwise it creates a new script.
+    """
+    client = _client_or_exit()
+    workspace = Path(config.workspace_dir())
+
+    try:
+        path = pusher.resolve_script_file(workspace, ref)
+    except pusher.ScriptFileNotFound as exc:
+        if exc.matches:
+            typer.echo(f"'{exc.ref}' matches more than one file — pass the full name:")
+            for p in exc.matches:
+                typer.echo(f"  {p.name}")
+        else:
+            typer.echo(f"No script file for '{exc.ref}'. Looked at:")
+            for p in exc.looked:
+                typer.echo(f"  {p}")
+        raise typer.Exit(code=1)
+
+    try:
+        spec = pusher.script_push_spec(path, name, language)
+    except ValueError as exc:
+        typer.echo(f"✗ {exc}")
+        raise typer.Exit(code=1)
+
+    # Check-then-confirm: is there already a script of ours with this filename?
+    try:
+        existing = resources.find_script_by_name(client, spec["server_name"])
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+
+    if existing:
+        sid = existing.get("id")
+        typer.echo(f"'{spec['server_name']}' already exists (id {sid}, v{existing.get('version')}, "
+                   f"updated {existing.get('updated_at')}).")
+
+        # Preview what the update would overwrite (best-effort; don't block on a fetch error).
+        try:
+            server_code = (resources.get_script_content(client, sid) or {}).get("content") or ""
+        except ApiError as exc:
+            server_code = None
+            render.note(f"  (couldn't fetch the current version to diff: {exc.message})")
+
+        if server_code is not None and not render.script_diff(spec["server_name"], server_code, spec["content"]):
+            typer.echo("Local file matches the server copy — nothing to update.")
+            return
+
+        if not yes and not typer.confirm("  Update it? This overwrites the code and bumps the version."):
+            typer.echo("Aborted — nothing pushed.")
+            raise typer.Exit(code=1)
+        try:
+            updated = resources.update_script(client, sid, spec["content"])
+        except ApiError as exc:
+            typer.echo(f"✗ {exc.message}")
+            raise typer.Exit(code=1)
+        typer.echo(f"✓ Updated '{updated.get('name')}' (id {updated.get('id')}, now v{updated.get('version')})")
+        return
+
+    # CREATE — no existing script to clobber (server rejects a duplicate pathname).
+    typer.echo(f"Creating '{spec['server_name']}' (language: {spec['language']})…")
+    try:
+        created = resources.create_script(client, {
+            "name": spec["name"], "language": spec["language"], "content": spec["content"],
+        })
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    typer.echo(f"✓ Created '{created.get('name')}' (id {created.get('id')})")
+
+
+# ---------------------------------------------------------------------------
+# Run commands. A script run streams live from the server. Ctrl+C asks the server
+# to stop it while the stream stays open to report the final status; a second
+# Ctrl+C detaches. Secret inputs are only ever typed at a hidden prompt.
+# ---------------------------------------------------------------------------
+
+
+class _RunSetupError(Exception):
+    """A run can't start; carries the lines to print once the activity line is gone."""
+
+    def __init__(self, *lines: str) -> None:
+        super().__init__(lines[0])
+        self.lines = lines
+
+
+@contextmanager
+def _setup_errors():
+    """Turn failures from a run's setup step (which runs under the activity line and
+    prints nothing) into clean messages + exits once that line has cleared."""
+    try:
+        yield
+    except KeyboardInterrupt:
+        typer.echo("Cancelled — nothing was run.", err=True)
+        raise typer.Exit(code=130)
+    except resources.AmbiguousResource as exc:
+        render.ambiguous(exc)
+        raise typer.Exit(code=1)
+    except resources.ResourceNotFound as exc:
+        typer.echo(str(exc))
+        raise typer.Exit(code=1)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+    except _RunSetupError as exc:
+        for line in exc.lines:
+            typer.echo(line)
+        raise typer.Exit(code=1)
+
+
+def _prepare_script_run(client, ref: str, server_ref: str, vault_ref: str | None,
+                        key_ref: str | None, activity: "render.RunActivity"):
+    """Look up everything a script run needs and return
+    (script, server, credential, vault_name, content).
+
+    The script, server and vault lists are fetched in parallel; their items already
+    carry what a run needs (params, vault/key links, nested keys), so no detail
+    calls follow. Prints nothing: it runs under the activity line, so failures are
+    raised for the caller to report.
+    """
+    scripts, servers, vaults = runner.fetch_parallel(
+        lambda: resources.list_scripts_full(client),
+        lambda: resources.list_servers_full(client),
+        lambda: resources.list_vaults_full(client),
+    )
+    vaults_by_id = {str(v.get("id")): v for v in vaults}
+    script = resources.pick_script(scripts, ref)
+
+    if vault_ref:
+        vault = resources.pick_vault(vaults, vault_ref)
+        server = resources.find_server_in_vault(vault, server_ref)
+        if not server:
+            raise _RunSetupError(f"✗ No server '{server_ref}' in vault '{vault.get('name')}'.")
+    else:
+        names = {vid: v.get("name") for vid, v in vaults_by_id.items()}
+        server = resources.pick_server(servers, server_ref, names)
+        vault = vaults_by_id.get(str(server.get("vault"))) or {}
+
+    if key_ref:
+        cred = resources.find_credential_in_vault(vault, key_ref)
+        if not cred:
+            raise _RunSetupError(
+                f"✗ No key '{key_ref}' in the server's vault '{vault.get('name')}'.",
+                f"  A server's key must live in the same vault. See:  sagex show vault \"{vault.get('name')}\"",
+            )
+    elif server.get("credential"):
+        cred = server.get("credential_details") or {"id": server.get("credential")}
+    else:
+        raise _RunSetupError(
+            f"✗ Server '{server.get('name')}' has no key attached.",
+            f"  Pass --key <name>, or attach one:  sagex update server \"{server.get('name')}\" --key <name>",
+        )
+
+    activity.set("Reading the script")
+    (body,) = runner.fetch_parallel(lambda: resources.get_script_content(client, script["id"]))
+    return script, server, cred, vault.get("name"), (body or {}).get("content") or ""
+
+
+def _prompt_input(spec: dict) -> str:
+    """Ask for one script input until it fits its type (hidden for secrets).
+    Prompts go to stderr so redirected stdout holds only the script's output."""
+    if spec["description"]:
+        render.run_note(f"  {spec['name']}: {spec['description']}")
+    suffix = " (secret)" if spec["secret"] else (f" ({spec['type']})" if spec["type"] != "string" else "")
+    while True:
+        value = typer.prompt(f"{spec['name']}{suffix}", hide_input=spec["secret"],
+                             default="", show_default=False, err=True)
+        problem = runner.check_value(spec["type"], value)
+        if not problem:
+            return value
+        typer.echo(f"  ✗ {problem}", err=True)
+
+
+def _collect_inputs(specs: list[dict], raw: list[str]) -> dict:
+    """A value for every script input: --param, else the saved default, else a
+    prompt. Secrets are refused as flags (shell history) and always prompted for."""
+    by_name = {s["name"].lower(): s for s in specs}
+    given: dict[str, str] = {}
+    for item in raw:
+        name, sep, value = item.partition("=")
+        name = name.strip()
+        if not sep or not name:
+            typer.echo(f"✗ --param must look like NAME=VALUE (got '{item}').")
+            raise typer.Exit(code=1)
+        spec = by_name.get(name.lower())
+        if spec is None:
+            known = ", ".join(s["name"] for s in specs) or "none"
+            typer.echo(f"✗ '{name}' isn't an input of this script. Its {{{{NAME}}}} inputs: {known}.")
+            raise typer.Exit(code=1)
+        if spec["secret"]:
+            typer.echo(f"✗ '{spec['name']}' is a secret — leave it off the command line; you'll be asked for it (hidden).")
+            raise typer.Exit(code=1)
+        problem = runner.check_value(spec["type"], value)
+        if problem:
+            typer.echo(f"✗ --param {spec['name']}: {problem} (got '{value}').")
+            raise typer.Exit(code=1)
+        given[spec["name"]] = value
+
+    # Prompts are written to stderr, so both ends must be a terminal. stdin alone
+    # isn't enough: Windows reports a null-device stdin (as the TUI uses) as a TTY.
+    interactive = sys.stdin.isatty() and sys.stderr.isatty()
+    inputs: dict[str, str] = {}
+    for spec in specs:
+        name = spec["name"]
+        if name in given:
+            inputs[name] = given[name]
+        elif spec["default"]:
+            inputs[name] = spec["default"]
+        elif interactive:
+            inputs[name] = _prompt_input(spec)
+        elif spec["secret"]:
+            typer.echo(f"✗ '{name}' is a secret and can only be typed at a hidden prompt — run this in a terminal.")
+            raise typer.Exit(code=1)
+        else:
+            typer.echo(f"✗ No value for '{name}'. Pass --param {name}=VALUE.")
+            raise typer.Exit(code=1)
+    return inputs
+
+
+def _show_run_frame(frame, state: dict, log: "copier.ScriptRunLog | None") -> bool:
+    """Print one live-run frame, copy it to the local log, and track the run's
+    status; False once the run is done."""
+    event, data = frame
+    if not isinstance(data, dict):
+        data = {"data": data}
+    text = None
+    if event == "stdout":
+        text = str(data.get("data", ""))
+        render.run_stdout(text)
+    elif event == "stderr":
+        text = str(data.get("data", ""))
+        render.run_stderr(text)
+    elif event == "status":
+        state["execution_id"] = data.get("execution_id") or state["execution_id"]
+        state["status"] = data.get("status") or state["status"]
+        if log and state["execution_id"]:
+            log.start(state["execution_id"])
+    elif event == "exit_code":
+        state["exit_code"] = data.get("exit_code")
+    elif event == "error":
+        text = str(data.get("message") or data.get("data") or "Run failed.")
+        render.run_stderr(text)
+    elif event == "done":
+        return False
+    else:                                   # 'log' and anything newer: worker info lines
+        text = str(data.get("data", ""))
+        render.run_note(text)
+    if log and text is not None:
+        log.line(event, text)
+    return True
+
+
+def _follow_script_run(client, payload: dict, log: "copier.ScriptRunLog | None") -> int:
+    """Stream a script run to the terminal (and the local log); return the CLI exit code."""
+    stream = runner.BackgroundStream(resources.run_script_stream(client, payload))
+    state = {"execution_id": None, "status": None, "exit_code": None}
+    activity = render.RunActivity("Starting the run")
+    stopping = detached = False
+    started = time.monotonic()
+    with render.run_activity(activity):
+        while True:
+            try:
+                frame = stream.get()
+                if frame is None or not _show_run_frame(frame, state, log):
+                    break
+                if state["status"] == "running" and not stopping and activity.verb != "Running":
+                    activity.set("Running")
+            except KeyboardInterrupt:
+                if stopping or not state["execution_id"]:
+                    detached = True
+                    break
+                stopping = True
+                activity.set("Stopping", "ctrl+c again to detach")
+                render.run_note("Stop requested — waiting for the run to end.")
+                try:
+                    resources.stop_script_execution(client, state["execution_id"])
+                except ApiError as exc:
+                    render.run_note(f"Couldn't stop it: {exc.message}")
+            except ApiError as exc:
+                render.run_stderr(f"✗ {exc.message}")
+                if log:
+                    log.line("error", exc.message)
+                break
+
+    seconds = time.monotonic() - started
+    status, exit_code, execution_id = state["status"], state["exit_code"], state["execution_id"]
+    if log:
+        log.finish(execution_id=execution_id, status=status, exit_code=exit_code,
+                   seconds=seconds, detached=detached)
+    if detached:
+        hint = f" (execution {execution_id})" if execution_id else ""
+        render.run_note(f"Detached — the run may still be going{hint}.")
+    elif execution_id:
+        render.run_summary(status, exit_code, seconds, execution_id)
+    if log and log.folder:
+        render.run_note(f"  logs: {_display_path(log.folder)}")
+    elif log and log.error:
+        render.run_note(f"  couldn't save logs locally: {log.error}")
+
+    if detached or status == "cancelled":
+        return 130
+    if status == "completed":
+        return 0
+    return exit_code if isinstance(exit_code, int) and exit_code > 0 else 1
+
+
+def _display_path(path: Path) -> str:
+    """`path` relative to the current directory when it's inside it, else absolute."""
+    try:
+        return str(path.resolve().relative_to(Path.cwd().resolve()))
+    except ValueError:
+        return str(path)
+
+
+@run_app.command("script")
+def run_script_cmd(
+    ref: str = typer.Argument(..., help="Script name or id."),
+    server_ref: str = typer.Option(..., "--server", "-s", help="Server (name or id) to run it on."),
+    key: str = typer.Option(None, "--key", "-k", help="Key (name or id) from the server's vault. Defaults to the server's attached key."),
+    vault: str = typer.Option(None, "--vault", help="Scope the server lookup to this vault (name or id) — for a server name shared across vaults."),
+    params: list[str] = typer.Option(None, "--param", "-p", help="A script input as NAME=VALUE (repeatable). Secrets are asked for at a hidden prompt instead."),
+    no_log: bool = typer.Option(False, "--no-log", help="Don't save a copy of the logs under <workspace>/logs/script/<execution_id>/."),
+) -> None:
+    """Run a script on a server and stream its output live.
+
+    The script's inputs are its {{NAME}} markers. Each value comes from --param, else the script's saved default, else a prompt. Ctrl+C stops the run (press it again to detach). A copy of the logs is saved under <workspace>/logs/script/<execution_id>/. Exits with the script's exit code.
+    """
+    client = _client_or_exit()
+    activity = render.RunActivity("Looking up the script and server", "ctrl+c to cancel")
+    with _setup_errors(), render.run_activity(activity):
+        script, server, cred, vault_name, content = _prepare_script_run(
+            client, ref, server_ref, vault, key, activity)
+
+    specs = runner.script_params(content, script.get("parameters"))
+    inputs = _collect_inputs(specs, params or [])
+    secret_names = {s["name"] for s in specs if s["secret"]}
+
+    details = [server.get("host"),
+               vault_name and f"vault {vault_name}",
+               cred.get("name") and f"key {cred.get('name')}"]
+    render.run_header(script.get("name") or ref, server.get("name") or server_ref,
+                      details, inputs, secret_names)
+
+    log = None
+    if not no_log:
+        log = copier.ScriptRunLog(Path(config.workspace_dir()), {
+            "script": {"id": script.get("id"), "name": script.get("name")},
+            "server": {"id": server.get("id"), "name": server.get("name"), "host": server.get("host")},
+            "vault": vault_name,
+            "key": cred.get("name"),
+            "inputs": {k: ("*****" if k in secret_names else v) for k, v in inputs.items()},
+        })
+    payload = {
+        "script_details": {
+            "script_id": int(script["id"]),
+            "script_name": script.get("name") or "",
+            "pathname": script.get("pathname") or "",
+        },
+        "vault_details": {
+            "vault_id": str(server.get("vault")),
+            "server_id": str(server.get("id")),
+            "credential_id": str(cred.get("id")),
+        },
+        "inputs": inputs,
+    }
+    raise typer.Exit(code=_follow_script_run(client, payload, log))
+
+
+_RUN_FINISHED = ("success", "failed", "cancelled")
+
+
+def _emit_run_event(view: "runview.WorkflowRunView", event: dict) -> None:
+    """Apply a run update to the live graph; under the TUI (SAGEX_EVENTS=1) also print
+    it as an event line so the TUI can draw the same graph."""
+    view.apply(event)
+    if os.environ.get("SAGEX_EVENTS") == "1":
+        print(runview.event_line(event), file=sys.stderr, flush=True)
+
+
+def _collect_workflow_inputs(specs: list[dict], raw: list[str]) -> tuple[dict, dict]:
+    """Return (inputs to send keyed by parameter id, values to show keyed by label).
+
+    --param takes a parameter name, or its id when a name repeats across nodes.
+    Parameters not set keep the value saved in the workflow (and aren't sent);
+    ones with no saved value are prompted for. Secrets are refused as flags, and
+    parameters fed by another node's output can't be set.
+    """
+    manual = [s for s in specs if s["source"] == "manual"]
+    by_id = {s["id"]: s for s in specs}
+    name_count: dict[str, int] = {}
+    for s in manual:
+        name_count[s["name"].lower()] = name_count.get(s["name"].lower(), 0) + 1
+
+    def ref_for(s):           # how to address a parameter on the command line
+        return s["name"] if name_count[s["name"].lower()] == 1 else s["id"]
+
+    given: dict[str, str] = {}
+    for item in raw:
+        key, sep, value = item.partition("=")
+        key = key.strip()
+        if not sep or not key:
+            typer.echo(f"✗ --param must look like NAME=VALUE (got '{item}').")
+            raise typer.Exit(code=1)
+        spec = by_id.get(key)
+        if spec is None:
+            hits = [s for s in specs if s["name"].lower() == key.lower()]
+            if not hits:
+                known = ", ".join(sorted({s["name"] for s in manual})) or "none"
+                typer.echo(f"✗ '{key}' isn't a parameter of this workflow. Its parameters: {known}.")
+                raise typer.Exit(code=1)
+            if len(hits) > 1:
+                typer.echo(f"✗ '{key}' names {len(hits)} different parameters — pass its id instead:")
+                for s in hits:
+                    typer.echo(f"    --param {s['id']}=VALUE   ({', '.join(s['nodes'])})")
+                raise typer.Exit(code=1)
+            spec = hits[0]
+        if spec["source"] != "manual":
+            typer.echo(f"✗ '{spec['name']}' takes its value from another node's output; it can't be set here.")
+            raise typer.Exit(code=1)
+        if spec["secret"]:
+            typer.echo(f"✗ '{spec['name']}' is a secret — leave it off the command line; you'll be asked for it (hidden).")
+            raise typer.Exit(code=1)
+        problem = runner.check_value(spec["type"], value)
+        if problem:
+            typer.echo(f"✗ --param {spec['name']}: {problem} (got '{value}').")
+            raise typer.Exit(code=1)
+        given[spec["id"]] = value
+
+    interactive = sys.stdin.isatty() and sys.stderr.isatty()
+    inputs: dict[str, str] = {}
+    shown: dict[str, str] = {}
+    for s in manual:
+        if s["id"] in given:
+            value = inputs[s["id"]] = given[s["id"]]
+        elif s["default"]:
+            value = s["default"]                     # saved in the workflow; not sent
+        elif interactive:
+            value = inputs[s["id"]] = _prompt_input(s)
+        elif s["secret"]:
+            typer.echo(f"✗ '{s['name']}' is a secret and can only be typed at a hidden prompt — run this in a terminal.")
+            raise typer.Exit(code=1)
+        else:
+            typer.echo(f"✗ No value for '{s['name']}'. Pass --param {ref_for(s)}=VALUE.")
+            raise typer.Exit(code=1)
+        label = s["name"] if name_count[s["name"].lower()] == 1 else f"{s['name']} ({s['nodes'][0]})"
+        shown[label] = "*****" if s["secret"] else value
+    return inputs, shown
+
+
+def _show_workflow_frame(frame, state: dict, view: "runview.WorkflowRunView") -> bool:
+    """Apply one live-run frame to the graph, print its output to the scrolling log,
+    and track the run; False once it reports 'done'."""
+    event, data = frame
+    if not isinstance(data, dict):
+        data = {"data": data}
+    if event == "status":
+        state["status"] = data.get("status") or state["status"]
+        if data.get("error_message"):
+            state["error"] = data["error_message"]
+        _emit_run_event(view, {"t": "run", "status": state["status"]})
+    elif event == "node_start":
+        node_id = data.get("node_id")
+        label = data.get("node_label") or view.label(node_id)
+        state["current"] = label
+        if state["status"] == "queued":
+            state["status"] = "running"           # the 'running' status may have streamed early
+        _emit_run_event(view, {"t": "node", "id": node_id, "status": "running"})
+        # The trigger finishes instantly and usually streams before we connect, so
+        # it gets no log lines either way (the graph still shows it done).
+        if view.kind(node_id) != "trigger":
+            render.workflow_node_start(label, view.kind(node_id))
+    elif event == "node_complete":
+        node_id = data.get("node_id")
+        branch = data.get("taken_branch") if "decision_result" in data else None
+        _emit_run_event(view, {"t": "node", "id": node_id, "status": data.get("status"),
+                               "exit_code": data.get("exit_code"), "duration": data.get("duration"),
+                               "branch": branch})
+        if view.kind(node_id) != "trigger":
+            render.workflow_node_done(data.get("node_label") or view.label(node_id), data.get("status"),
+                                      data.get("exit_code"), data.get("duration"), branch)
+    elif event == "log":
+        kind, text = runner.classify_log_line(str(data.get("stdout") or data.get("data") or ""))
+        {"stdout": render.run_stdout, "stderr": render.run_stderr, "note": render.run_note}[kind](text)
+    elif event == "stdout":
+        render.run_stdout(str(data.get("data", "")))
+    elif event == "stderr":
+        render.run_stderr(str(data.get("data", "")))
+    elif event == "error":
+        render.run_stderr(str(data.get("message") or data.get("data") or "Stream error."))
+    elif event == "done":
+        if data.get("status") in _RUN_FINISHED:
+            state["status"] = data["status"]
+            _emit_run_event(view, {"t": "run", "status": state["status"]})
+        return False
+    return True
+
+
+def _pump_workflow_stream(client, run_id: str, state: dict, view: "runview.WorkflowRunView",
+                          activity: "render.RunActivity") -> bool:
+    """Show one stream connection's frames; True if it ended with the run finished.
+
+    The connection lives in state["stream"] so a Ctrl+C (whose cancel may fail)
+    resumes the same stream instead of opening a second one and losing frames.
+    """
+    if state.get("stream") is None:
+        state["stream"] = runner.BackgroundStream(resources.stream_workflow_run(client, run_id))
+    while True:
+        try:
+            frame = state["stream"].get()
+        except ApiError:
+            state["stream"] = None
+            raise
+        if frame is None:
+            state["stream"] = None
+            return False                          # ended early (dropped / 30-min cap)
+        state["errors"] = 0
+        if not _show_workflow_frame(frame, state, view):
+            state["stream"] = None
+            return state["status"] in _RUN_FINISHED
+        if state["status"] == "running":
+            activity.set(f"Running {state['current']}" if state["current"] else "Running")
+
+
+def _iso_seconds(start: str | None, end: str | None) -> float | None:
+    try:
+        return (datetime.fromisoformat(end) - datetime.fromisoformat(start)).total_seconds()
+    except (TypeError, ValueError):
+        return None
+
+
+def _follow_workflow_run(client, run_id: str, view: "runview.WorkflowRunView",
+                         workspace: Path | None) -> int:
+    """Follow a workflow run live until it ends; return the CLI exit code.
+
+    On a terminal, the run's graph stays pinned at the bottom and updates as nodes
+    start and finish, while their output scrolls above it. The stream is live-only,
+    so it reconnects if it ends early, and the run's node records are applied at the
+    end (covering anything that streamed before we connected). Ctrl+C cancels the
+    run; a second Ctrl+C detaches.
+    """
+    state = {"status": "queued", "error": "", "current": "", "errors": 0, "stream": None}
+    activity = render.RunActivity("Queued — waiting for a worker", "ctrl+c to cancel")
+    started = time.monotonic()
+    cancel_tried = detached = lost = False
+    with render.run_activity(activity, above=view):
+        while True:
+            try:
+                if _pump_workflow_stream(client, run_id, state, view, activity):
+                    break
+                run = resources.get_workflow_run(client, run_id)     # did it finish meanwhile?
+                if run.get("status") in _RUN_FINISHED:
+                    state["status"], state["error"] = run["status"], run.get("error_message") or ""
+                    break
+                render.run_note("Reconnecting to the live stream…")
+                time.sleep(1)
+            except KeyboardInterrupt:
+                if cancel_tried:
+                    detached = True
+                    break
+                cancel_tried = True
+                activity.set("Cancelling", "ctrl+c again to detach")
+                try:
+                    resources.cancel_workflow_run(client, run_id)
+                    state["status"] = "cancelled"
+                    break
+                except KeyboardInterrupt:
+                    detached = True
+                    break
+                except ApiError as exc:
+                    render.run_note(f"Couldn't cancel: {exc.message}")
+                    activity.set("Running", "ctrl+c again to detach")
+            except ApiError as exc:
+                state["errors"] += 1
+                render.run_stderr(f"✗ {exc.message}")
+                if state["errors"] >= 3:
+                    lost = True
+                    break
+
+    seconds = time.monotonic() - started
+    if detached or lost:
+        why = "Detached — the run is still going" if detached else "Lost the live stream"
+        render.run_note(f"{why} (run {run_id}). Check it later:  sagex show run {run_id}")
+        return 130 if detached else 1
+
+    # Apply the run's node records (the authoritative final state), show the final
+    # graph, then save the logs from the server's copies.
+    run, nodes = {"id": run_id, "status": state["status"]}, None
+    try:
+        with render.run_activity(render.RunActivity("Collecting the results", "")):
+            run, nodes = runner.fetch_parallel(
+                lambda: resources.get_workflow_run(client, run_id),
+                lambda: resources.get_run_nodes(client, run_id),
+            )
+    except (ApiError, KeyboardInterrupt) as exc:
+        render.run_note(f"Couldn't fetch the run's final results: {getattr(exc, 'message', 'interrupted')}")
+
+    for n in nodes or []:
+        if n.get("status"):
+            _emit_run_event(view, {"t": "node", "id": n.get("node_id"), "status": n["status"],
+                                   "exit_code": n.get("exit_code"),
+                                   "duration": _iso_seconds(n.get("started_at"), n.get("finished_at"))})
+    status = run.get("status") or state["status"]
+    _emit_run_event(view, {"t": "run", "status": status})
+    if os.environ.get("SAGEX_EVENTS") != "1":       # the TUI draws its own final graph
+        render.workflow_run_graph(view)
+
+    if status == "failed" and (run.get("error_message") or state["error"]):
+        render.run_stderr(run.get("error_message") or state["error"])
+    total = _iso_seconds(run.get("started_at"), run.get("finished_at")) or seconds
+    render.run_summary(status, None, total, run_id, noun="run")
+
+    if workspace is not None and nodes is not None:
+        try:
+            with render.run_activity(render.RunActivity("Saving the logs", "")):
+                folder = copier.save_workflow_run(client, workspace, run, nodes)
+            render.run_note(f"  logs: {_display_path(folder)}")
+        except (OSError, ApiError, KeyboardInterrupt) as exc:
+            render.run_note(f"  couldn't save logs locally: {getattr(exc, 'message', exc)}")
+
+    if status == "success":
+        return 0
+    return 130 if status == "cancelled" else 1
+
+
+@run_app.command("workflow")
+def run_workflow_cmd(
+    ref: str = typer.Argument(..., help="Workflow name or id."),
+    params: list[str] = typer.Option(None, "--param", "-p", help="Set a parameter as NAME=VALUE (or PARAM_ID=VALUE when a name repeats across nodes). Repeatable; secrets are asked for at a hidden prompt."),
+    notify: str = typer.Option(None, "--notify", help="Email this address when the run finishes."),
+    no_log: bool = typer.Option(False, "--no-log", help="Don't save the run's logs under <workspace>/logs/workflow/<run_id>/."),
+) -> None:
+    """Run a workflow now (manual trigger) and follow it live, node by node.
+
+    Parameters keep the values saved in the workflow unless set with --param; any without a value are asked for. Ctrl+C cancels the run (press it again to detach). The logs are saved under <workspace>/logs/workflow/<run_id>/ when it ends.
+    """
+    if notify is not None and "@" not in notify:
+        typer.echo("✗ --notify needs an email address.")
+        raise typer.Exit(code=1)
+
+    client = _client_or_exit()
+    with _setup_errors(), render.run_activity(render.RunActivity("Looking up the workflow", "ctrl+c to cancel")):
+        wf = resources.resolve_workflow(client, ref)
+
+    specs = runner.workflow_params(wf.get("nodes"))
+    inputs, shown = _collect_workflow_inputs(specs, params or [])
+    payload = {"inputs": inputs, "send_email": bool(notify), "user_email": notify or ""}
+
+    try:
+        with render.run_activity(render.RunActivity("Starting the run", "")):
+            queued = resources.trigger_workflow_run(client, wf["id"], payload) or {}
+    except KeyboardInterrupt:
+        typer.echo("Interrupted — the run may already be queued. Check:  sagex list run", err=True)
+        raise typer.Exit(code=130)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        raise typer.Exit(code=1)
+
+    run_id = str(queued.get("workflow_run_id") or "")
+    if not run_id:
+        typer.echo("✗ The server didn't return a run id.")
+        raise typer.Exit(code=1)
+
+    raise typer.Exit(code=_watch_new_run(client, wf, run_id, shown, no_log))
+
+
+def _watch_new_run(client, wf: dict, run_id: str, shown: dict, no_log: bool,
+                   via: str | None = None) -> int:
+    """Print the run header, then follow the run live; returns the CLI exit code."""
+    view = runview.WorkflowRunView.from_workflow(wf)
+    render.workflow_run_header(wf.get("name") or "(workflow)", len(view.order), shown, via)
+    if os.environ.get("SAGEX_EVENTS") == "1":
+        print(runview.event_line({"t": "start", "run_id": run_id, "view": view.snapshot()}),
+              file=sys.stderr, flush=True)
+    workspace = None if no_log else Path(config.workspace_dir())
+    return _follow_workflow_run(client, run_id, view, workspace)
+
+
+def _parse_iso(iso: str | None) -> datetime | None:
+    try:
+        dt = datetime.fromisoformat(iso)
+    except (TypeError, ValueError):
+        return None
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+@trigger_app.command("watch")
+def trigger_watch_cmd(
+    ref: str = typer.Argument(..., help="Workflow name, or schedule trigger id."),
+    no_log: bool = typer.Option(False, "--no-log", help="Don't save the run's logs under <workspace>/logs/workflow/<run_id>/."),
+) -> None:
+    """Wait for a schedule's next run, then follow it live.
+
+    Counts down to the next firing (times come from the server, using the scheduler's own rules), then follows the run with the live graph. If a firing passes without a run (e.g. the previous run was still going) it says why and keeps waiting. Ctrl+C stops watching.
+    """
+    client = _client_or_exit()
+    with _setup_errors(), render.run_activity(render.RunActivity("Looking up the schedule", "ctrl+c to cancel")):
+        kind, trig = resources.resolve_trigger(client, ref)
+        if kind != "schedule":
+            raise _RunSetupError(
+                "✗ That's an HTTP trigger — it runs when it's called, not on a schedule.",
+                f"  Call it now:  sagex trigger fire \"{trig.get('workflow_name')}\"",
+            )
+        wf = resources.get_workflow_detail(client, trig.get("workflow_id"))
+
+    name = wf.get("name") or trig.get("workflow_name")
+    if not trig.get("is_active", True):
+        typer.echo(f"✗ This schedule is disabled. Enable it first:  sagex trigger enable \"{name}\"")
+        raise typer.Exit(code=1)
+
+    baseline = trig.get("last_run_id")
+    upcoming = [t for t in map(_parse_iso, trig.get("next_runs") or []) if t]
+    next_at = upcoming[0] if upcoming else None      # None: an older server without next_runs
+    activity = render.RunActivity("Waiting for the next run", "ctrl+c to stop watching")
+    run_id, errors, last_poll = None, 0, time.monotonic()
+    try:
+        with render.run_activity(activity):
+            while run_id is None:
+                now = datetime.now(timezone.utc)
+                remaining = (next_at - now).total_seconds() if next_at else None
+                if next_at:
+                    clock = next_at.astimezone().strftime("%H:%M")
+                    activity.set(f"Next run {render.time_until(remaining)} (at {clock})" if remaining > 0
+                                 else "Waiting for the scheduled run to start")
+                # Poll gently while it's far off, briskly around the firing time.
+                interval = 3 if remaining is None or remaining <= 10 else 15
+                if time.monotonic() - last_poll >= interval:
+                    last_poll = time.monotonic()
+                    try:
+                        detail = resources.get_schedule_trigger(client, trig.get("workflow_id"), trig.get("node_id"))
+                        errors = 0
+                    except ApiError as exc:
+                        detail = None
+                        errors += 1
+                        render.run_stderr(f"✗ {exc.message}")
+                        if errors >= 3:
+                            raise typer.Exit(code=1)
+                    if detail and detail.get("last_run_id") and detail.get("last_run_id") != baseline:
+                        run_id = str(detail["last_run_id"])
+                        break
+                    fresh = [t for t in map(_parse_iso, (detail or {}).get("next_runs") or []) if t]
+                    # A firing that passed (with a minute's grace) without starting a run.
+                    if next_at and remaining < -60 and fresh and fresh[0] > next_at:
+                        reason = detail.get("last_error") or "no run started — is the scheduler (Celery Beat) running?"
+                        render.run_note(f"The {next_at.astimezone().strftime('%H:%M')} run didn't start: {reason}")
+                        next_at = fresh[0]
+                    elif next_at is None and fresh:
+                        next_at = fresh[0]
+                time.sleep(1)
+    except KeyboardInterrupt:
+        render.run_note("Stopped watching.")
+        raise typer.Exit(code=130)
+
+    raise typer.Exit(code=_watch_new_run(client, wf, run_id, {}, no_log, via="via schedule"))
+
+
+def _fire_schedule_now(client, trig: dict, wf: dict, no_follow: bool, no_log: bool) -> int:
+    """Fire a schedule now (scheduler path) and follow the run; returns the exit code."""
+    name = wf.get("name") or trig.get("workflow_name")
+    if not trig.get("is_active", True):
+        typer.echo(f"✗ This schedule is disabled. Enable it first:  sagex trigger enable \"{name}\"")
+        return 1
+    try:
+        with render.run_activity(render.RunActivity("Firing the schedule", "")):
+            queued = resources.fire_schedule_now(client, trig.get("workflow_id"), trig.get("node_id")) or {}
+    except KeyboardInterrupt:
+        typer.echo("Interrupted — the run may already be queued. Check:  sagex list run", err=True)
+        return 130
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        if exc.status == 404 and exc.message.startswith("Request failed"):
+            typer.echo("  Your server may predate firing schedules on demand — update it.")
+        return 1
+
+    run_id = str(queued.get("workflow_run_id") or "")
+    if not run_id:
+        typer.echo("✗ The server didn't return a run id.")
+        return 1
+    if no_follow:
+        typer.echo(f"✓ Queued scheduled run {run_id}.")
+        typer.echo(f"  Check it:  sagex show run {run_id}")
+        return 0
+    return _watch_new_run(client, wf, run_id, {}, no_log, via="via schedule · fired now")
+
+
+def _read_trigger_secret(secret_file: str | None) -> str:
+    """The HTTP trigger secret: from --secret-file, else a hidden prompt. Never a flag
+    (shell history / process list) and never stored."""
+    if secret_file:
+        secret = _read_secret_file(secret_file).strip()
+    elif sys.stdin.isatty() and sys.stderr.isatty():
+        secret = typer.prompt("Trigger secret", hide_input=True, err=True).strip()
+    else:
+        typer.echo("✗ The trigger secret is typed at a hidden prompt — run this in a terminal, or pass --secret-file <path>.")
+        raise typer.Exit(code=1)
+    if not secret:
+        typer.echo("✗ The trigger secret is empty.")
+        raise typer.Exit(code=1)
+    return secret
+
+
+@trigger_app.command("fire")
+def trigger_fire_cmd(
+    ref: str = typer.Argument(..., help="Workflow name, or trigger id."),
+    params: list[str] = typer.Option(None, "--param", "-p", help="Set a parameter as NAME=VALUE (or PARAM_ID=VALUE when a name repeats). Repeatable; secrets are asked for at a hidden prompt."),
+    secret_file: str = typer.Option(None, "--secret-file", help="Read the trigger secret from this file instead of a hidden prompt."),
+    idempotency_key: str = typer.Option(None, "--idempotency-key", help="Send this Idempotency-Key (default: a new random one). Reusing a key returns the run it started."),
+    no_follow: bool = typer.Option(False, "--no-follow", help="Just queue the run and print its id and polling URL."),
+    no_log: bool = typer.Option(False, "--no-log", help="Don't save the run's logs under <workspace>/logs/workflow/<run_id>/."),
+) -> None:
+    """Fire a trigger now and follow the run live: an HTTP trigger is called exactly as a webhook caller would; a schedule is fired through the scheduler's own path.
+
+    HTTP: sends only the trigger secret and an Idempotency-Key (no API key), so it tests the real webhook path. The secret is typed at a hidden prompt or read from --secret-file, never passed as a flag. Parameters work like `sagex run workflow`. Schedule: runs it now exactly as its cron would (no parameters; skipped if its previous run is still going). Ctrl+C cancels the run (press it again to detach).
+    """
+    client = _client_or_exit()
+    with _setup_errors(), render.run_activity(render.RunActivity("Looking up the trigger", "ctrl+c to cancel")):
+        kind, trig = resources.resolve_trigger(client, ref)
+        wf = resources.get_workflow_detail(client, trig.get("workflow_id"))
+
+    if kind == "schedule":
+        if params or secret_file or idempotency_key:
+            typer.echo("✗ A schedule fires with no parameters, secret or Idempotency-Key — drop those options.")
+            raise typer.Exit(code=1)
+        raise typer.Exit(code=_fire_schedule_now(client, trig, wf, no_follow, no_log))
+
+    if not trig.get("is_active", True):
+        typer.echo(f"✗ This HTTP trigger is disabled. Enable it first:  sagex trigger enable \"{wf.get('name')}\"")
+        raise typer.Exit(code=1)
+    path = resources.http_trigger_path(trig)
+    if not path:
+        typer.echo("✗ Couldn't work out this trigger's URL. See:  sagex trigger invoke …")
+        raise typer.Exit(code=1)
+
+    specs = runner.workflow_params(wf.get("nodes"))
+    inputs, shown = _collect_workflow_inputs(specs, params or [])
+    secret = _read_trigger_secret(secret_file)
+    key = idempotency_key or str(uuid.uuid4())
+
+    try:
+        with render.run_activity(render.RunActivity("Calling the webhook", "")):
+            queued = resources.fire_http_trigger(client, path, secret, key, inputs) or {}
+    except KeyboardInterrupt:
+        typer.echo(f"Interrupted — the run may already be queued (Idempotency-Key {key}). Check:  sagex list run", err=True)
+        raise typer.Exit(code=130)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        if exc.status == 401:
+            typer.echo(f"  The secret ends ••••{trig.get('secret_last4')}. Lost it? Rotate it:  sagex trigger regenerate \"{wf.get('name')}\"")
+        raise typer.Exit(code=1)
+
+    run_id = str(queued.get("workflow_run_id") or "")
+    if not run_id:
+        typer.echo("✗ The webhook didn't return a run id.")
+        raise typer.Exit(code=1)
+    if queued.get("idempotent"):
+        render.note("That Idempotency-Key was already used, so no new run was queued — this is the run it started.")
+    if no_follow:
+        what = "Run" if queued.get("idempotent") else "Queued run"
+        typer.echo(f"✓ {what} {run_id} via the HTTP trigger (Idempotency-Key {key}).")
+        if queued.get("polling_url"):
+            typer.echo(f"  Polling URL (GET with X-Trigger-Secret):  {queued['polling_url']}")
+        typer.echo(f"  Poll it from here:  sagex trigger poll {run_id} --watch")
+        return
+    raise typer.Exit(code=_watch_new_run(client, wf, run_id, shown, no_log,
+                                         via=f"via HTTP trigger · Idempotency-Key {key}"))
+
+
+def _graph_for_run(client, run_id: str) -> dict | None:
+    """The graph shape of a webhook run's workflow (best effort; None if unavailable)."""
+    try:
+        return resources.resolve_http_trigger_run(client, run_id).get("workflow")
+    except (ApiError, resources.AmbiguousResource, AttributeError):
+        return None
+
+
+def _find_trigger_run(client, target: str, run_ref: str | None) -> dict:
+    """One server lookup for `trigger poll`: the trigger run named by TARGET (+ RUN).
+    Exits with a hint when it can't be found."""
+    try:
+        with render.run_activity(render.RunActivity("Finding the run", "ctrl+c to cancel")):
+            return resources.resolve_http_trigger_run(client, target, run_ref)
+    except KeyboardInterrupt:
+        raise typer.Exit(code=130)
+    except resources.AmbiguousResource as exc:
+        render.ambiguous(exc)
+        raise typer.Exit(code=1)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        code = exc.errors.get("code") if isinstance(exc.errors, dict) else None
+        hint = {
+            "not_webhook_run": f"  See it with:  sagex show run {target}",
+            "no_runs_yet": f"  Fire it:  sagex trigger fire \"{target}\"",
+            "run_not_found": f"  Only runs this webhook started can be polled. See it with:  sagex show run {run_ref}",
+            "trigger_not_found": "  See your triggers:  sagex list trigger",
+            "not_found": "  See your triggers:  sagex list trigger",
+        }.get(code)
+        if hint is None and exc.status == 404:
+            hint = "  Your server may predate this lookup — update it, or pass the full polling URL."
+        if hint:
+            typer.echo(hint)
+        raise typer.Exit(code=1)
+
+
+def _apply_poll(view: "runview.WorkflowRunView", data: dict) -> None:
+    """Apply a polling response (node records + run status) to the graph."""
+    now = datetime.now(timezone.utc).isoformat()
+    for n in data.get("nodes") or []:
+        if n.get("status"):
+            event = {"t": "node", "id": n.get("node_id"), "status": n["status"],
+                     "exit_code": n.get("exit_code"),
+                     "duration": _iso_seconds(n.get("started_at"), n.get("finished_at"))}
+            if n["status"] == "running":
+                event["elapsed"] = _iso_seconds(n.get("started_at"), now)
+            _emit_run_event(view, event)
+    _emit_run_event(view, {"t": "run", "status": data.get("status")})
+
+
+@trigger_app.command("poll")
+def trigger_poll_cmd(
+    target: str = typer.Argument(..., help="A run id (or its first few characters), a trigger id / workflow name (= its latest run), or a polling URL."),
+    run_ref: str = typer.Argument(None, metavar="[RUN]", help="A run id, when TARGET is a trigger or workflow."),
+    secret_file: str = typer.Option(None, "--secret-file", help="Read the trigger secret from this file instead of a hidden prompt."),
+    watch: bool = typer.Option(False, "--watch", "-w", help="Keep polling until the run finishes."),
+    interval: float = typer.Option(3.0, "--interval", help="Seconds between polls with --watch (minimum 2)."),
+) -> None:
+    """Check a run through its HTTP trigger's polling URL — exactly what a webhook caller sees.
+
+    Pass a run id (as `trigger fire` prints), a trigger id or workflow name for its latest webhook run, or the full polling URL. Polls with only the trigger secret (no API key), typed at a hidden prompt or read from --secret-file. Shows the run as a graph, once, or live with --watch. Ctrl+C stops watching; the run carries on.
+    """
+    client = _client_or_exit()
+    parsed = resources.http_trigger_poll_path(target)
+    if parsed and run_ref:
+        typer.echo("✗ The polling URL already names the run — drop the extra run id.")
+        raise typer.Exit(code=1)
+    found = None if parsed else _find_trigger_run(client, target, run_ref)   # one lookup
+    path, run_id = parsed if parsed else (found["polling_path"], str(found["run"]["id"]))
+
+    secret = _read_trigger_secret(secret_file)
+    try:
+        with render.run_activity(render.RunActivity("Checking the run", "")):
+            if found:
+                (data,) = runner.fetch_parallel(lambda: resources.poll_http_trigger_run(client, path, secret))
+                wf = found.get("workflow")
+            else:   # from a URL: fetch the graph shape alongside the poll
+                data, wf = runner.fetch_parallel(
+                    lambda: resources.poll_http_trigger_run(client, path, secret),
+                    lambda: _graph_for_run(client, run_id),
+                )
+    except KeyboardInterrupt:
+        raise typer.Exit(code=130)
+    except ApiError as exc:
+        typer.echo(f"✗ {exc.message}")
+        if exc.status == 404:
+            typer.echo(f"  Only runs this webhook started can be polled. See it with:  sagex show run {run_id}")
+        raise typer.Exit(code=1)
+
+    data = data or {}
+    if wf:
+        view = runview.WorkflowRunView.from_workflow(wf)
+    else:   # no access to the workflow's shape: show the polled nodes as a flat list
+        records = sorted(data.get("nodes") or [], key=lambda n: n.get("execution_order") or 0)
+        view = runview.WorkflowRunView(f"Run {run_id}", [
+            {"id": n.get("node_id"), "label": n.get("node_label") or n.get("node_id"), "kind": ""}
+            for n in records], [])
+    if os.environ.get("SAGEX_EVENTS") == "1":
+        print(runview.event_line({"t": "start", "run_id": run_id, "view": view.snapshot()}),
+              file=sys.stderr, flush=True)
+    _apply_poll(view, data)
+
+    stopped = False
+    if watch and not view.finished:
+        interval = max(interval, 2.0)
+        activity = render.RunActivity("Polling", f"every {interval:g}s · ctrl+c to stop watching")
+        errors = 0
+        with render.run_activity(activity, above=view):
+            while not view.finished:
+                try:
+                    time.sleep(interval)
+                    data = resources.poll_http_trigger_run(client, path, secret) or {}
+                    errors = 0
+                    _apply_poll(view, data)
+                except KeyboardInterrupt:
+                    stopped = True
+                    break
+                except ApiError as exc:
+                    errors += 1
+                    render.run_stderr(f"✗ {exc.message}")
+                    if errors >= 3:
+                        break
+
+    if os.environ.get("SAGEX_EVENTS") != "1":       # the TUI draws its own graph
+        render.workflow_run_graph(view)
+    if view.finished:
+        if view.status == "failed" and data.get("error_message"):
+            render.run_stderr(data["error_message"])
+        total = _iso_seconds(data.get("started_at"), data.get("finished_at")) or 0.0
+        render.run_summary(view.status, None, total, run_id, noun="run")
+    else:
+        why = "Stopped watching — the run carries on" if stopped else f"Still {view.status}"
+        hint = "" if watch and not stopped else f"  ·  watch it:  sagex trigger poll {run_id} --watch"
+        render.run_note(f"{why} (run {run_id}).{hint}")
+
+    if stopped:
+        raise typer.Exit(code=130)
+    if watch:
+        raise typer.Exit(code=0 if view.status == "success" else 1)
+
+
+if __name__ == "__main__":
+    app()