runtime-sdk 0.4.49__py3-none-win_amd64.whl

runtime_sdk/cli.py

@@ -0,0 +1,985 @@
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+
+from runtime_sdk import __version__, account, arguments, completion, computers, files as file_commands, github as github_commands, goals, output as cli_output, providers, proxy, secrets as secret_commands, services, ssh as ssh_commands
+from runtime_sdk.auth import authenticated_client, has_credentials
+from runtime_sdk.client import RuntimeAPIError
+from runtime_sdk.config import (
+    DEFAULT_BASE_URL,
+    RuntimeConfig,
+    RuntimeConfigError,
+    load_config,
+)
+
+
+# --------------------------------------------------------------------------- #
+# argparse                                                                    #
+# --------------------------------------------------------------------------- #
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="runtime",
+        description="Manage RuntimeVM computers — run code, publish apps, share URLs.",
+    )
+    parser.add_argument("--base-url", help="Override the Runtime API base URL")
+    parser.add_argument("--version", action="version", version=f"runtime-sdk {__version__}")
+
+    # Bare TTY `runtime` opens the dashboard; non-interactive use requires an
+    # explicit command so invoking the CLI can never create a computer by accident.
+    subparsers = parser.add_subparsers(dest="command", required=False)
+
+    login = subparsers.add_parser("login", help="Sign in with WorkOS device authorization")
+    login.add_argument(
+        "--no-open",
+        action="store_true",
+        help="Print the verification URL without opening a browser",
+    )
+    login.add_argument(
+        "--api-key",
+        nargs="?",
+        const="",
+        default=None,
+        help="Import an API key explicitly (prompts if omitted in interactive mode)",
+    )
+
+    subparsers.add_parser("whoami")
+    subparsers.add_parser("logout")
+
+    api_keys_cmd = subparsers.add_parser("api-keys", help="Manage WorkOS API keys")
+    api_keys_subparsers = api_keys_cmd.add_subparsers(dest="api_keys_action", required=True)
+    api_keys_subparsers.add_parser("list", aliases=["ls"], help="List API keys")
+    api_keys_create = api_keys_subparsers.add_parser("create", help="Create a new API key")
+    api_keys_create.add_argument("name", nargs="?", default=None, help="Human-friendly name for the new API key")
+    api_keys_revoke = api_keys_subparsers.add_parser("revoke", help="Revoke an API key")
+    api_keys_revoke.add_argument("id", nargs="?", default=None, help="API key id")
+
+    secrets_cmd = subparsers.add_parser("secrets", help="Manage account-level secret sets")
+    secrets_subparsers = secrets_cmd.add_subparsers(dest="secrets_action", required=True)
+    secrets_subparsers.add_parser("list", aliases=["ls"], help="List secret sets")
+    secrets_show = secrets_subparsers.add_parser("show", help="Show one secret set")
+    secrets_show.add_argument("slug", nargs="?", default=None, help="Secret set slug")
+    secrets_set = secrets_subparsers.add_parser("set", help="Create or replace a secret set from KEY=VALUE pairs")
+    secrets_set.add_argument("slug", nargs="?", default=None, help="Secret set slug")
+    secrets_set.add_argument("pairs", nargs="*", help="KEY=VALUE pairs")
+    secrets_set.add_argument("--proxy", action="append", default=[], metavar="KEY=HOST", help="Deliver KEY through the egress proxy and inject it only for HOST")
+    secrets_import = secrets_subparsers.add_parser("import", help="Create or replace a secret set from a .env file")
+    secrets_import.add_argument("slug", nargs="?", default=None, help="Secret set slug")
+    secrets_import.add_argument("--env-file", required=True, help="Path to .env file")
+    secrets_import.add_argument("--proxy", action="append", default=[], metavar="KEY=HOST", help="Deliver KEY through the egress proxy and inject it only for HOST")
+    secrets_delete = secrets_subparsers.add_parser("delete", aliases=["rm"], help="Delete a secret set")
+    secrets_delete.add_argument("slug", nargs="?", default=None, help="Secret set slug")
+
+    codex_cmd = subparsers.add_parser("codex", help="Manage Runtime's saved Codex credential")
+    codex_subparsers = codex_cmd.add_subparsers(dest="codex_action", required=True)
+    codex_login = codex_subparsers.add_parser("login", help="Open Codex login and save it to Runtime")
+    codex_login.add_argument("--device", action="store_true", help="Use Codex device-code login")
+    codex_subparsers.add_parser("status", help="Show whether Runtime has a saved Codex credential")
+    codex_subparsers.add_parser("logout", help="Remove Runtime's saved Codex login")
+
+    claude_cmd = subparsers.add_parser("claude", help="Manage Runtime's saved Claude Code credential")
+    claude_subparsers = claude_cmd.add_subparsers(dest="claude_action", required=True)
+    claude_subparsers.add_parser("login", help="Open Claude login and save it to Runtime")
+    claude_subparsers.add_parser("status", help="Show whether Runtime has a saved Claude Code credential")
+    claude_subparsers.add_parser("logout", help="Remove Runtime's saved Claude login")
+
+    grok_cmd = subparsers.add_parser("grok", help="Manage Runtime's saved Grok credential")
+    grok_subparsers = grok_cmd.add_subparsers(dest="grok_action", required=True)
+    grok_subparsers.add_parser("login", help="Import the local Grok login into Runtime")
+    grok_subparsers.add_parser("status", help="Show whether Runtime has a saved Grok credential")
+    grok_subparsers.add_parser("logout", help="Remove Runtime's saved Grok login")
+
+    xai_cmd = subparsers.add_parser("xai", help="Manage Runtime's saved xAI API key")
+    xai_subparsers = xai_cmd.add_subparsers(dest="xai_action", required=True)
+    xai_login = xai_subparsers.add_parser("login", help="Save an xAI API key to Runtime")
+    xai_login.add_argument("--api-key", default=None, help="xAI API key; defaults to XAI_API_KEY or an interactive prompt")
+    xai_subparsers.add_parser("status", help="Show whether Runtime has a saved xAI API key")
+    xai_subparsers.add_parser("logout", help="Remove Runtime's saved xAI login")
+
+    github_cmd = subparsers.add_parser("github", help="Manage connected GitHub App installations")
+    github_subparsers = github_cmd.add_subparsers(dest="github_action", required=True)
+    github_subparsers.add_parser("list", aliases=["ls"], help="List connected GitHub installations")
+    github_disconnect = github_subparsers.add_parser("disconnect", aliases=["rm"], help="Disconnect a GitHub installation from Runtime")
+    github_disconnect.add_argument("ref", nargs="?", default=None, help="GitHub owner or installation id")
+
+    integrate_cmd = subparsers.add_parser("integrate", help="Connect the RuntimeVM GitHub App")
+    integrate_cmd.add_argument("provider", choices=["github"])
+    integrate_cmd.add_argument("--no-open", action="store_true", help="Print the install URL instead of opening a browser")
+    integrate_cmd.add_argument("--timeout", type=int, default=180, help="Seconds to wait for the browser install to finish (default: 180)")
+
+    switch_cmd = subparsers.add_parser(
+        "switch",
+        aliases=["checkout"],
+        help="Open a GitHub branch workspace in its own computer",
+    )
+    switch_cmd.add_argument("branch", nargs="?", default=None, help="Git branch to open")
+    switch_cmd.add_argument("--repo", default=None, help="GitHub repository in owner/name format")
+    switch_cmd.add_argument("-c", "--create", action="store_true", help="Create a new branch before opening it")
+    switch_cmd.add_argument("--from", dest="base_branch", default=None, help="Base branch for -c (defaults to the repo default branch)")
+
+    create_cmd = subparsers.add_parser("create", help="Create a new computer with the starter app published by default")
+    create_cmd.add_argument(
+        "name",
+        nargs="?",
+        default=None,
+        help="Subdomain name (e.g. redsox → redsox.runruntime.dev). Random if skipped.",
+    )
+    create_cmd.add_argument("--command", dest="startup_command", help="Initial service command to save on create")
+    create_cmd.add_argument("--cwd", help="Working directory for the initial service command")
+    create_cmd.add_argument("--port", type=int, help="App port to publish for the initial service")
+    create_cmd.add_argument("--network", choices=["open", "allowlist", "none"], help="Override the account network default")
+    create_cmd.add_argument("--allow-host", action="append", default=[], help="Allowed host; repeat with --network allowlist")
+
+    network_cmd = subparsers.add_parser("network", help="Manage default and per-computer outbound network access")
+    network_subparsers = network_cmd.add_subparsers(dest="network_action", required=True)
+    network_default = network_subparsers.add_parser("default", help="Manage the default for newly created computers")
+    network_default_subparsers = network_default.add_subparsers(dest="network_default_action", required=True)
+    network_default_subparsers.add_parser("show", help="Show the default network policy")
+    network_default_subparsers.add_parser("open", help="Allow public network access by default")
+    network_default_subparsers.add_parser("none", help="Block public network access by default")
+    network_default_allowlist = network_default_subparsers.add_parser("allowlist", help="Allow only listed HTTP/HTTPS hosts by default")
+    network_default_allowlist.add_argument("hosts", nargs="+", help="Exact hosts or wildcard subdomains such as *.example.com")
+    network_show = network_subparsers.add_parser("show", help="Show one computer's network policy")
+    network_show.add_argument("id", nargs="?", default=None, help="Computer ID or name")
+    network_denials = network_subparsers.add_parser("denials", help="Show hosts recently denied by one computer's policy")
+    network_denials.add_argument("id", nargs="?", default=None, help="Computer ID or name")
+    network_set = network_subparsers.add_parser("set", help="Set one computer's network policy")
+    network_set.add_argument("id", help="Computer ID or name")
+    network_set.add_argument("mode", choices=["open", "allowlist", "none"])
+    network_set.add_argument("hosts", nargs="*", help="Hosts required for allowlist mode")
+    list_cmd = subparsers.add_parser("list", aliases=["ls"], help="List computers")
+    list_cmd.add_argument(
+        "--json",
+        action="store_true",
+        help="Write machine-readable JSON instead of opening the interactive dashboard",
+    )
+    list_cmd.add_argument(
+        "-w",
+        "--watch",
+        nargs="?",
+        const=2,
+        type=int,
+        default=None,
+        metavar="SECONDS",
+        help="Refresh the TUI or NDJSON stream every N seconds (default 2)",
+    )
+
+    enter_cmd = subparsers.add_parser(
+        "enter",
+        help="Enter a computer's console",
+        epilog="Use `runtime exec` for exact exit codes; use `runtime enter <id> -- <cmd>` for interactive TTY commands.",
+    )
+    enter_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    enter_cmd.add_argument("enter_command", nargs="*", help="Command to run in the interactive terminal")
+
+    ssh_cmd = subparsers.add_parser(
+        "ssh",
+        help="SSH into a computer through Runtime",
+        epilog="Extra arguments after the computer id are passed to ssh after the destination.",
+    )
+    ssh_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    ssh_cmd.add_argument("ssh_args", nargs=argparse.REMAINDER, help="Remote command or ssh arguments")
+
+    info_cmd = subparsers.add_parser("info", help="Get computer details")
+    info_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+
+    url_cmd = subparsers.add_parser("url", help="Show a computer's public URL and live published port")
+    url_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+
+    share_cmd = subparsers.add_parser("share", help="Set whether a computer is public or private")
+    share_subparsers = share_cmd.add_subparsers(dest="share_action", required=True)
+    share_public = share_subparsers.add_parser("public", help="Make a computer publicly accessible")
+    share_public.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    share_private = share_subparsers.add_parser("private", help="Require owner auth before browser access")
+    share_private.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+
+    start_cmd = subparsers.add_parser("start", help="Wake a cold computer")
+    start_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+
+    delete_cmd = subparsers.add_parser("delete", aliases=["rm"], help="Delete a computer")
+    delete_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    delete_cmd.add_argument(
+        "--force",
+        "-y",
+        action="store_true",
+        help="Skip the typed-name confirmation prompt",
+    )
+
+    run_cmd = subparsers.add_parser("run", help="Run a one-shot command in a computer")
+    run_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    run_cmd.add_argument(
+        "run_command",
+        metavar="command",
+        nargs="?",
+        default=None,
+        help="Command to run",
+    )
+    run_cmd.add_argument("--uid", type=int, help="User ID")
+    run_cmd.add_argument("--gid", type=int, help="Group ID")
+    run_cmd.add_argument("--cwd", help="Working directory")
+    run_cmd.add_argument("--shell", help="Shell to use")
+
+    exec_cmd = subparsers.add_parser("exec", help="Stream a command in a computer")
+    exec_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    exec_cmd.add_argument("exec_command", nargs="*", help="Command after --")
+    exec_cmd.add_argument("--stdin", action="store_true", help="Pipe local stdin to the command")
+    exec_cmd.add_argument("--uid", type=int, help="User ID")
+    exec_cmd.add_argument("--gid", type=int, help="Group ID")
+    exec_cmd.add_argument("--cwd", help="Working directory")
+    exec_cmd.add_argument("--shell", help="Shell to use")
+
+    files_cmd = subparsers.add_parser("files", aliases=["fs", "file"], help="Read, write, list, and delete files")
+    files_subparsers = files_cmd.add_subparsers(dest="files_action", required=True)
+    files_read = files_subparsers.add_parser("read", help="Read a file to stdout or --output")
+    files_read.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    files_read.add_argument("path", nargs="?", default=None, help="Path inside the computer")
+    files_read.add_argument("--output", "-o", help="Local output file")
+    files_write = files_subparsers.add_parser("write", help="Write stdin, --content, or --input into a file")
+    files_write.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    files_write.add_argument("path", nargs="?", default=None, help="Path inside the computer")
+    files_write.add_argument("--input", "-i", help="Local input file (defaults to stdin)")
+    files_write.add_argument("--content", help="Literal text to write")
+    files_write.add_argument("--mode", help="File mode, e.g. 0644")
+    files_write.add_argument("--uid", type=int, help="User ID")
+    files_write.add_argument("--gid", type=int, help="Group ID")
+    files_list = files_subparsers.add_parser("list", aliases=["ls"], help="List a directory")
+    files_list.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    files_list.add_argument("path", nargs="?", default=None, help="Directory path")
+    files_stat = files_subparsers.add_parser("stat", help="Show file metadata")
+    files_stat.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    files_stat.add_argument("path", nargs="?", default=None, help="Path inside the computer")
+    files_mkdir = files_subparsers.add_parser("mkdir", help="Create a directory")
+    files_mkdir.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    files_mkdir.add_argument("path", nargs="?", default=None, help="Directory path")
+    files_mkdir.add_argument("--parents", "-p", action="store_true", help="Create parent directories")
+    files_mkdir.add_argument("--mode", help="Directory mode, e.g. 0755")
+    files_rm = files_subparsers.add_parser("rm", aliases=["delete"], help="Delete a file or directory")
+    files_rm.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    files_rm.add_argument("path", nargs="?", default=None, help="Path inside the computer")
+    files_rm.add_argument("--recursive", "-r", action="store_true", help="Delete directories recursively")
+    files_upload = files_subparsers.add_parser("upload", help="Upload a local file or directory")
+    files_upload.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    files_upload.add_argument("local", nargs="?", default=None, help="Local file or directory")
+    files_upload.add_argument("remote", nargs="?", default=None, help="Remote destination directory")
+    files_download = files_subparsers.add_parser("download", help="Download a remote file or directory")
+    files_download.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    files_download.add_argument("remote", nargs="?", default=None, help="Remote file or directory")
+    files_download.add_argument("local", nargs="?", default=None, help="Local destination directory")
+
+    publish_cmd = subparsers.add_parser(
+        "publish", help="Promote the running app on a local port into the durable public app"
+    )
+    publish_cmd.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    publish_cmd.add_argument("port", nargs="?", type=int, default=None, help="Local app port")
+    publish_cmd.add_argument("publish_command", nargs="*", help="Command after --")
+
+    startup_cmd = subparsers.add_parser("startup", help=argparse.SUPPRESS)
+    startup_subparsers = startup_cmd.add_subparsers(dest="startup_action", required=True)
+    startup_show = startup_subparsers.add_parser("show", help="Show durable startup config")
+    startup_show.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    startup_set = startup_subparsers.add_parser("set", help="Set durable startup config")
+    startup_set.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    startup_set.add_argument("--command", dest="startup_value_command", required=True, help="Durable startup command")
+    startup_set.add_argument("--cwd", help="Working directory for the durable startup command")
+    startup_set.add_argument("--port", required=True, type=int, help="App port to publish for durable startup")
+    startup_clear = startup_subparsers.add_parser("clear", help="Clear durable startup config")
+    startup_clear.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+
+    service_cmd = subparsers.add_parser("service", help="Manage the durable published app service")
+    service_subparsers = service_cmd.add_subparsers(dest="service_action", required=True)
+    service_run = service_subparsers.add_parser("run", help="Start and publish a durable service command")
+    service_run.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    service_run.add_argument("--port", required=True, type=int, help="Service port")
+    service_run.add_argument("--cwd", help="Working directory for the service command")
+    service_run.add_argument("service_command", nargs="*", help="Command after --")
+    service_show = service_subparsers.add_parser("show", help="Show the durable published app service")
+    service_show.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    service_status = service_subparsers.add_parser("status", help="Show durable service status")
+    service_status.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    service_logs = service_subparsers.add_parser("logs", help="Stream durable service logs")
+    service_logs.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    service_logs.add_argument("--follow", action="store_true", help="Follow live logs")
+    service_restart = service_subparsers.add_parser("restart", help="Restart the durable service")
+    service_restart.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    service_stop = service_subparsers.add_parser("stop", help="Stop the durable service but keep its config")
+    service_stop.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    service_clear = service_subparsers.add_parser("clear", help="Clear the durable published app service")
+    service_clear.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+
+    goal_cmd = subparsers.add_parser("goal", help="Watch email-triggered Codex goal runs")
+    goal_subparsers = goal_cmd.add_subparsers(dest="goal_action", required=True)
+    goal_watch = goal_subparsers.add_parser("watch", help="Stream a goal run from inside a computer")
+    goal_watch.add_argument("id", nargs="?", default=None, help="Computer ID (hostname)")
+    goal_watch.add_argument("--latest", action="store_true", help="Watch the latest known goal run")
+    goal_watch.add_argument("--next", action="store_true", help="Wait for and watch the next goal run")
+    goal_watch.add_argument("--email-id", help="Watch a specific Runtime email id, e.g. eml_...")
+    goal_watch.add_argument("--timeout", type=int, default=0, help="Stop after N seconds (default: no timeout)")
+
+    proxy_cmd = subparsers.add_parser("proxy", help="Manage background local port proxies")
+    proxy_subparsers = proxy_cmd.add_subparsers(dest="proxy_command", required=True)
+    proxy_start = proxy_subparsers.add_parser("start", help="Start one or more background local port proxies")
+    proxy_start.add_argument("id", help="Computer ID (hostname)")
+    proxy_start.add_argument("ports", nargs="+", help="Port mappings like 5432 or 15432:5432")
+    proxy_subparsers.add_parser("ls", help="List background local port proxies")
+    proxy_stop = proxy_subparsers.add_parser("stop", help="Stop one or more background local port proxies")
+    proxy_stop.add_argument("local_ports", nargs="*", type=int, help="Local ports to stop")
+    proxy_stop.add_argument("--all", action="store_true", help="Stop all running proxies")
+
+    proxy_agent = subparsers.add_parser("_proxy_agent", help=argparse.SUPPRESS)
+    proxy_agent.add_argument("--base-url", required=True)
+    proxy_agent.add_argument("--computer-id", required=True)
+    proxy_agent.add_argument("--display-name", required=True)
+    proxy_agent.add_argument("--local-port", type=int, required=True)
+    proxy_agent.add_argument("--remote-port", type=int, required=True)
+
+    help_cmd = subparsers.add_parser("help", help="Show extended help for a topic")
+    help_cmd.add_argument("topic", nargs="?", default=None, help="Topic to show (computer, share, account, all)")
+
+    completion_cmd = subparsers.add_parser(
+        "completion", help="Print shell completion script"
+    )
+    completion_cmd.add_argument(
+        "shell", choices=["bash", "zsh", "fish", "powershell"], help="Target shell"
+    )
+
+    # Internal commands used by completion and the packaged TUI.
+    subparsers.add_parser("_slugs", help=argparse.SUPPRESS)
+    subparsers.add_parser("_tui_state", help=argparse.SUPPRESS)
+
+    parser.format_help = lambda: _format_top_help()  # type: ignore[assignment]
+    return parser
+
+
+_HELP_SECTIONS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
+    (
+        "Computers",
+        (
+            ("create [name]", "Create a new computer (starter app published by default)"),
+            ("list, ls", "Open the computer dashboard (--json for scripts; -w refreshes)"),
+            ("info [id]", "Show computer details"),
+            ("url [id]", "Show a computer's public URL and live published port"),
+            ("start [id]", "Wake a cold computer"),
+            ("enter [id] [-- <cmd>]", "Enter a computer's console or interactive TTY command"),
+            ("ssh [id] [-- <cmd>]", "SSH into a computer through Runtime's authenticated tunnel"),
+            ("run [id] <cmd>", "Run a one-shot command"),
+            ("exec [id] -- <cmd>", "Stream stdout/stderr and optionally pipe stdin"),
+            ("publish [id] <port> -- <cmd>", "Run and publish a durable service command"),
+            ("delete, rm [id]", "Delete a computer (typed-name confirm; --force / -y to skip)"),
+        ),
+    ),
+    (
+        "Files",
+        (
+            ("files read [id] <path>", "Read a file to stdout or --output"),
+            ("files write [id] <path>", "Write stdin, --input, or --content to a file"),
+            ("files ls/stat/mkdir/rm", "List, inspect, create, and delete paths"),
+        ),
+    ),
+    (
+        "Sharing",
+        (
+            ("share public [id]", "Make a computer publicly accessible"),
+            ("share private [id]", "Require owner auth before browser access"),
+        ),
+    ),
+    (
+        "Network",
+        (
+            (
+                "network default show/open/none",
+                "Manage the network default for future computers",
+            ),
+            (
+                "network default allowlist <hosts…>",
+                "Allow only listed HTTP/HTTPS hosts by default",
+            ),
+            ("network show [id]", "Show one computer's network policy"),
+            ("network denials [id]", "Show policy-denied hosts since the egress service started"),
+            (
+                "network set <id> <mode> [hosts…]",
+                "Set one computer to open, allowlist, or none",
+            ),
+        ),
+    ),
+    (
+        "Startup & service",
+        (
+            ("service run [id] --port N -- <cmd>", "Run and publish a durable service command"),
+            ("service status [id]", "Show durable service status"),
+            ("service logs [id] --follow", "Stream service logs"),
+            ("service restart [id]", "Restart the durable service"),
+            ("service stop [id]", "Stop service but keep config"),
+            ("service clear [id]", "Clear the durable published app service"),
+        ),
+    ),
+    (
+        "Goals",
+        (
+            ("goal watch [id] --next", "Stream the next email-triggered Codex goal"),
+            ("goal watch [id] --latest", "Stream the latest email-triggered Codex goal"),
+        ),
+    ),
+    (
+        "Proxy",
+        (
+            ("proxy start <id> <ports…>", "Forward local → remote ports (e.g. 5432 or 15432:5432)"),
+            ("proxy ls", "List running proxies"),
+            ("proxy stop [ports…] [--all]", "Stop proxies (by local port or all)"),
+        ),
+    ),
+    (
+        "GitHub",
+        (
+            ("switch, checkout [branch]", "Open a GitHub branch workspace in its own computer"),
+            ("integrate github", "Install the RuntimeVM GitHub App and wait for completion"),
+            ("github list", "List connected GitHub installations"),
+            ("github disconnect, rm [owner|id]", "Disconnect one GitHub installation"),
+        ),
+    ),
+    (
+        "Account",
+        (
+            ("login", "Sign in with WorkOS; use --api-key for headless access"),
+            ("whoami", "Show current account"),
+            ("logout", "Revoke the current credential and remove local config"),
+            ("api-keys list/create/revoke", "Manage WorkOS API keys"),
+            ("secrets list/show/set/import/rm", "Manage account-level secret sets"),
+            ("codex login/status/logout", "Log Codex into Runtime computers"),
+            ("claude login/status/logout", "Log Claude Code into Runtime computers"),
+            ("grok login/status/logout", "Log Grok into Runtime computers"),
+            ("xai login/status/logout", "Log xAI into Runtime computers"),
+        ),
+    ),
+    (
+        "Shell",
+        (
+            ("help [topic]", "Show extended help — topics: computer, share, account, all"),
+            ("completion <bash|zsh|fish>", "Print shell completion script"),
+        ),
+    ),
+)
+
+
+_HELP_EXAMPLES: tuple[str, ...] = (
+    "runtime                         # interactive dashboard",
+    "runtime list                    # open the computer dashboard",
+    "runtime list --json             # stable JSON for scripts and agents",
+    "runtime ls -w                   # live-updating list",
+    "runtime create mybox --command 'npm start' --cwd /app --port 3000",
+    "runtime share private mybox     # require owner auth",
+    "runtime ssh mybox               # SSH through Runtime without exposing VM IPs",
+    "runtime integrate github         # open GitHub and wait for the install to finish",
+    "runtime github list              # show connected GitHub orgs/accounts",
+    "runtime codex login              # open Codex login and save it to Runtime",
+    "runtime claude login             # open Claude login and save it to Runtime",
+    "runtime grok login               # import the local Grok login into Runtime",
+    "runtime xai login                # save an xAI API key to Runtime",
+    "runtime proxy start mybox 5432  # forward localhost:5432 → mybox:5432",
+    "runtime completion zsh > ~/.zsh/completions/_runtime",
+)
+
+
+def _format_top_help() -> str:
+    lines: list[str] = []
+    lines.append("runtime — manage RuntimeVM computers")
+    lines.append("")
+    lines.append("usage: runtime [--base-url URL] [--version] [-h] <command> [args…]")
+    lines.append("")
+    lines.append("Global options:")
+    lines.append("  --base-url URL       Override the Runtime API base URL")
+    lines.append("  --version            Show the CLI version")
+    lines.append("  -h, --help           Show this help")
+    lines.append("")
+    left_width = 0
+    for _, rows in _HELP_SECTIONS:
+        for name, _ in rows:
+            left_width = max(left_width, len(name))
+    left_width = min(left_width, 38)
+    for title, rows in _HELP_SECTIONS:
+        lines.append(f"{title}:")
+        for name, desc in rows:
+            padded = name if len(name) >= left_width else name + " " * (left_width - len(name))
+            lines.append(f"  {padded}  {desc}")
+        lines.append("")
+    lines.append("Examples:")
+    for example in _HELP_EXAMPLES:
+        lines.append(f"  {example}")
+    lines.append("")
+    lines.append("Run `runtime <command> --help` for flags and examples on one command.")
+    lines.append("Run `runtime help <topic>` for long-form docs.")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    _configure_windows_output()
+    raw_argv = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+    args = parser.parse_args(raw_argv)
+
+    try:
+        enter_id: str | None = None
+        enter_command: list[str] | None = None
+        if args.command == "enter":
+            enter_id, enter_command, enter_err = _parse_enter_invocation(raw_argv, args.id, args.enter_command)
+            if enter_err:
+                return cli_output.report_error(enter_err)
+
+        config = load_config()
+        if args.base_url:
+            config.base_url = args.base_url
+        elif os.environ.get("RUNTIME_BASE_URL"):
+            config.base_url = str(os.environ.get("RUNTIME_BASE_URL"))
+        else:
+            config.base_url = config.configured_base_url or DEFAULT_BASE_URL
+
+        # Bare TTY `runtime` owns the single interactive surface. Requiring an
+        # explicit non-TTY command prevents accidental resource creation.
+        if args.command is None:
+            if cli_output.interactive():
+                return _run_tui(config)
+            return cli_output.report_error("command is required; run runtime --help")
+
+        if args.command == "login":
+            return account.handle_login(
+                config, api_key=args.api_key, no_open=args.no_open
+            )
+        if args.command == "whoami":
+            return account.handle_whoami(config)
+        if args.command == "logout":
+            return account.handle_logout(config)
+        if args.command == "api-keys":
+            if args.api_keys_action in ("list", "ls"):
+                return account.handle_api_keys_list(config)
+            if args.api_keys_action == "create":
+                return account.handle_api_keys_create(config, args.name)
+            if args.api_keys_action == "revoke":
+                return account.handle_api_keys_revoke(config, args.id)
+            return cli_output.report_error("unknown api-keys command")
+        if args.command == "secrets":
+            if args.secrets_action in ("list", "ls"):
+                return secret_commands.handle_secrets_list(config)
+            if args.secrets_action == "show":
+                return secret_commands.handle_secrets_show(config, args.slug)
+            if args.secrets_action == "set":
+                return secret_commands.handle_secrets_set(config, args.slug, args.pairs, args.proxy)
+            if args.secrets_action == "import":
+                return secret_commands.handle_secrets_import(config, args.slug, args.env_file, args.proxy)
+            if args.secrets_action in ("delete", "rm"):
+                return secret_commands.handle_secrets_delete(config, args.slug)
+            return cli_output.report_error("unknown secrets command")
+        if args.command == "codex":
+            if args.codex_action == "login":
+                return providers.handle_codex_login(config, device=args.device)
+            if args.codex_action == "status":
+                return providers.handle_codex_status(config)
+            if args.codex_action == "logout":
+                return providers.handle_codex_logout(config)
+            return cli_output.report_error("unknown codex command")
+        if args.command == "claude":
+            if args.claude_action == "login":
+                return providers.handle_claude_login(config)
+            if args.claude_action == "status":
+                return providers.handle_claude_status(config)
+            if args.claude_action == "logout":
+                return providers.handle_claude_logout(config)
+            return cli_output.report_error("unknown claude command")
+        if args.command == "grok":
+            if args.grok_action == "login":
+                return providers.handle_grok_login(config)
+            if args.grok_action == "status":
+                return providers.handle_grok_status(config)
+            if args.grok_action == "logout":
+                return providers.handle_grok_logout(config)
+            return cli_output.report_error("unknown grok command")
+        if args.command == "xai":
+            if args.xai_action == "login":
+                return providers.handle_xai_login(config, api_key=args.api_key)
+            if args.xai_action == "status":
+                return providers.handle_xai_status(config)
+            if args.xai_action == "logout":
+                return providers.handle_xai_logout(config)
+            return cli_output.report_error("unknown xai command")
+        if args.command == "github":
+            if args.github_action in ("list", "ls"):
+                return github_commands.handle_github_list(config)
+            if args.github_action in ("disconnect", "rm"):
+                return github_commands.handle_github_disconnect(config, args.ref)
+            return cli_output.report_error("unknown github command")
+        if args.command == "integrate":
+            return github_commands.handle_integrate_github(config, args.provider, no_open=args.no_open, timeout_seconds=args.timeout)
+        if args.command in ("switch", "checkout"):
+            return github_commands.handle_switch(
+                config,
+                getattr(args, "repo", None),
+                getattr(args, "branch", None),
+                create_branch=getattr(args, "create", False),
+                base_branch=getattr(args, "base_branch", None),
+            )
+        if args.command == "create":
+            return computers.handle_create(
+                config,
+                args.name,
+                getattr(args, "startup_command", None),
+                getattr(args, "cwd", None),
+                getattr(args, "port", None),
+                getattr(args, "network", None),
+                getattr(args, "allow_host", []),
+            )
+        if args.command == "network":
+            return computers.handle_network(config, args)
+        if args.command in ("list", "ls"):
+            return handle_list(
+                config,
+                watch=getattr(args, "watch", None),
+                json_output=getattr(args, "json", False),
+            )
+        if args.command == "info":
+            return computers.handle_info(config, args.id)
+        if args.command == "url":
+            return computers.handle_url(config, args.id)
+        if args.command == "share":
+            return computers.handle_share(config, args.share_action, args.id)
+        if args.command == "start":
+            return computers.handle_start(config, args.id)
+        if args.command == "enter":
+            return computers.handle_enter(config, enter_id, enter_command)
+        if args.command == "ssh":
+            return ssh_commands.handle_ssh(config, args.id, args.ssh_args)
+        if args.command in ("delete", "rm"):
+            return computers.handle_delete(config, args.id, force=getattr(args, "force", False))
+        if args.command == "run":
+            return computers.handle_run(
+                config, args.id, args.run_command, args.uid, args.gid, args.cwd, args.shell
+            )
+        if args.command == "exec":
+            return handle_exec_stream(config, args.id, args.exec_command, args.stdin, args.uid, args.gid, args.cwd, args.shell)
+        if args.command in ("files", "fs", "file"):
+            return file_commands.handle_files(config, args)
+        if args.command == "publish":
+            return computers.handle_publish(config, args.id, args.port, args.publish_command)
+        if args.command == "startup":
+            if args.startup_action == "show":
+                return services.handle_startup_show(config, args.id)
+            if args.startup_action == "set":
+                return services.handle_startup_set(config, args.id, args.startup_value_command, args.cwd, args.port)
+            if args.startup_action == "clear":
+                return services.handle_startup_clear(config, args.id)
+            return cli_output.report_error("unknown startup command")
+        if args.command == "service":
+            if args.service_action == "run":
+                return services.handle_service_run(config, args.id, args.port, args.cwd, args.service_command)
+            if args.service_action in ("show", "status"):
+                return services.handle_service_show(config, args.id)
+            if args.service_action == "logs":
+                return services.handle_service_logs(config, args.id, args.follow)
+            if args.service_action == "restart":
+                return services.handle_service_restart(config, args.id)
+            if args.service_action == "stop":
+                return services.handle_service_stop(config, args.id)
+            if args.service_action == "clear":
+                return services.handle_service_clear(config, args.id)
+            return cli_output.report_error("unknown service command")
+        if args.command == "goal":
+            if args.goal_action == "watch":
+                return goals.handle_goal_watch(config, args.id, latest=args.latest, next_goal=args.next, email_id=args.email_id, timeout=args.timeout)
+            return cli_output.report_error("unknown goal command")
+        if args.command == "proxy":
+            if args.proxy_command == "start":
+                return proxy.handle_proxy_start(config, args.id, args.ports)
+            if args.proxy_command == "ls":
+                return proxy.handle_proxy_ls(config)
+            if args.proxy_command == "stop":
+                return proxy.handle_proxy_stop(config, args.local_ports, stop_all=args.all)
+            return cli_output.report_error("unknown proxy command")
+        if args.command == "help":
+            return handle_help(args.topic)
+        if args.command == "completion":
+            return completion.handle_completion(args.shell)
+        if args.command == "_slugs":
+            return handle_slugs(config)
+        if args.command == "_tui_state":
+            return account.handle_tui_state(config)
+        if args.command == "_proxy_agent":
+            return proxy.run_proxy_agent(
+                config,
+                args.computer_id,
+                args.display_name,
+                args.local_port,
+                args.remote_port,
+            )
+    except RuntimeAPIError as exc:
+        return cli_output.report_error(str(exc), status_code=exc.status_code)
+    except RuntimeConfigError as exc:
+        return cli_output.report_error(str(exc))
+    except KeyboardInterrupt:
+        if cli_output.interactive():
+            print("\ncancelled", file=sys.stderr)
+            return 130
+        return cli_output.report_error("cancelled")
+
+    return cli_output.report_error("unknown command")
+
+
+def _configure_windows_output() -> None:
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8")
+
+
+# --------------------------------------------------------------------------- #
+# Shared helpers                                                              #
+# --------------------------------------------------------------------------- #
+
+
+def _parse_enter_invocation(raw_argv: list[str], parsed_id: str | None, parsed_command: list[str]) -> tuple[str | None, list[str], str | None]:
+    enter_index = raw_argv.index("enter")
+    enter_args = raw_argv[enter_index + 1:]
+    if "--" not in enter_args:
+        if parsed_command:
+            return None, [], "enter command must be separated from the computer id with --"
+        return parsed_id, parsed_command, None
+
+    separator_index = enter_args.index("--")
+    before_separator = enter_args[:separator_index]
+    if len(before_separator) > 1:
+        return None, [], "enter accepts at most one computer id before --"
+    computer_id = before_separator[0] if before_separator else None
+    return computer_id, enter_args[separator_index + 1:], None
+
+
+def _run_tui(config: RuntimeConfig, *, refresh_seconds: int | None = None) -> int:
+    binary = _tui_binary_path()
+    if not binary.is_file():
+        return cli_output.report_error(
+            "Runtime's interactive interface requires a native macOS, Linux, or Windows wheel; "
+            "scriptable subcommands remain available"
+        )
+
+    with tempfile.TemporaryDirectory(prefix="runtime-tui-") as directory:
+        action_path = Path(directory) / "action.json"
+        while True:
+            with contextlib.suppress(FileNotFoundError):
+                action_path.unlink()
+            command = [
+                str(binary),
+                "--runtime-bin",
+                sys.argv[0],
+                "--action-file",
+                str(action_path),
+                "--base-url",
+                config.base_url,
+            ]
+            if refresh_seconds is not None:
+                command.extend(["--refresh-ms", str(refresh_seconds * 1000)])
+            result = subprocess.run(command, check=False)
+            if result.returncode != 0:
+                return result.returncode
+            if not action_path.exists():
+                return 0
+
+            action = _read_tui_action(action_path)
+            code = main(["--base-url", config.base_url, *action])
+            if code != 0:
+                return code
+
+
+def _tui_binary_path() -> Path:
+    default_binary = "runtime-tui.exe" if sys.platform == "win32" else "runtime-tui"
+    return Path(
+        os.environ.get("RUNTIME_TUI_BIN") or Path(__file__).with_name(default_binary)
+    )
+
+
+def _read_tui_action(path: Path) -> list[str]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise RuntimeConfigError(f"invalid Runtime interface action: {exc}") from exc
+    action = payload.get("argv") if isinstance(payload, dict) else None
+    if not isinstance(action, list) or not all(isinstance(value, str) for value in action):
+        raise RuntimeConfigError("invalid Runtime interface action")
+    allowed = (
+        action in (
+            ["codex", "login"],
+            ["claude", "login"],
+            ["grok", "login"],
+            ["xai", "login"],
+            ["integrate", "github"],
+        )
+        or (len(action) == 2 and action[0] == "enter" and bool(action[1].strip()))
+    )
+    if not allowed:
+        raise RuntimeConfigError("unsupported Runtime interface action")
+    return action
+
+
+# --------------------------------------------------------------------------- #
+# Authentication commands                                                    #
+# --------------------------------------------------------------------------- #
+
+def handle_list(
+    config: RuntimeConfig,
+    *,
+    watch: int | None = None,
+    json_output: bool = False,
+) -> int:
+    if watch is not None and watch < 1:
+        return cli_output.report_error("--watch interval must be at least 1 second")
+
+    if cli_output.interactive() and not json_output:
+        return _run_tui(config, refresh_seconds=watch)
+
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+
+    if watch is not None:
+        if not json_output:
+            return cli_output.report_error("--watch requires an interactive terminal or --json")
+        return _watch_list(config, watch)
+
+    client = authenticated_client(config)
+    return cli_output.report_success(client.list_computers())
+
+
+def _watch_list(config: RuntimeConfig, interval: int) -> int:
+    client = authenticated_client(config)
+    print(f"watching every {interval}s; press Ctrl+C to exit", file=sys.stderr)
+    try:
+        while True:
+            cli_output.write_json({"success": True, **client.list_computers()})
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        print("watch stopped", file=sys.stderr)
+        return 0
+
+
+def handle_exec_stream(
+    config: RuntimeConfig,
+    computer_id: str | None,
+    command_parts: list[str] | None,
+    pipe_stdin: bool,
+    uid: int | None,
+    gid: int | None,
+    cwd: str | None,
+    shell: str | None,
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+    if not computer_id:
+        return cli_output.report_error("computer id is required")
+    command = arguments.command_from_remainder(command_parts)
+    if not command:
+        return cli_output.report_error("exec requires -- <command...>")
+    stdin_data = None
+    if pipe_stdin:
+        stdin_buffer = getattr(sys.stdin, "buffer", None)
+        stdin_data = stdin_buffer.read() if stdin_buffer is not None else sys.stdin.read().encode()
+    client = authenticated_client(config)
+    computer_id = computers.resolve_computer_ref(client, computer_id)
+    exit_code = 0
+    for frame in client.stream_command(computer_id, command, stdin=stdin_data, uid=uid, gid=gid, cwd=cwd, shell=shell):
+        stdout = frame.get("stdout") or frame.get("data") or ""
+        stderr = frame.get("stderr") or ""
+        error = frame.get("error") or ""
+        if stdout:
+            print(stdout, end="")
+        if stderr:
+            print(stderr, end="", file=sys.stderr)
+        if error:
+            print(error, file=sys.stderr)
+            exit_code = 1
+        if frame.get("type") == "exit" or frame.get("exit_code") is not None:
+            try:
+                exit_code = int(frame.get("exit_code") or 0)
+            except (TypeError, ValueError):
+                exit_code = 1
+    return exit_code
+
+
+# --------------------------------------------------------------------------- #
+# Help browser + shell completion                                              #
+# --------------------------------------------------------------------------- #
+
+
+_HELP_TOPICS: dict[str, tuple[str, ...]] = {
+    "computer": ("Computers",),
+    "computers": ("Computers",),
+    "ssh": ("Computers",),
+    "share": ("Sharing",),
+    "sharing": ("Sharing",),
+    "network": ("Network",),
+    "service": ("Startup & service",),
+    "goal": ("Goals",),
+    "goals": ("Goals",),
+    "proxy": ("Proxy",),
+    "github": ("GitHub",),
+    "codex": ("Account",),
+    "claude": ("Account",),
+    "xai": ("Account",),
+    "account": ("Account",),
+    "shell": ("Shell",),
+    "all": tuple(title for title, _ in _HELP_SECTIONS),
+}
+
+
+def handle_help(topic: str | None) -> int:
+    if topic is None:
+        sys.stdout.write(_format_top_help())
+        return 0
+    key = topic.strip().lower()
+    if key not in _HELP_TOPICS:
+        matches = computers.close_matches(key, list(_HELP_TOPICS))
+        if matches:
+            return cli_output.report_error(f"unknown help topic {topic!r}. Did you mean {', '.join(repr(m) for m in matches)}?")
+        return cli_output.report_error(f"unknown help topic {topic!r}. Try: {', '.join(sorted(_HELP_TOPICS))}")
+
+    wanted = set(_HELP_TOPICS[key])
+    lines: list[str] = []
+    for title, rows in _HELP_SECTIONS:
+        if title not in wanted:
+            continue
+        lines.append(f"{title}:")
+        left = max((len(name) for name, _ in rows), default=0)
+        for name, desc in rows:
+            padded = name + " " * max(0, left - len(name))
+            lines.append(f"  {padded}  {desc}")
+        lines.append("")
+    sys.stdout.write("\n".join(lines) + "\n")
+    return 0
+
+
+def handle_slugs(config: RuntimeConfig) -> int:
+    """Print one slug per line. Used by shell completion scripts. Silent on errors."""
+    if not has_credentials(config):
+        return 0
+    try:
+        client = authenticated_client(config)
+        payload = client.list_computers()
+    except Exception:
+        return 0
+    computers = payload.get("computers") or []
+    if not isinstance(computers, list):
+        return 0
+    for c in computers:
+        if isinstance(c, dict):
+            slug = str(c.get("slug") or "").strip()
+            if slug:
+                sys.stdout.write(slug + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())