withruntime 0.2.2 → 0.3.1

package/dist/cli.js

@@ -0,0 +1,1291 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveCredential } from "./credentials.js";
+import { authenticationCommand, me, named } from "./login.js";
+import { Runtime } from "./client.js";
+import { RuntimeError } from "./errors.js";
+import { VERSION } from "./transport.js";
+const HELP = `Runtime Cloud CLI ${VERSION}
+
+Usage: runtime <product> <command> [options]      runtime <command> [options]
+
+Start
+  run [--keep] [create options] -- <command>   A fresh sandbox runs one command, then stops
+
+Account
+  login [--agent-name <name>] [--no-browser] [--wait]
+                                               Connect this machine (no key to copy)
+  login --with-key                             Or paste a key from withruntime.com/account/keys
+  logout                                       Revoke this machine's connection
+  whoami                                       The organization and agent you act as
+  usage                                        Balance, trial time and charges
+  limits                                       Whether this key is read-only, and its daily spending limit
+  referrals                                    Your referral link: you both get up to $500
+  ls                                           Everything you run, every product
+  feedback "<text>" [--kind bug|missing_feature|competitor_gap|migration_blocker|docs|pricing|praise|other]
+                   [--detail <text>] [--competitor <name>] [--request-id <req_...>]
+  feedback --list                              What you reported, and what happened to it
+  support "<message>" [--conversation <id>]    Ask Runtime support; read, approve, deny below
+  support read <conversationId>
+  support approve <actionId> <inputHash> --conversation <id>
+  support deny <actionId> --conversation <id>
+  docs [topic]                                 Print a docs page (start, cli, api, python...)
+  mcp                                          Serve MCP on stdio for agents that need it
+
+Products
+  sandbox   Linux microVMs: exec, shell, files, code, previews, network, desktop
+  snapshot  Saved sandboxes, disk and memory, to start or fork from
+  image     Custom images from a Dockerfile, a public image or a package list
+  volume    Persistent disks to attach to sandboxes
+  Each has its own help: \`runtime sandbox help\`, \`runtime image help\`...
+
+Every command takes --json. Keys: RUNTIME_API_KEY, or the connection from \`runtime login\`.
+`;
+const SANDBOX_HELP = `runtime sandbox <command>
+
+  create [--name n] [--label k=v]... [--vcpu 2] [--memory 4096] [--disk 4096]
+         [--timeout <seconds>] [--on-timeout pause|stop] [--trial|--paid] [--no-wait]
+         [--no-internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
+         [--image <imageId> | --snapshot <snapshotId>] [--volume <volumeId>:/data[:snapshot]]...
+                                                              Create one; prints its id
+  ls [--all] [--label k=v]... [--state running]               List (live ones unless --all)
+  get <id>                                                    One sandbox, in full
+  exec <id> [--cwd /workspace] [--env K=V]... [--timeout <s>] -- <command...>
+                                              Run and stream output; exits with its code
+  spawn <id> [--pty] -- <command...>          Start in the background; prints a process id
+  ps <id>                                     Running and recent processes
+  logs <id> <processId> [-f]                  A process's output (follow with -f)
+  kill <id> <processId> [--signal SIGTERM]
+  shell <id> [--command "bash -l"]            An interactive terminal
+  cp <src> <dst>                              Copy files or directories; name a sandbox
+                                              path as <id>:/path, e.g. cp ./app sbx:/workspace/app
+  cat <id> <path>                             Print a file
+  files <id> [path] [--depth 2] [--glob '**/*.py']
+  stop <id> | pause <id> | wake <id> | restart <id>
+  extend <id> <seconds>                       More time before the lease ends
+  snapshot <id> [--name n] [--retention days] Keep its whole machine; prints the snapshot id
+  fork <id> [--count 3] [--name n] [--keep-snapshot]
+                                              Copies of it as it is now, running; prints their ids
+  run-code <id> <file|-> [--lang python|javascript] [--context c] [--out-dir .]
+                                              Run a notebook-style cell; charts saved as PNG
+  preview <id> <port> [--public] [--ttl <s>]  Share a port at an HTTPS address
+  previews <id>                               Every shared port
+  unshare <id> <port>                         Stop sharing a port
+  network <id> [--no-internet|--internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
+                                              Show its network rules, or replace them
+  desktop <id> start | stop | screenshot [file.png] | open <url> | click <x> <y>
+               | type <text> | press <keys> | windows
+
+Examples
+  id=$(runtime sandbox create)
+  runtime sandbox exec $id -- python3 -c 'print(6*7)'
+  runtime sandbox cp ./project $id:/workspace/project
+  runtime sandbox stop $id
+`;
+function parse(argv, booleans = []) {
+    const positional = [];
+    const flags = new Map();
+    let rest;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--") {
+            rest = argv.slice(i + 1);
+            break;
+        }
+        if (arg.startsWith("--") || (arg.startsWith("-") && arg.length === 2 && !/^-\d/.test(arg))) {
+            const [name, inline] = arg.replace(/^-+/, "").split(/=(.*)/s, 2);
+            const value = inline ?? (booleans.includes(name) ? "true" : argv[++i]);
+            if (value === undefined)
+                throw usage(`--${name} needs a value.`);
+            flags.set(name, [...(flags.get(name) ?? []), value]);
+        }
+        else
+            positional.push(arg);
+    }
+    return { positional, flags, rest };
+}
+const flag = (args, name) => args.flags.get(name)?.at(-1);
+const has = (args, name) => args.flags.get(name)?.at(-1) === "true";
+const integer = (args, name) => {
+    const value = flag(args, name);
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value))
+        throw usage(`--${name} must be a whole number.`);
+    return Number(value);
+};
+const pairs = (args, name) => Object.fromEntries((args.flags.get(name) ?? []).map((pair) => {
+    const at = pair.indexOf("=");
+    if (at < 1)
+        throw usage(`--${name} takes KEY=VALUE.`);
+    return [pair.slice(0, at), pair.slice(at + 1)];
+}));
+/** The product being run, so a mistake points at its own help. */
+let product = "";
+function usage(message) {
+    return new RuntimeError({
+        message,
+        code: "usage",
+        status: 0,
+        hint: product ? `Run \`${me} ${product} help\`.` : `Run \`${me} help\`.`,
+    });
+}
+/** "Unknown command X." and, when one is close, the command that was meant. */
+function unknown(what, word, choices) {
+    const distance = (a, b) => {
+        const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+        for (let i = 1; i <= a.length; i++) {
+            let previous = row[0];
+            row[0] = i;
+            for (let j = 1; j <= b.length; j++) {
+                const next = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+                previous = row[j];
+                row[j] = next;
+            }
+        }
+        return row[b.length];
+    };
+    const best = choices
+        .map((choice) => [choice, distance(word, choice)])
+        .sort((x, y) => x[1] - y[1])[0];
+    const meant = best && best[1] <= (word.length >= 4 ? 2 : 1) ? best[0] : undefined;
+    return usage(`Unknown ${what} ${word}.${meant ? ` Did you mean ${meant}?` : ""}`);
+}
+const COMMANDS = [
+    "login",
+    "logout",
+    "whoami",
+    "usage",
+    "limits",
+    "referrals",
+    "ls",
+    "feedback",
+    "support",
+    "docs",
+    "mcp",
+    "sandbox",
+    "snapshot",
+    "image",
+    "volume",
+    "help",
+    "version",
+];
+const SANDBOX_VERBS = [
+    "create",
+    "ls",
+    "get",
+    "stop",
+    "pause",
+    "wake",
+    "restart",
+    "snapshot",
+    "fork",
+    "extend",
+    "exec",
+    "spawn",
+    "ps",
+    "logs",
+    "kill",
+    "shell",
+    "cat",
+    "files",
+    "cp",
+    "run-code",
+    "preview",
+    "previews",
+    "unshare",
+    "network",
+    "desktop",
+];
+function need(value, what) {
+    if (!value)
+        throw usage(`Give ${what}.`);
+    return value;
+}
+/** The client, with the key from RUNTIME_API_KEY or this machine's saved
+ * connection. With neither, the first command connects the machine first (a
+ * browser approval, nothing to copy) and then does what was asked, so setup
+ * is not a separate step. CI, or RUNTIME_NO_LOGIN, answers missing_api_key. */
+/** The approval was asked for and not given yet: say where, and that running
+ * the same command again picks it up. */
+function notApprovedYet(login) {
+    return new RuntimeError({
+        message: `Not connected yet. Open ${login.url}, check the code ${login.userCode} and choose Connect agent.`,
+        code: "connection_pending",
+        status: 0,
+        hint: "Once it is approved, run the same command again: it picks up this approval, with no new link.",
+    });
+}
+async function client(env) {
+    let apiKey;
+    try {
+        apiKey = await resolveCredential(env);
+    }
+    catch (error) {
+        if (!(error instanceof RuntimeError) ||
+            error.code !== "missing_api_key" ||
+            env.CI ||
+            env.RUNTIME_NO_LOGIN)
+            throw error;
+        process.stderr.write("This machine is not connected to Runtime yet. Connecting it first.\n");
+        const login = await authenticationCommand(["login"], env);
+        if (login.pending)
+            throw notApprovedYet(login);
+        apiKey = await resolveCredential(env);
+    }
+    return new Runtime({ apiKey, baseUrl: env.RUNTIME_API_URL, maxRetries: 4 });
+}
+function table(rows) {
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => (row[column] ?? "").length)));
+    return rows
+        .map((row) => row
+        .map((cell, column) => cell.padEnd(widths[column]))
+        .join("  ")
+        .trimEnd())
+        .join("\n");
+}
+function describe(info) {
+    return table([
+        ["id", info.id],
+        ["name", info.name ?? "-"],
+        ["state", info.state],
+        [
+            "shape",
+            `${info.vcpu} vCPU, ${info.memoryMiB} MiB memory, ${info.diskMiB} MiB disk (${info.cpu})`,
+        ],
+        ["funding", info.funding],
+        ["region", info.region],
+        ["expires", info.expiresAt ?? "-"],
+        [
+            "labels",
+            Object.entries(info.labels ?? {})
+                .map(([k, v]) => `${k}=${v}`)
+                .join(", ") || "-",
+        ],
+        ["charged", `$${(info.chargedMicros / 1e6).toFixed(6)}`],
+    ]);
+}
+/** Resolves `<id>:/path` into its parts, or undefined for a local path. */
+function remote(spec) {
+    const match = /^([A-Za-z0-9][A-Za-z0-9_.-]{0,127}):(\/.*)$/.exec(spec);
+    return match ? { id: match[1], path: match[2] } : undefined;
+}
+export async function run(argv, env = process.env, out = defaultOut(argv)) {
+    const [command, ...rest] = argv.filter((arg) => arg !== "--json" || (argv.indexOf("--") !== -1 && argv.indexOf(arg) > argv.indexOf("--")));
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    product = "";
+    if (!command) {
+        const connected = Boolean(env.RUNTIME_API_KEY) ||
+            (await resolveCredential(env).then(() => true, () => false));
+        const start = connected
+            ? "Connected."
+            : "Not connected yet: the first command below connects this machine (a browser approval).";
+        out.write(out.json
+            ? JSON.stringify({ connected, usage: HELP })
+            : `Runtime Cloud ${VERSION}. ${start}
+
+  ${me} run -- python3 -c 'print(6*7)'   A fresh sandbox runs one command, then stops
+  ${me} sandbox create                   A sandbox that stays; prints its id
+  ${me} sandbox exec <id> -- <command>   Run in it
+  ${me} help                             Everything else
+`);
+        return 0;
+    }
+    if (command === "help" || command === "--help" || command === "-h") {
+        out.write(out.json ? JSON.stringify({ usage: named(HELP) }) : named(HELP));
+        return 0;
+    }
+    if (command === "run") {
+        const args = parse(rest, [...CREATE_FLAGS, "keep"]);
+        const commandLine = args.rest ?? args.positional;
+        if (!commandLine.length)
+            throw usage(`Give the command after --: ${me} run -- python3 -c 'print(6*7)'`);
+        const runtime = await client(env);
+        const timeout = integer(args, "timeout");
+        const { timeoutSeconds: _lease, ...input } = createInput(args);
+        const sbx = await runtime.sandboxes.create(input);
+        let cleanup;
+        // SIGINT and normal completion share one stop. Keep an absolute deadline
+        // across the stop retries and final state check, so cleanup cannot hang.
+        const stop = () => (cleanup ??= (async () => {
+            const signal = AbortSignal.timeout(30_000);
+            try {
+                await sbx.stop({ wait: false, signal });
+                if (sbx.state !== "stopped")
+                    await sbx.waitFor("stopped", { timeoutSeconds: 25, signal });
+                if (sbx.state !== "stopped")
+                    throw new Error(`Sandbox is still ${sbx.state}.`);
+                return true;
+            }
+            catch (error) {
+                out.error(describeError(new RuntimeError({
+                    code: "cleanup_failed",
+                    status: 0,
+                    message: `Could not confirm that sandbox ${sbx.id} stopped. ${error instanceof Error ? error.message : String(error)}`,
+                    hint: `Check it and retry cleanup with: ${me} sandbox stop ${sbx.id}`,
+                    cause: error,
+                }), out.json));
+                return false;
+            }
+        })());
+        const interrupted = () => void stop().then(() => process.exit(130));
+        if (!has(args, "keep"))
+            process.once("SIGINT", interrupted);
+        let code = 1;
+        try {
+            code = await execute(sbx, commandLine, args, out, timeout);
+        }
+        finally {
+            try {
+                if (has(args, "keep"))
+                    out.error(`Kept sandbox ${sbx.id}. Run more with: ${me} sandbox exec ${sbx.id} -- <command>`);
+                else if (!(await stop()) && code === 0)
+                    code = 1;
+            }
+            finally {
+                process.off("SIGINT", interrupted);
+            }
+        }
+        return code;
+    }
+    if (command === "--version" || command === "version") {
+        print(VERSION, { version: VERSION });
+        return 0;
+    }
+    if (command === "login" || command === "logout") {
+        const result = await authenticationCommand([command, ...rest], env);
+        print(result.pending
+            ? `Not connected yet. When it is approved, run any command, or \`${me} login --wait\`; it uses this link.`
+            : command === "login"
+                ? `Connected${"agentName" in result && result.agentName ? ` as ${String(result.agentName)}` : ""}.`
+                : "Disconnected.", result);
+        return 0;
+    }
+    if (command === "whoami") {
+        const who = await (await client(env)).me();
+        print(table([
+            ["organization", who.orgId],
+            ["agent", who.principalId],
+            ["key", who.credentialId ?? "-"],
+            ["api", who.apiVersion],
+        ]), who);
+        return 0;
+    }
+    if (command === "usage") {
+        const value = await (await client(env)).usage();
+        print(JSON.stringify(value, null, 2), value);
+        return 0;
+    }
+    if (command === "limits") {
+        const l = await (await client(env)).limits.get();
+        const usd = (micros) => `$${(Number(BigInt(micros) / 10000n) / 100).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+        const access = l.access === "read"
+            ? "read only: reads every product, cannot start, change or spend"
+            : l.access === "full"
+                ? "full: every product"
+                : (l.access ?? "-");
+        print(table([
+            ["access", access],
+            [
+                "daily limit",
+                l.daily.limitMicros === null
+                    ? "none (the prepaid balance is the bound)"
+                    : usd(l.daily.limitMicros),
+            ],
+            ["used, last 24 hours", usd(l.daily.usedMicros)],
+            ...(l.daily.remainingMicros === null ? [] : [["left", usd(l.daily.remainingMicros)]]),
+        ]), l);
+        return 0;
+    }
+    if (command === "referrals") {
+        const r = await (await client(env)).referrals.get();
+        const usd = (micros) => `$${(Number(BigInt(micros) / 10000n) / 100).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+        print([
+            `Your link: ${r.link}`,
+            "",
+            `When a company signs up with it and makes its first top-up of ${usd(r.minPurchaseMicros)} or more,`,
+            `you each get credit equal to that top-up: at least ${usd(r.rewardMicros)}, at most ${usd(r.maxRewardMicros)}`,
+            `(up to ${usd(r.yearlyCapMicros)} a year for you).`,
+            ...(r.enabled ? [] : ["The program is paused: new sign-ups are not counted right now."]),
+            "",
+            table([
+                ["signed up", String(r.signedUp)],
+                ["waiting for a first top-up", String(r.pending)],
+                ["paid", String(r.paid)],
+                ["earned", usd(r.earnedMicros)],
+                [`left this year (${r.year})`, usd(r.capRemainingMicros)],
+            ]),
+        ].join("\n"), r);
+        return 0;
+    }
+    if (command === "mcp") {
+        const { serveMcp } = await import("./mcp.js");
+        await serveMcp(env);
+        return 0;
+    }
+    if (command === "docs") {
+        const topic = rest[0] ?? "index";
+        const response = await fetch(`https://withruntime.com/docs/${topic === "index" ? "start" : encodeURIComponent(topic)}.md`, { redirect: "error" });
+        if (!response.ok)
+            throw usage(`No docs page named ${topic}. Try start, cli, api, javascript, python, mcp.`);
+        out.write(await response.text());
+        return 0;
+    }
+    if (command === "feedback") {
+        const args = parse(rest, ["list"]);
+        if (has(args, "list")) {
+            const { data } = await (await client(env)).feedback.list();
+            print(data.length
+                ? table([
+                    ["ID", "KIND", "STATUS", "SUMMARY"],
+                    ...data.map((f) => [
+                        f.id,
+                        f.kind,
+                        f.sorted === false ? "received, sorting hourly" : f.status,
+                        f.summary,
+                    ]),
+                ])
+                : 'Nothing reported yet. Tell us anything: runtime feedback "..."', data);
+            return 0;
+        }
+        const summary = need(args.positional.join(" ").trim(), 'what to tell us, in quotes: runtime feedback "..."');
+        const kind = (flag(args, "kind") ?? "other");
+        const detail = flag(args, "detail");
+        const result = await (await client(env)).feedback.submit({
+            kind,
+            summary: summary.slice(0, 200),
+            ...(detail || summary.length > 200 ? { detail: detail ?? summary } : {}),
+            ...(flag(args, "competitor") ? { competitor: flag(args, "competitor") } : {}),
+            ...(flag(args, "request-id") ? { requestId: flag(args, "request-id") } : {}),
+        });
+        print(`Thank you, received ${result.id}${result.duplicate ? " (already filed)" : ""}. It is sorted into an item every hour; follow it with \`${me} feedback --list\`.`, result);
+        return 0;
+    }
+    if (command === "support")
+        return support(rest, env, out);
+    if (command === "ls") {
+        const runtime = await client(env);
+        // Every product in one list; a product this account cannot use is left out.
+        const quiet = (work) => work.catch(() => undefined);
+        const [sandboxes, snapshots, images, volumes] = await Promise.all([
+            runtime.sandboxes.list({ limit: 100 }),
+            quiet(runtime.snapshots.list({ limit: 100 })),
+            quiet(runtime.images.list({ limit: 100 })),
+            quiet(runtime.volumes.list({ limit: 100 })),
+        ]);
+        const items = [
+            ...sandboxes.data.map((s) => s.info),
+            ...(snapshots?.data ?? []),
+            ...(images?.data ?? []),
+            ...(volumes?.data ?? []),
+        ];
+        const rows = items.map((item) => [
+            item.id,
+            item.kind,
+            item.name ?? "-",
+            item.state ?? item.status ?? "-",
+            item.createdAt,
+        ]);
+        print(rows.length
+            ? table([["ID", "PRODUCT", "NAME", "STATE", "CREATED"], ...rows])
+            : "Nothing yet. Start with: runtime sandbox create", items);
+        return 0;
+    }
+    if (command === "sandbox" || command === "sandboxes" || command === "sbx") {
+        product = "sandbox";
+        return sandbox(rest, env, out);
+    }
+    if (command === "snapshot" || command === "snapshots") {
+        product = "snapshot";
+        return snapshot(rest, env, out);
+    }
+    if (command === "image" || command === "images") {
+        product = "image";
+        return image(rest, env, out);
+    }
+    if (command === "volume" || command === "volumes") {
+        product = "volume";
+        return volume(rest, env, out);
+    }
+    throw unknown("command", command, COMMANDS);
+}
+async function support(argv, env, out) {
+    const args = parse(argv);
+    const api = (await client(env)).support;
+    const conversationId = flag(args, "conversation");
+    const [first, second, third] = args.positional;
+    let reply;
+    if (first === "read")
+        reply = await api.read(need(second, "the conversation id"));
+    else if (first === "approve")
+        reply = await api.message({
+            approveActionId: need(second, "the action id"),
+            approveInputHash: need(third, "the input hash"),
+            ...(conversationId ? { conversationId } : {}),
+        });
+    else if (first === "deny")
+        reply = await api.message({
+            denyActionId: need(second, "the action id"),
+            ...(conversationId ? { conversationId } : {}),
+        });
+    else
+        reply = await api.message({
+            message: need(args.positional.join(" ").trim(), 'a message: runtime support "..."'),
+            ...(conversationId ? { conversationId } : {}),
+        });
+    const actions = (reply.pendingActions ?? []).map((a) => `  ${a.id}  ${a.summary}\n    approve: runtime support approve ${a.id} ${a.inputHash} --conversation ${reply.conversationId}`);
+    out.write(out.json
+        ? JSON.stringify(reply)
+        : `${reply.reply ?? (reply.status === "working" ? "Support is working on it. Read again in a minute:" : "")}\n${reply.status === "working" ? `  runtime support read ${reply.conversationId}\n` : ""}${actions.length ? `Proposed actions (nothing runs until you approve):\n${actions.join("\n")}\n` : ""}[${reply.status}] conversation ${reply.conversationId}`);
+    return 0;
+}
+async function sandbox(argv, env, out) {
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        out.write(out.json ? JSON.stringify({ usage: named(SANDBOX_HELP) }) : named(SANDBOX_HELP));
+        return 0;
+    }
+    const runtime = await client(env);
+    const get = (id) => runtime.sandboxes.get(need(id, "a sandbox id"));
+    switch (verb) {
+        case "create": {
+            const args = parse(rest, CREATE_FLAGS);
+            const sbx = await runtime.sandboxes.create(createInput(args));
+            print(sbx.id, sbx.info);
+            return 0;
+        }
+        case "ls":
+        case "list": {
+            const args = parse(rest, ["all"]);
+            const page = await runtime.sandboxes.list({
+                ...(has(args, "all") ? { includeStopped: true } : {}),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+                ...(args.flags.has("state")
+                    ? { state: args.flags.get("state") }
+                    : {}),
+            });
+            const all = await page.toArray(1000);
+            // Stopped sandboxes are hidden by default; say so, or an agent that
+            // stopped everything reads "No sandboxes" as "never had any".
+            const hidden = out.json || args.flags.size
+                ? null
+                : await runtime.sandboxes.list({ state: ["stopped"], limit: 50 });
+            const stopped = hidden?.data.length
+                ? `${hidden.data.length}${hidden.hasMore ? "+" : ""} stopped; runtime sandbox ls --all shows them.`
+                : "";
+            const rows = all.map((s) => [
+                s.id,
+                s.info.name ?? "-",
+                s.state,
+                `${s.info.vcpu}/${s.info.memoryMiB}`,
+                s.info.funding,
+                s.info.expiresAt ?? "-",
+            ]);
+            print([
+                rows.length
+                    ? table([["ID", "NAME", "STATE", "CPU/MIB", "FUNDING", "EXPIRES"], ...rows])
+                    : stopped
+                        ? "No live sandboxes."
+                        : "No sandboxes. Create one: runtime sandbox create",
+                stopped,
+            ]
+                .filter(Boolean)
+                .join("\n"), all.map((s) => s.info));
+            return 0;
+        }
+        case "get": {
+            const sbx = await get(rest[0]);
+            print(describe(sbx.info), sbx.info);
+            return 0;
+        }
+        case "stop":
+        case "pause":
+        case "wake":
+        case "restart": {
+            const sbx = await get(rest[0]);
+            await sbx[verb]();
+            print(`${sbx.id} ${sbx.state}`, sbx.info);
+            return 0;
+        }
+        case "snapshot": {
+            const args = parse(rest);
+            const sbx = await get(args.positional[0]);
+            const snapshot = await sbx.snapshot({
+                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+                ...(integer(args, "retention") ? { retentionDays: integer(args, "retention") } : {}),
+            });
+            print(snapshot.id, snapshot);
+            return 0;
+        }
+        case "fork": {
+            const args = parse(rest, ["keep-snapshot"]);
+            const sbx = await get(args.positional[0]);
+            const forks = await sbx.fork({
+                count: integer(args, "count") ?? 1,
+                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+                ...(has(args, "keep-snapshot") ? { keepSnapshot: true } : {}),
+            });
+            print(forks.map((f) => f.id).join("\n"), forks.map((f) => f.info));
+            return 0;
+        }
+        case "extend": {
+            const sbx = await get(rest[0]);
+            const seconds = Number(need(rest[1], "seconds, e.g. runtime sandbox extend <id> 600"));
+            await sbx.extend(seconds);
+            print(`${sbx.id} now ends at ${sbx.info.expiresAt}`, sbx.info);
+            return 0;
+        }
+        case "exec": {
+            const args = parse(rest);
+            const command = args.rest ?? args.positional.slice(1);
+            if (!command.length)
+                throw usage("Give the command after --: runtime sandbox exec <id> -- ls -la");
+            const sbx = await get(args.positional[0]);
+            return execute(sbx, command, args, out, integer(args, "timeout"));
+        }
+        case "spawn": {
+            const args = parse(rest, ["pty"]);
+            const command = args.rest ?? [];
+            if (!command.length)
+                throw usage("Give the command after --: runtime sandbox spawn <id> -- npm run dev");
+            const sbx = await get(args.positional[0]);
+            const proc = await sbx.spawn(command.length === 1 ? command[0] : command, {
+                ...(has(args, "pty") ? { pty: { cols: 120, rows: 40 } } : {}),
+                ...(flag(args, "cwd") ? { cwd: flag(args, "cwd") } : {}),
+                ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
+            });
+            print(proc.id, proc.info);
+            return 0;
+        }
+        case "ps": {
+            const sbx = await get(rest[0]);
+            const list = await sbx.processes.list();
+            print(list.length
+                ? table([
+                    ["PROCESS", "STATE", "EXIT", "COMMAND"],
+                    ...list.map((p) => [p.id, p.state, String(p.exitCode ?? "-"), p.command]),
+                ])
+                : "No processes.", list);
+            return 0;
+        }
+        case "logs": {
+            const args = parse(rest, ["f", "follow"]);
+            const sbx = await get(args.positional[0]);
+            const proc = await sbx.processes.get(need(args.positional[1], "a process id"));
+            if (has(args, "f") || has(args, "follow") || !out.json) {
+                for await (const event of proc.output())
+                    if (event.type === "stdout")
+                        process.stdout.write(event.data);
+                    else if (event.type === "stderr")
+                        process.stderr.write(event.data);
+                    else if (out.json)
+                        out.write(JSON.stringify(event));
+                return 0;
+            }
+            out.write(JSON.stringify(await proc.wait()));
+            return 0;
+        }
+        case "kill": {
+            const args = parse(rest);
+            const sbx = await get(args.positional[0]);
+            const proc = await sbx.processes.get(need(args.positional[1], "a process id"));
+            await proc.kill((flag(args, "signal") ?? "SIGTERM"));
+            print(`Signalled ${proc.id}.`, { processId: proc.id });
+            return 0;
+        }
+        case "shell": {
+            const args = parse(rest);
+            const sbx = await get(args.positional[0]);
+            return shell(sbx, flag(args, "command"));
+        }
+        case "cat": {
+            const sbx = await get(rest[0]);
+            process.stdout.write(await sbx.files.read(need(rest[1], "a path")));
+            return 0;
+        }
+        case "files": {
+            const args = parse(rest);
+            const sbx = await get(args.positional[0]);
+            const entries = await sbx.files.list(args.positional[1] ?? "/workspace", {
+                ...(integer(args, "depth") ? { depth: integer(args, "depth") } : {}),
+                ...(flag(args, "glob") ? { glob: flag(args, "glob") } : {}),
+            });
+            print(entries
+                .map((e) => `${e.type === "directory" ? "d" : "-"} ${String(e.size).padStart(10)}  ${e.path}`)
+                .join("\n") || "(empty)", entries);
+            return 0;
+        }
+        case "cp": {
+            const [from, to] = parse(rest).positional;
+            const source = remote(need(from, "a source"));
+            const target = remote(need(to, "a destination"));
+            if (source && !target)
+                await (await get(source.id)).files.download(source.path, to);
+            else if (!source && target)
+                await (await get(target.id)).files.upload(from, target.path);
+            else
+                throw usage("Name exactly one side as <sandbox-id>:/path.");
+            print(`Copied ${from} to ${to}.`, { from, to });
+            return 0;
+        }
+        case "run-code":
+            return runCode(await get(rest[0]), rest.slice(1), out);
+        case "preview": {
+            const args = parse(rest, ["public"]);
+            const sbx = await get(args.positional[0]);
+            const port = Number(need(args.positional[1], "a port, e.g. runtime sandbox preview <id> 3000"));
+            const preview = await sbx.previews.create(port, {
+                ...(has(args, "public") ? { visibility: "public" } : {}),
+                ...(integer(args, "ttl") ? { ttlSeconds: integer(args, "ttl") } : {}),
+            });
+            print((preview.visibility === "public"
+                ? preview.url
+                : `${preview.urlWithToken ?? preview.url}\nPrivate: send the header x-runtime-preview-token: ${preview.token} (expires ${preview.tokenExpiresAt}).`) +
+                (preview.hint ? `\n${preview.hint}` : ""), preview);
+            return 0;
+        }
+        case "previews": {
+            const list = await (await get(rest[0])).previews.list();
+            print(list.length
+                ? table([
+                    ["PORT", "VISIBILITY", "URL"],
+                    ...list.map((p) => [String(p.port), p.visibility, p.url]),
+                ])
+                : "No shared ports. Share one: runtime sandbox preview <id> 3000", list);
+            return 0;
+        }
+        case "unshare": {
+            const sbx = await get(rest[0]);
+            const port = Number(need(rest[1], "the port"));
+            print(`Port ${port} is no longer shared.`, await sbx.previews.delete(port));
+            return 0;
+        }
+        case "network": {
+            const args = parse(rest, ["no-internet", "internet"]);
+            const sbx = await get(args.positional[0]);
+            const rules = ["allow", "deny", "connect"].filter((name) => args.flags.has(name));
+            const policy = has(args, "no-internet") || has(args, "internet") || rules.length
+                ? await sbx.network.set({
+                    internet: !has(args, "no-internet"),
+                    ...Object.fromEntries(rules.map((name) => [name, args.flags.get(name)])),
+                })
+                : await sbx.network.get();
+            print(table([
+                ["internet", policy.internet ? "on" : "off"],
+                ["allow", policy.allow.join(", ") || "(the public web)"],
+                ["deny", policy.deny.join(", ") || "-"],
+                ["connect", policy.connect.join(", ") || "-"],
+                ["enforced", policy.enforced ? "yes" : "not yet; run the same command again"],
+            ]), policy);
+            return 0;
+        }
+        case "desktop":
+            return desktop(await get(rest[0]), rest.slice(1), out);
+    }
+    throw unknown("sandbox command", verb, SANDBOX_VERBS);
+}
+/** `<volumeId>:/path[:snapshot]`, as the create body wants it. */
+function attachment(spec) {
+    const [volumeId, path, mode = "rw"] = spec.split(":");
+    if (!volumeId || !path?.startsWith("/") || (mode !== "rw" && mode !== "snapshot"))
+        throw usage("--volume takes <volumeId>:/path, or <volumeId>:/path:snapshot for a copy.");
+    return { volumeId, path, mode };
+}
+async function readInput(source) {
+    if (source !== "-")
+        return readFile(source, "utf8");
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function runCode(sbx, argv, out) {
+    const args = parse(argv);
+    const source = need(args.positional[0], "a file, or - to read the code from standard input");
+    const code = await readInput(source);
+    const language = (flag(args, "lang") ??
+        (/\.(m?js|ts)$/.test(source) ? "javascript" : "python"));
+    const timeout = integer(args, "timeout");
+    const execution = await sbx.interpreter.run(code, {
+        language,
+        ...(flag(args, "context") ? { context: flag(args, "context") } : {}),
+        ...(timeout ? { timeoutMs: timeout * 1000 } : {}),
+        ...(out.json
+            ? {}
+            : {
+                onStdout: (text) => process.stdout.write(text),
+                onStderr: (text) => process.stderr.write(text),
+            }),
+    });
+    const saved = [];
+    const outDir = flag(args, "out-dir") ?? ".";
+    for (const [index, result] of execution.results.entries()) {
+        const inline = result.data["image/png"];
+        const ref = result.refs["image/png"];
+        if (typeof inline !== "string" && !ref)
+            continue;
+        const bytes = typeof inline === "string"
+            ? Buffer.from(inline, "base64")
+            : await sbx.interpreter.result(ref);
+        const file = join(outDir, `result-${execution.executionCount ?? 0}-${index + 1}.png`);
+        await writeFile(file, bytes);
+        saved.push(file);
+    }
+    if (out.json)
+        out.write(JSON.stringify({ ...execution, saved }));
+    else {
+        for (const result of execution.results) {
+            const text = result.data["text/plain"];
+            if (typeof text === "string" && !result.data["image/png"])
+                out.write(text);
+        }
+        for (const file of saved)
+            out.write(`Saved ${file}`);
+        if (execution.error)
+            out.error(execution.error.traceback || `${execution.error.name}: ${execution.error.value}`);
+        if (execution.status === "timeout")
+            out.error("runtime: the cell timed out.");
+    }
+    return execution.status === "timeout" ? 124 : execution.error ? 1 : 0;
+}
+async function desktop(sbx, argv, out) {
+    const [action, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    const d = sbx.desktop;
+    switch (action) {
+        case "start": {
+            const args = parse(rest);
+            const started = await d.start({
+                ...(integer(args, "width") ? { width: integer(args, "width") } : {}),
+                ...(integer(args, "height") ? { height: integer(args, "height") } : {}),
+            });
+            print(`Desktop ${started.size} on ${started.display}. Watch it: ${started.streamUrl}`, started);
+            return 0;
+        }
+        case "stop":
+            print("Desktop stopped.", await d.stop());
+            return 0;
+        case "screenshot": {
+            const file = rest[0] ?? "screenshot.png";
+            await writeFile(file, await d.screenshot());
+            print(`Saved ${file}`, { file });
+            return 0;
+        }
+        case "open":
+            print("Opened.", await d.open(need(rest[0], "a URL")));
+            return 0;
+        case "click":
+            print("Clicked.", await d.click(Number(need(rest[0], "x")), Number(need(rest[1], "y"))));
+            return 0;
+        case "type":
+            print("Typed.", await d.type(need(rest.join(" "), "the text")));
+            return 0;
+        case "press":
+            print("Pressed.", await d.press(need(rest[0], "keys, e.g. ctrl+l")));
+            return 0;
+        case "windows": {
+            const windows = await d.windows();
+            print(windows.length
+                ? table([["WINDOW", "TITLE"], ...windows.map((w) => [w.id, w.title])])
+                : "No windows.", windows);
+            return 0;
+        }
+    }
+    throw usage(`${me} sandbox desktop <id> start|stop|screenshot|open|click|type|press|windows`);
+}
+const SNAPSHOT_HELP = `runtime snapshot <command>
+
+  ls [--sandbox <id>] [--name n]              Your snapshots
+  get <id>                                    One snapshot
+  extend <id> <days>                          Keep it longer
+  rm <id>                                     Delete it
+  Take one with \`runtime sandbox snapshot <sandboxId>\`; start from one with
+  \`runtime sandbox fork\` or the SDK's fork().
+`;
+async function snapshot(argv, env, out) {
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(SNAPSHOT_HELP), { usage: named(SNAPSHOT_HELP) });
+        return 0;
+    }
+    const api = (await client(env)).snapshots;
+    switch (verb) {
+        case "ls":
+        case "list": {
+            const args = parse(rest);
+            const all = await (await api.list({
+                ...(flag(args, "sandbox") ? { sandboxId: flag(args, "sandbox") } : {}),
+                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+            })).toArray(1000);
+            print(all.length
+                ? table([
+                    ["ID", "NAME", "STATUS", "FROM", "EXPIRES"],
+                    ...all.map((s) => [s.id, s.name ?? "-", s.status, s.sourceSandboxId, s.expiresAt]),
+                ])
+                : "No snapshots. Take one: runtime sandbox snapshot <sandboxId>", all);
+            return 0;
+        }
+        case "get": {
+            const found = await api.get(need(rest[0], "a snapshot id"));
+            print(JSON.stringify(found, null, 2), found);
+            return 0;
+        }
+        case "extend": {
+            const days = integer(parse(rest.slice(1)), "days") ?? Number(need(rest[1], "days"));
+            const found = await api.extend(need(rest[0], "a snapshot id"), days);
+            print(`${found.id} kept until ${found.expiresAt}`, found);
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            const id = need(rest[0], "a snapshot id");
+            await api.delete(id);
+            print(`Deleted ${id}.`, { id, deleted: true });
+            return 0;
+        }
+    }
+    throw unknown("snapshot command", verb, ["ls", "get", "extend", "rm"]);
+}
+const IMAGE_HELP = `runtime image <command>
+
+  build (--dockerfile <path> | --from <public image> | --pip <pkg>... --apt <pkg>... --npm <pkg>...)
+        [--name n] [--max-image-mib 4096] [--timeout <seconds>]
+                        Build and stream the log; prints the image id when ready.
+                        A Dockerfile's COPY and ADD sources are sent from its folder
+                        (at most 256 files, 1 MiB in all).
+  ls                    Your images
+  get <id>              One image
+  logs <id>             Its build log
+  rm <id>               Delete it
+  Use one: runtime sandbox create --image <id>
+`;
+async function image(argv, env, out) {
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(IMAGE_HELP), { usage: named(IMAGE_HELP) });
+        return 0;
+    }
+    const api = (await client(env)).images;
+    switch (verb) {
+        case "build": {
+            const args = parse(rest);
+            const list = (name) => (args.flags.get(name) ?? []).flatMap((value) => value.split(/[\s,]+/)).filter(Boolean);
+            const recipe = { apt: list("apt"), pip: list("pip"), npm: list("npm") };
+            const hasRecipe = recipe.apt.length + recipe.pip.length + recipe.npm.length > 0;
+            const sources = [flag(args, "dockerfile"), flag(args, "from"), hasRecipe || undefined];
+            if (sources.filter((s) => s !== undefined).length !== 1)
+                throw usage("Give exactly one of --dockerfile <path>, --from <image>, or --pip/--apt/--npm.");
+            const build = {
+                ...(integer(args, "max-image-mib") ? { maxImageMiB: integer(args, "max-image-mib") } : {}),
+                ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
+            };
+            const common = {
+                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+                ...(Object.keys(build).length ? { build } : {}),
+            };
+            const dockerfile = flag(args, "dockerfile");
+            const input = dockerfile
+                ? { ...common, ...(await dockerContext(dockerfile)) }
+                : flag(args, "from")
+                    ? { ...common, image: flag(args, "from") }
+                    : {
+                        ...common,
+                        recipe: Object.fromEntries(Object.entries(recipe).filter(([, v]) => v.length)),
+                    };
+            const built = await api.build(input, {
+                ...(out.json ? {} : { onLog: (line) => out.error(line.text) }),
+            });
+            print(built.id, built);
+            return 0;
+        }
+        case "ls":
+        case "list": {
+            const all = await (await api.list()).toArray(1000);
+            print(all.length
+                ? table([
+                    ["ID", "NAME", "STATE", "MIB", "CREATED"],
+                    ...all.map((i) => [
+                        i.id,
+                        i.name ?? "-",
+                        i.state,
+                        String(i.sizeMiB ?? "-"),
+                        i.createdAt,
+                    ]),
+                ])
+                : "No images. Build one: runtime image build --pip pandas", all);
+            return 0;
+        }
+        case "get": {
+            const found = await api.get(need(rest[0], "an image id"));
+            print(JSON.stringify(found, null, 2), found);
+            return 0;
+        }
+        case "logs": {
+            const id = need(rest[0], "an image id");
+            let after = 0;
+            const lines = [];
+            for (;;) {
+                const page = await api.logs(id, after);
+                lines.push(...page.lines.map((line) => line.text));
+                if (!page.lines.length || page.nextAfter === after)
+                    break;
+                after = page.nextAfter;
+            }
+            print(lines.join("\n") || "(no log yet)", lines);
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            const found = await api.delete(need(rest[0], "an image id"));
+            print(`${found.id} ${found.state}`, found);
+            return 0;
+        }
+    }
+    throw unknown("image command", verb, ["build", "ls", "get", "logs", "rm"]);
+}
+/** The Dockerfile and the files its COPY and ADD lines name, from its folder. */
+async function dockerContext(path) {
+    const dockerfile = await readFile(path, "utf8");
+    const root = dirname(resolve(path));
+    const sources = new Set();
+    for (const line of dockerfile.replace(/\\\r?\n/g, " ").split(/\r?\n/)) {
+        const match = /^\s*(?:COPY|ADD)\s+(.+)$/i.exec(line);
+        if (!match || /--from=/i.test(match[1]))
+            continue;
+        const body = match[1].trim();
+        const words = body.startsWith("[")
+            ? JSON.parse(body)
+            : body.split(/\s+/).filter((word) => !word.startsWith("--"));
+        for (const word of words.slice(0, -1))
+            if (!/^https?:\/\//.test(word))
+                sources.add(word);
+    }
+    const files = [];
+    let total = 0;
+    const add = async (absolute) => {
+        const info = await stat(absolute);
+        if (info.isDirectory()) {
+            for (const entry of await readdir(absolute))
+                if (entry !== ".git")
+                    await add(join(absolute, entry));
+            return;
+        }
+        const name = relative(root, absolute).split(sep).join("/");
+        if (files.some((file) => file.path === name))
+            return;
+        const bytes = await readFile(absolute);
+        total += bytes.length;
+        if (files.length >= 256 || total > 1024 * 1024)
+            throw usage("The Dockerfile's context is over 256 files or 1 MiB. Build from --from, or install packages with --pip/--apt/--npm.");
+        files.push({
+            path: name,
+            content: bytes.toString("base64"),
+            encoding: "base64",
+            mode: info.mode & 0o777,
+        });
+    };
+    for (const source of sources) {
+        const absolute = resolve(root, source);
+        if (absolute !== root && !absolute.startsWith(root + sep))
+            throw usage(`COPY ${source} is outside the Dockerfile's folder.`);
+        if (/[*?[]/.test(source)) {
+            const pattern = new RegExp(`^${source
+                .split("/")
+                .at(-1)
+                .replace(/[.+^${}()|\\]/g, "\\$&")
+                .replace(/\*/g, "[^/]*")
+                .replace(/\?/g, "[^/]")}$`);
+            const folder = dirname(absolute);
+            for (const entry of await readdir(folder))
+                if (pattern.test(entry))
+                    await add(join(folder, entry));
+        }
+        else
+            await add(absolute);
+    }
+    return { dockerfile, files };
+}
+const VOLUME_HELP = `runtime volume <command>
+
+  create --size-mib <N> [--name n]            A persistent ext4 disk; prints its id
+  ls                                          Your volumes
+  get <id>                                    One volume and where it is attached
+  rm <id>                                     Delete it and everything on it
+  Attach one: runtime sandbox create --volume <id>:/data
+  A volume lives on one server and is not backed up off it.
+`;
+async function volume(argv, env, out) {
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(VOLUME_HELP), { usage: named(VOLUME_HELP) });
+        return 0;
+    }
+    const api = (await client(env)).volumes;
+    switch (verb) {
+        case "create": {
+            const args = parse(rest);
+            const created = await api.create({
+                sizeMiB: integer(args, "size-mib") ?? Number(need(undefined, "--size-mib <N>")),
+                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+            });
+            if (!out.json)
+                out.error("Not backed up off its server.");
+            print(created.id, created);
+            return 0;
+        }
+        case "ls":
+        case "list": {
+            const all = await (await api.list()).toArray(1000);
+            print(all.length
+                ? table([
+                    ["ID", "NAME", "STATE", "MIB", "ATTACHED"],
+                    ...all.map((v) => [
+                        v.id,
+                        v.name ?? "-",
+                        v.state,
+                        String(v.sizeMiB),
+                        v.attachments.map((a) => `${a.sandboxId}:${a.path}`).join(", ") || "-",
+                    ]),
+                ])
+                : "No volumes. Create one: runtime volume create --size-mib 10240", all);
+            return 0;
+        }
+        case "get": {
+            const found = await api.get(need(rest[0], "a volume id"));
+            print(JSON.stringify(found, null, 2), found);
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            const found = await api.delete(need(rest[0], "a volume id"));
+            print(`${found.id} ${found.state}`, found);
+            return 0;
+        }
+    }
+    throw unknown("volume command", verb, ["create", "ls", "get", "rm"]);
+}
+/** Flags `sandbox create` and `run` take without a value. */
+const CREATE_FLAGS = ["trial", "paid", "no-wait", "no-internet"];
+/** A create body from the command line's flags. */
+function createInput(args) {
+    const rules = ["allow", "deny", "connect"].filter((name) => args.flags.has(name));
+    return {
+        ...(flag(args, "image") ? { image: flag(args, "image") } : {}),
+        ...(flag(args, "snapshot") ? { snapshot: flag(args, "snapshot") } : {}),
+        ...(args.flags.has("volume") ? { volumes: args.flags.get("volume").map(attachment) } : {}),
+        ...(has(args, "no-internet") || rules.length
+            ? {
+                network: {
+                    internet: !has(args, "no-internet"),
+                    ...Object.fromEntries(rules.map((name) => [name, args.flags.get(name)])),
+                },
+            }
+            : {}),
+        ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+        ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+        ...(integer(args, "vcpu") ? { vcpu: integer(args, "vcpu") } : {}),
+        ...(integer(args, "memory") ? { memoryMiB: integer(args, "memory") } : {}),
+        ...(integer(args, "disk") ? { diskMiB: integer(args, "disk") } : {}),
+        ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
+        ...(flag(args, "on-timeout")
+            ? { onLeaseEnd: flag(args, "on-timeout") }
+            : {}),
+        ...(has(args, "trial")
+            ? { funding: "trial" }
+            : has(args, "paid")
+                ? { funding: "paid" }
+                : {}),
+        ...(has(args, "no-wait") ? { wait: false } : {}),
+    };
+}
+/** Runs a command in a sandbox, streaming its output, and answers its exit code
+ * (124 on a timeout), so a script's `set -e` behaves. */
+async function execute(sbx, command, args, out, timeout) {
+    const target = command.length === 1 ? command[0] : command;
+    const options = {
+        ...(flag(args, "cwd") ? { cwd: flag(args, "cwd") } : {}),
+        ...(args.flags.has("env") ? { env: pairs(args, "env") } : {}),
+        ...(timeout ? { timeoutMs: timeout * 1000 } : {}),
+    };
+    const result = out.json
+        ? await sbx.exec(target, options)
+        : await sbx.exec(target, {
+            ...options,
+            onStdout: (t) => process.stdout.write(t),
+            onStderr: (t) => process.stderr.write(t),
+        });
+    if (out.json)
+        out.write(JSON.stringify(result));
+    else if (result.timedOut)
+        out.error(`runtime: timed out after ${timeout ?? 60} s; the command's process group was killed.`);
+    return result.timedOut ? 124 : Math.min(255, Math.max(0, result.exitCode ?? 1));
+}
+async function shell(sbx, command) {
+    const stdin = process.stdin;
+    const size = () => ({ cols: process.stdout.columns || 80, rows: process.stdout.rows || 24 });
+    const terminal = await sbx.terminal({
+        ...size(),
+        ...(command ? { command } : {}),
+        onData: (data) => process.stdout.write(data),
+    });
+    if (stdin.isTTY)
+        stdin.setRawMode(true);
+    stdin.resume();
+    const onInput = (chunk) => terminal.write(new Uint8Array(chunk));
+    const onResize = () => terminal.resize(size().cols, size().rows);
+    stdin.on("data", onInput);
+    process.stdout.on("resize", onResize);
+    const code = await terminal.exited;
+    stdin.off("data", onInput);
+    process.stdout.off("resize", onResize);
+    if (stdin.isTTY)
+        stdin.setRawMode(false);
+    stdin.pause();
+    return code ?? 0;
+}
+function defaultOut(argv) {
+    const json = argv.includes("--json") &&
+        (argv.indexOf("--") === -1 || argv.indexOf("--json") < argv.indexOf("--"));
+    return {
+        json,
+        write: (text) => process.stdout.write(text.endsWith("\n") ? text : `${text}\n`),
+        error: (text) => process.stderr.write(`${text}\n`),
+    };
+}
+export function describeError(error, json) {
+    if (error instanceof RuntimeError) {
+        if (json)
+            return JSON.stringify({
+                error: {
+                    code: error.code,
+                    status: error.status,
+                    message: error.message,
+                    hint: error.hint,
+                    requestId: error.requestId,
+                    idempotencyKey: error.idempotencyKey,
+                    details: error.details,
+                },
+            });
+        return `Error [${error.code}]: ${error.message}${error.hint ? `\nHint: ${error.hint}` : ""}${error.requestId ? `\nRequest: ${error.requestId} (report it: runtime feedback "..." --request-id ${error.requestId})` : ""}`;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return json ? JSON.stringify({ error: { code: "cli_error", message } }) : `Error: ${message}`;
+}
+if (import.meta.main ||
+    (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))) {
+    const argv = process.argv.slice(2);
+    const out = defaultOut(argv);
+    run(argv, process.env, out).then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        out.error(describeError(error, out.json));
+        process.exitCode = 1;
+    });
+}