withruntime 0.6.0 → 0.7.0

package/dist/cli.js

@@ -3,15 +3,14 @@ import { realpathSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { connectionStore, resolveCredential } from "./credentials.js";
-import { authenticationCommand, me, named } from "./login.js";
-import { createKey, dailyLimitMicros } from "./keys.js";
+import { connectionOrigins, connectionStore, resolveCredential } from "./credentials.js";
+import { me, named } from "./cli-name.js";
 import { Runtime } from "./client.js";
+import { Sandbox as SandboxHandle } from "./sandbox.js";
 import { RuntimeError } from "./errors.js";
 import { NETWORK_PRODUCTS, networkProductCommand } from "./network-cli.js";
+import { billingCommand } from "./billing-cli.js";
 import { envFetch } from "./proxy.js";
-import { identityToken } from "./identity.js";
-import { portForwardCommand, resolveSandbox, sshCommand } from "./ssh.js";
 import { VERSION } from "./transport.js";
 const HELP = `Runtime Cloud CLI ${VERSION}
 
@@ -30,22 +29,25 @@ Account
   account [ls]                                 The accounts this machine is connected to
   account switch <name|id>                     Use another of them for every command after
   account add                                  Connect another account (choose it in the browser)
+  account close --confirm "<account name>"     Close the account for good (owner, key for every product)
   audit [--action member.] [--limit 50] [--before <next>]
                                                The account's audit log (owner or admin keys)
   sso                                          Single sign-on and SCIM directory sync (owner or
                                                admin keys); an owner changes it on the website
-  usage                                        Balance, trial time and charges
+  usage [--csv]                                Balance, trial time and charges; --csv, each resource
   limits                                       Whether this key is read-only, and its daily spending limit
   secrets set <NAME> --host <host>... [--header <name> [--format '<text {value}>']]
-                                               Store a secret sandboxes use without seeing it; the
-                                               value is read from standard input, never an argument
+            [--allow '[GET,HEAD] /path/*']...  Store a secret sandboxes use without seeing it; the
+                                               value is read from standard input, never an argument.
+                                               --allow (paid): only these methods and paths get it
   secrets ls                                   Names, hosts and placeholders, never values
   secrets rm <NAME>                            Delete a secret
   keys create [--name <name>] [--read-only] [--daily-limit <usd>]
                                                A new API key for CI, approved by an owner in the browser
   referrals                                    Your referral link: you both get up to $500
   compare --from <provider> [--days 30]        What your usage would cost at e2b, daytona, vercel,
-                                               modal, cloudflare, fly and others, and what you save
+                                               modal, cloudflare, fly, lambda-microvms, freestyle,
+                                               prime and others, and what you save
   switch [--from <provider>]                   Moving from a rival: record it before your first top-up,
                                                and that top-up is matched, up to $100
   ls                                           Everything you run, every product
@@ -84,6 +86,7 @@ Products
   port      A public TCP port to a sandbox: databases, game servers
   address   A dedicated outbound address, for allow-lists
   tunnel    A WireGuard tunnel from your own network into your sandboxes
+  network   Account-wide network settings: send outbound traffic through your own proxy
   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\`.
@@ -97,6 +100,7 @@ const SANDBOX_HELP = `runtime sandbox <command>
   ssh <id|name> [-- <command...>] | ssh config [--install]    Log in over SSH, also from VS Code and JetBrains
   port-forward <id|name> <port|local:remote>...               Forward local ports to ports in it
   create [--name n] [--label k=v]... [--vcpu 2] [--memory 4096] [--disk 4096]
+         [--cpu shared|reserved] [--cpu-floor <thousandths>] [--max-cost <usd>] [--max-total-cost <usd>]
          [--timeout <seconds>] [--on-timeout pause|stop] [--trial|--paid] [--no-wait]
          [--no-internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
          [--image <name:tag|imageId> | --snapshot <snapshotId>] [--volume <volumeId>:/data[:snapshot]]...
@@ -137,6 +141,8 @@ const SANDBOX_HELP = `runtime sandbox <command>
                                               Start them; prints each URL and the header to send
   mcp <id> [status] | mcp <id> stop           Their state and fresh URLs; stop them
   preview <id> <port> [--public] [--ttl <s>]  Share a port at an HTTPS address
+  preview rotate <id> <port>                  Refuse every token given out for a private port so
+                                              far; prints the new token
   previews <id>                               Every shared port
   unshare <id> <port>                         Stop sharing a port
   network <id> [--no-internet|--internet] [--allow <host>]... [--deny <host>]... [--connect <host:port>]...
@@ -157,9 +163,38 @@ Examples
   runtime sandbox cp ./project $id:/workspace/project
   runtime sandbox stop $id
 `;
-function parse(argv, booleans = []) {
+/** A command's options. Reading one its parse() did not declare is a bug in
+ * this file, and says so, so a test that runs the command finds it. */
+class Flags extends Map {
+    known;
+    constructor(known) {
+        super();
+        this.known = known;
+    }
+    get(name) {
+        this.#declared(name);
+        return super.get(name);
+    }
+    has(name) {
+        this.#declared(name);
+        return super.has(name);
+    }
+    #declared(name) {
+        if (!this.known.has(name))
+            throw new Error(`The CLI reads --${name}, which this command's parse() does not declare.`);
+    }
+}
+/** A command's arguments: `booleans` are options that take no value, `values`
+ * those that take one. Any other option is refused before anything is sent, so
+ * `--memory-mib 8192` for `--memory` is a usage error with the right name, not a
+ * sandbox created at the default size. Everything after `--` is `rest`. */
+function parse(argv, booleans, values, 
+/** For a command that runs one: how to write it, so an option that belongs
+ * to the command (`python3 -c ...`) is pointed after the `--`. */
+commandAfter) {
+    const known = new Set([...values, ...booleans]);
     const positional = [];
-    const flags = new Map();
+    const flags = new Flags(known);
     let rest;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -169,6 +204,10 @@ function parse(argv, booleans = []) {
         }
         if (arg.startsWith("--") || (arg.startsWith("-") && arg.length === 2 && !/^-\d/.test(arg))) {
             const [name, inline] = arg.replace(/^-+/, "").split(/=(.*)/s, 2);
+            if (!known.has(name))
+                throw commandAfter && !meantOption(name, known)
+                    ? usage(`Unknown option ${arg.split("=")[0]}. If it belongs to the command, put the command after --: ${commandAfter}`)
+                    : unknownOption(name, known);
             const value = inline ?? (booleans.includes(name) ? "true" : argv[++i]);
             if (value === undefined)
                 throw usage(`--${name} needs a value.`);
@@ -179,6 +218,22 @@ function parse(argv, booleans = []) {
     }
     return { positional, flags, rest };
 }
+/** The declared option a mistyped one most likely meant. --memory-mib for
+ * --memory, --timeout-seconds for --timeout: the SDK's spelling of an option is
+ * the CLI's with its unit added. */
+function meantOption(name, known) {
+    return ([...known].find((option) => name.startsWith(`${option}-`) || option.startsWith(`${name}-`)) ??
+        closest(name, [...known]));
+}
+/** "Unknown option --x", the one that was likely meant, and the ones there are. */
+function unknownOption(name, known) {
+    const dash = (option) => (option.length === 1 ? `-${option}` : `--${option}`);
+    const meant = meantOption(name, known);
+    const options = [...known].filter((option) => option.length > 1).map(dash);
+    return usage(`Unknown option ${dash(name)}.${meant ? ` Did you mean ${dash(meant)}?` : ""}${options.length
+        ? ` This command takes ${options.join(", ")}.`
+        : " This command takes no options."}`);
+}
 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) => {
@@ -189,6 +244,13 @@ const integer = (args, name) => {
         throw usage(`--${name} must be a whole number.`);
     return Number(value);
 };
+/** A flag that takes one of a few words, checked before anything is sent. */
+function oneOf(args, name, choices) {
+    const value = flag(args, name);
+    if (!choices.includes(value))
+        throw usage(`--${name} takes ${choices.join(" or ")}.`);
+    return value;
+}
 const pairs = (args, name) => Object.fromEntries((args.flags.get(name) ?? []).map((pair) => {
     const at = pair.indexOf("=");
     if (at < 1)
@@ -197,7 +259,7 @@ const pairs = (args, name) => Object.fromEntries((args.flags.get(name) ?? []).ma
 }));
 /** What the commands in cli-extras.ts use of this file. */
 const kit = {
-    parse: (argv, booleans) => parse(argv, booleans),
+    parse: (argv, booleans, values) => parse(argv, booleans, values),
     flag,
     has,
     integer,
@@ -218,30 +280,37 @@ function usage(message) {
 }
 /** "Unknown command X." and, when one is close, the command that was meant. */
 function unknown(what, word, choices) {
+    const meant = closest(word, choices);
+    return usage(`Unknown ${what} ${word}.${meant ? ` Did you mean ${meant}?` : ""}`);
+}
+/** The choice a mistyped word most likely meant, or none when nothing is close:
+ * one edit away (a swap of two letters counts as one), or two for a word longer
+ * than five letters, so "exce" finds exec and "bogus" finds nothing. */
+function closest(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;
+        const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+        for (let i = 1; i <= a.length; 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;
+                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+                d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+                if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                    d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
             }
-        }
-        return row[b.length];
+        return d[a.length][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}?` : ""}`);
+    return best && best[1] <= (word.length > 5 ? 2 : 1) ? best[0] : undefined;
 }
 const COMMANDS = [
+    "account",
+    "audit",
     "login",
     "logout",
     "whoami",
     "usage",
+    "billing",
     "limits",
     "sso",
     "secrets",
@@ -262,12 +331,38 @@ const COMMANDS = [
     "port",
     "address",
     "tunnel",
+    "network",
     "webhooks",
     "otel",
     "events",
     "help",
     "version",
 ];
+/** Commands with a help of their own: `runtime <command> help`. */
+const OWN_HELP = [
+    "sandbox",
+    "sandboxes",
+    "sbx",
+    "snapshot",
+    "snapshots",
+    "image",
+    "images",
+    "volume",
+    "volumes",
+    "keys",
+    "webhooks",
+    "webhook",
+    "billing",
+    "domain",
+    "domains",
+    "port",
+    "ports",
+    "address",
+    "addresses",
+    "tunnel",
+    "tunnels",
+    "network",
+];
 /** Sandbox commands that once sat at the top level. */
 const SANDBOX_MOVED = ["run", "ssh", "port-forward", "forward"];
 const SANDBOX_VERBS = [
@@ -313,6 +408,14 @@ function need(value, what) {
         throw usage(`Give ${what}.`);
     return value;
 }
+/** A port from the command line: a whole number from 1 to 65535, checked
+ * before any call so a typo is a usage error, not a 404 from the API. */
+function portOf(value, example) {
+    const port = Number(need(value, `a port, e.g. ${example}`));
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        throw usage(`${value} is not a port: give a whole number from 1 to 65535, e.g. ${example}.`);
+    return port;
+}
 /** 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
@@ -339,6 +442,7 @@ async function client(env) {
             env.RUNTIME_NO_LOGIN)
             throw error;
         process.stderr.write("This machine is not connected to Runtime yet. Connecting it first.\n");
+        const { authenticationCommand } = await import("./login.js");
         const login = await authenticationCommand(["login"], env);
         if (login.pending)
             throw notApprovedYet(login);
@@ -381,7 +485,7 @@ function describe(info) {
                 .map(([k, v]) => `${k}=${v}`)
                 .join(", ") || "-",
         ],
-        ["charged", `$${(info.chargedMicros / 1e6).toFixed(6)}`],
+        ["charged", dollars(BigInt(Math.round(Number(info.chargedMicros) || 0)))],
     ]);
 }
 /** Resolves `<id>:/path` into its parts, or undefined for a local path. */
@@ -400,6 +504,16 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         SANDBOX_MOVED.includes(remaining[0] ?? "");
     const command = nested ? remaining[0] : first;
     const rest = nested ? remaining.slice(1) : remaining;
+    // `runtime sandbox create --help` is how an agent asks what a command takes:
+    // answer with the product's help, never by running the command.
+    const cut = remaining.indexOf("--");
+    if (first &&
+        (cut < 0 ? remaining : remaining.slice(0, cut)).some((arg) => arg === "--help" || arg === "-h"))
+        return run(nested && command === "ssh"
+            ? [first, "ssh", "help"]
+            : OWN_HELP.includes(first)
+                ? [first, "help"]
+                : ["help"], env, out);
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     product = "";
     if (!command) {
@@ -425,14 +539,14 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "run") {
-        const args = parse(rest, [...CREATE_FLAGS, "keep"]);
+        const args = parse(rest, [...CREATE_FLAGS, "keep"], [...CREATE_VALUES, "cwd", "env"], `${me} sandbox run -- python3 -c 'print(6*7)'`);
         const commandLine = args.rest ?? args.positional;
         if (!commandLine.length)
             throw usage(`Give the command after --: ${me} sandbox 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);
+        const sbx = await runtime.sandboxes.create(input, { onCapacityWait: waiting(out) });
         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.
@@ -462,7 +576,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             process.once("SIGINT", interrupted);
         let code = 1;
         try {
-            code = await execute(sbx, commandLine, args, out, timeout);
+            code = await execute(sbx, commandLine, args, out, timeout, has(args, "keep"));
         }
         finally {
             try {
@@ -482,6 +596,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "login" || command === "logout") {
+        const { authenticationCommand } = await import("./login.js");
         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.`
@@ -491,9 +606,26 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "whoami") {
-        const who = await (await client(env)).me();
+        const rt = await client(env);
+        // The usage call only adds the funding line: a key that cannot read it
+        // still gets its answer.
+        const [who, spend] = await Promise.all([rt.me(), rt.usage().catch(() => undefined)]);
+        const trialLeft = spend?.trial ? spend.trial.availableMs / 3_600_000 : 0;
+        const credit = spend ? BigInt(spend.available) : 0n;
+        const funding = !spend
+            ? undefined
+            : [
+                ...(trialLeft > 0
+                    ? [
+                        `free trial, ${trialLeft.toLocaleString("en-US", { maximumFractionDigits: 1 })} hours left`,
+                    ]
+                    : []),
+                ...(credit > 0n ? [`${dollars(credit)} of credit`] : []),
+            ].join("; ") || "no trial time or credit left: runtime billing";
         print(table([
-            ["organization", who.orgId],
+            ["organization", who.orgName ? `${who.orgName} (${who.orgId})` : who.orgId],
+            ...(who.role ? [["role", who.role]] : []),
+            ...(funding ? [["funding", funding]] : []),
             ["agent", who.principalId],
             ["key", who.credentialId ?? "-"],
             ["api", who.apiVersion],
@@ -501,7 +633,17 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "usage") {
+        const csv = rest.includes("--csv");
+        const unknown = rest.find((arg) => arg !== "--csv");
+        if (unknown)
+            throw usage(`Unknown option ${unknown}: ${me} usage [--csv | --json]`);
         const value = await (await client(env)).usage();
+        if (csv) {
+            out.write(usageCsv(value));
+            if ((value.resources ?? []).length >= 100)
+                out.error("These are the newest 100 resources; older ones are not in this export.");
+            return 0;
+        }
         print(usageSummary(value), value);
         return 0;
     }
@@ -533,7 +675,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     if (command === "otel")
         return otelCommand(rest, env, out);
     if (command === "events") {
-        const args = parse(rest);
+        const args = parse(rest, [], ["sandbox", "type", "limit"]);
         const rt = await client(env);
         const sandbox = flag(args, "sandbox");
         const page = await rt.events.list({
@@ -577,7 +719,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     if (command === "account" || command === "accounts")
         return accountCommand(rest, env, out);
     if (command === "audit") {
-        const args = parse(rest);
+        const args = parse(rest, [], ["action", "limit", "before"]);
         const known = new Set(["action", "limit", "before"]);
         for (const name of args.flags.keys())
             if (!known.has(name))
@@ -605,6 +747,24 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             : "Nothing recorded yet.", page);
         return 0;
     }
+    if (command === "billing") {
+        product = "billing";
+        const origins = connectionOrigins(env);
+        const { claimWalletAccount, openWalletAccount } = await import("./wallet.js");
+        return billingCommand(rest, parse(rest, ["wait", "new-account", "accept-terms"], []), out, () => client(env), undefined, {
+            open: (input) => openWalletAccount(input, { authUrl: origins.auth }),
+            claim: (code) => claimWalletAccount(code, { authUrl: origins.auth }),
+            save: (key, orgId) => connectionStore(env).save({
+                version: 1,
+                apiOrigin: origins.api,
+                authOrigin: origins.auth,
+                key,
+                connectionId: "pasted",
+                orgId,
+                agentName: "Wallet agent",
+            }),
+        });
+    }
     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 })}`;
@@ -646,7 +806,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         return 0;
     }
     if (command === "feedback") {
-        const args = parse(rest, ["list"]);
+        const args = parse(rest, ["list"], ["kind", "detail", "competitor", "request-id"]);
         if (has(args, "list")) {
             const { data } = await (await client(env)).feedback.list();
             print(data.length
@@ -707,11 +867,11 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     if (command === "ssh") {
         product = "ssh";
-        return sshCommand(rest, env, out, () => client(env), me);
+        return (await import("./ssh.js")).sshCommand(rest, env, out, () => client(env), me);
     }
     if (command === "port-forward" || command === "forward") {
         product = "ssh";
-        return portForwardCommand(rest, out, () => client(env), me);
+        return (await import("./ssh.js")).portForwardCommand(rest, out, () => client(env), me);
     }
     if (command === "sandbox" || command === "sandboxes" || command === "sbx") {
         product = "sandbox";
@@ -733,13 +893,62 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         command;
     if (NETWORK_PRODUCTS.includes(networkProduct)) {
         product = networkProduct;
-        return networkProductCommand(networkProduct, rest, parse(rest, ["ipv6"]), out, () => client(env));
+        return networkProductCommand(networkProduct, rest, parse(rest, ["ipv6"], ["sandbox", "subnet", "public-key", "route", "out", "host", "secret"]), out, () => client(env));
     }
     throw unknown("command", command, COMMANDS);
 }
 /** `runtime usage` for a person: the balance, the trial and what each kind
  * of resource was charged, in dollars. --json keeps every figure, and each
  * resource with its rates and CPU time. */
+/** One row per resource, for a spreadsheet: when it ran, how big it was, how
+ * long it ran, the CPU it used and what it cost. Money is exact dollars to the
+ * microdollar (the API's integer microdollars moved six places), so a column
+ * sums to the ledger to the last digit. */
+export function usageCsv(u) {
+    const cell = (value) => {
+        const text = typeof value === "string" || typeof value === "number" || typeof value === "bigint"
+            ? String(value)
+            : "";
+        return /[",\n\r]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+    };
+    const exact = (value) => {
+        const micros = BigInt(typeof value === "number" || typeof value === "string" ? value : 0);
+        const sign = micros < 0n ? "-" : "";
+        const size = micros < 0n ? -micros : micros;
+        return `${sign}${size / 1000000n}.${(size % 1000000n).toString().padStart(6, "0")}`;
+    };
+    const head = [
+        "resource_id",
+        "name",
+        "kind",
+        "state",
+        "created_at",
+        "vcpu",
+        "memory_mib",
+        "running_seconds",
+        "active_cpu_seconds",
+        "memory_gib_seconds",
+        "charged_usd",
+        "held_usd",
+    ];
+    const rows = (u.resources ?? []).map((r) => [
+        r.resourceId,
+        r.name,
+        r.kind,
+        r.state ?? r.status,
+        r.createdAt,
+        r.vcpu,
+        r.memoryMiB,
+        r.runningSeconds,
+        r.activeCpuSeconds,
+        r.memoryGiBSeconds,
+        exact(r.chargedMicros),
+        exact(r.heldMicros),
+    ]
+        .map(cell)
+        .join(","));
+    return [head.join(","), ...rows].join("\n");
+}
 function usageSummary(u) {
     const micros = (value) => typeof value === "string" || typeof value === "number" || typeof value === "bigint"
         ? BigInt(value)
@@ -749,11 +958,14 @@ function usageSummary(u) {
     const rows = [
         ["available", dollars(micros(u.available))],
         ["credited", dollars(micros(u.credited))],
-        [
-            "spent",
-            `${dollars(micros(u.spent))}${takenBack > 0n ? `, ${dollars(takenBack)} of it refunded or disputed` : ""}`,
-        ],
-        ["held for running work", dollars(micros(u.held))],
+        // spent includes what refunds and disputes took back: say that part on
+        // its own line, so "spent" reads as what was used.
+        ["used", dollars(micros(u.spent) - takenBack)],
+        ...(takenBack > 0n ? [["returned by refunds and disputes", dollars(takenBack)]] : []),
+        // Holds cover running sandboxes and the hour ahead of stored snapshots,
+        // images and volumes (pricing guide), so an account with nothing running
+        // can still show one.
+        ["held for running sandboxes and this hour's storage", dollars(micros(u.held))],
     ];
     if (micros(u.expired) > 0n)
         rows.push(["expired or taken back", dollars(micros(u.expired))]);
@@ -788,13 +1000,15 @@ function usageSummary(u) {
             ])
             : "No resources yet.",
         "",
-        `Each resource, with its rates and CPU time: ${me} usage --json`,
+        `Each resource, with its rates and CPU time: ${me} usage --json, or --csv for a spreadsheet`,
     ].join("\n");
 }
 const SANDBOX_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** A sandbox's id from its id or its name, for the filters that take an id. */
 async function sandboxIdOf(runtime, target) {
-    return SANDBOX_UUID.test(target) ? target : (await resolveSandbox(runtime, target)).id;
+    return SANDBOX_UUID.test(target)
+        ? target
+        : (await (await import("./ssh.js")).resolveSandbox(runtime, target)).id;
 }
 /** What a process has printed so far, in order, without waiting for more. */
 async function outputSoFar(runtime, sandboxId, processId) {
@@ -900,7 +1114,7 @@ function trialNote(trial, all) {
     return ` ${which} ran on the free trial, which charged nothing; Runtime's side prices ${trial === 1 ? "it" : "them"} at the standard rates, what the same work costs on paid credit.`;
 }
 async function switching(command, argv, env, out) {
-    const args = parse(argv);
+    const args = parse(argv, [], command === "compare" ? ["from", "days"] : ["from"]);
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     const known = new Set(command === "compare" ? ["from", "days"] : ["from"]);
     for (const name of args.flags.keys())
@@ -927,7 +1141,7 @@ async function switching(command, argv, env, out) {
         return 0;
     }
     if (!from)
-        throw usage(`Name the rival: ${me} compare --from e2b (or daytona, vercel, modal, cloudflare, fly, fly-machines...).`);
+        throw usage(`Name the rival: ${me} compare --from e2b (or daytona, vercel, modal, cloudflare, fly, fly-machines, lambda-microvms, freestyle, prime...).`);
     /* The server holds the list of rivals it has rates for, and names them all
        when it refuses one, so a rival added there needs no new CLI. */
     const days = integer(args, "days");
@@ -942,7 +1156,7 @@ async function switching(command, argv, env, out) {
     const monthly = month === undefined
         ? ""
         : month >= 0n
-            ? `about ${dollars(month)} a month`
+            ? `a saving of about ${dollars(month)} a month`
             : `about ${dollars(-month)} a month more on Runtime`;
     /* The month is projected from the days the usage covers, not from the
        window asked for: say which, or a young account's 7 and 90 days read the
@@ -951,7 +1165,7 @@ async function switching(command, argv, env, out) {
     const pace = month === undefined
         ? "."
         : covered < c.window.days
-            ? `. Your first sandbox in this window ran ${covered <= 1 ? "within the last day" : `${covered.toLocaleString("en-US")} days ago`}; at that pace, ${monthly}.`
+            ? `. Your usage so far covers ${covered <= 1 ? "less than a day" : `${covered.toLocaleString("en-US")} days`}; at that pace, ${monthly}.`
             : c.window.days === 30
                 ? `, ${monthly}.`
                 : `. At that pace, ${monthly}.`;
@@ -972,7 +1186,7 @@ async function switching(command, argv, env, out) {
     return 0;
 }
 async function support(argv, env, out) {
-    const args = parse(argv);
+    const args = parse(argv, [], ["conversation"]);
     const api = (await client(env)).support;
     const conversationId = flag(args, "conversation");
     const [first, second, third] = args.positional;
@@ -1010,9 +1224,10 @@ async function sandbox(argv, env, out) {
     }
     // Inside a sandbox, with no API key: the sandbox's own request token asks.
     if (verb === "identity-token") {
-        const args = parse(rest);
+        const args = parse(rest, [], ["audience", "lifetime"]);
         const audience = need(flag(args, "audience"), "--audience, such as sts.amazonaws.com");
         const lifetime = flag(args, "lifetime");
+        const { identityToken } = await import("./identity.js");
         const token = await identityToken({
             audience,
             ...(lifetime === undefined ? {} : { lifetimeSeconds: Number(lifetime) }),
@@ -1023,17 +1238,26 @@ async function sandbox(argv, env, out) {
     const runtime = await client(env);
     /* By id or by name, for every command here, as ssh and port-forward
        always took one. */
-    const get = (id) => resolveSandbox(runtime, need(id, "a sandbox id or name"));
+    const get = async (id) => (await import("./ssh.js")).resolveSandbox(runtime, need(id, "a sandbox id or name"));
+    /* For a command that needs only the id: an id is used as it is, with no
+       lookup first, so `exec` is one request and not two (about 110 ms less
+       from Colorado to Virginia). A sandbox that is gone or stopped is refused
+       by the command itself, with the same words. */
+    const use = async (id) => SANDBOX_UUID.test(id ?? "")
+        ? new SandboxHandle(runtime.transport, { id })
+        : get(id);
     switch (verb) {
         case "create": {
-            const args = parse(rest, CREATE_FLAGS);
-            const sbx = await runtime.sandboxes.create(createInput(args));
+            const args = parse(rest, CREATE_FLAGS, CREATE_VALUES);
+            const sbx = await runtime.sandboxes.create(createInput(args), {
+                onCapacityWait: waiting(out),
+            });
             print(sbx.id, sbx.info);
             return 0;
         }
         case "ls":
         case "list": {
-            const args = parse(rest, ["all"]);
+            const args = parse(rest, ["all"], ["label", "state"]);
             const page = await runtime.sandboxes.list({
                 ...(has(args, "all") ? { includeStopped: true } : {}),
                 ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
@@ -1085,8 +1309,8 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "mount": {
-            const args = parse(rest, ["read-only"]);
-            const sbx = await get(args.positional[0]);
+            const args = parse(rest, ["read-only"], ["secret", "region", "endpoint", "account-id"]);
+            const sbx = await use(args.positional[0]);
             const source = need(args.positional[1], "a bucket, as s3://bucket, r2://bucket or gcs://bucket");
             const found = /^(s3|r2|gcs):\/\/([^/]+)(?:\/(.+))?$/.exec(source);
             if (!found)
@@ -1106,7 +1330,7 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "mounts": {
-            const sbx = await get(rest[0]);
+            const sbx = await use(rest[0]);
             const all = await sbx.mounts.list();
             print(all.length
                 ? table([
@@ -1123,13 +1347,13 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "unmount": {
-            const sbx = await get(rest[0]);
+            const sbx = await use(rest[0]);
             const gone = await sbx.mounts.remove(need(rest[1], "the mounted path"));
             print(`${gone.path} unmounted`, gone);
             return 0;
         }
         case "snapshot": {
-            const args = parse(rest);
+            const args = parse(rest, [], ["name", "retention"]);
             const sbx = await get(args.positional[0]);
             const snapshot = await sbx.snapshot({
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
@@ -1139,7 +1363,7 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "fork": {
-            const args = parse(rest, ["keep-snapshot", "trial", "paid"]);
+            const args = parse(rest, ["keep-snapshot", "trial", "paid"], ["count", "name"]);
             const sbx = await get(args.positional[0]);
             const forks = await sbx.fork({
                 count: integer(args, "count") ?? 1,
@@ -1155,7 +1379,7 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "update": {
-            const args = parse(rest);
+            const args = parse(rest, [], ["name", "label", "idle-pause", "auto-wake", "persistent", "max-total-cost"]);
             const sbx = await get(args.positional[0]);
             const onOff = (name) => {
                 const value = flag(args, name);
@@ -1196,19 +1420,19 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "exec": {
-            const args = parse(rest);
+            const args = parse(rest, [], ["cwd", "env", "timeout"], `${me} sandbox exec <id> -- ls -la`);
             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]);
+            const sbx = await use(args.positional[0]);
             return execute(sbx, command, args, out, integer(args, "timeout"));
         }
         case "spawn": {
-            const args = parse(rest, ["pty"]);
+            const args = parse(rest, ["pty"], ["cwd", "env"], `${me} sandbox spawn <id> -- npm run dev`);
             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 sbx = await use(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") } : {}),
@@ -1218,7 +1442,7 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "ps": {
-            const sbx = await get(rest[0]);
+            const sbx = await use(rest[0]);
             const list = await sbx.processes.list();
             print(list.length
                 ? table([
@@ -1229,8 +1453,8 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "logs": {
-            const args = parse(rest, ["f", "follow"]);
-            const sbx = await get(args.positional[0]);
+            const args = parse(rest, ["f", "follow"], []);
+            const sbx = await use(args.positional[0]);
             const proc = await sbx.processes.get(need(args.positional[1], "a process id"));
             if (has(args, "f") || has(args, "follow")) {
                 for await (const event of proc.output())
@@ -1256,26 +1480,28 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "kill": {
-            const args = parse(rest);
-            const sbx = await get(args.positional[0]);
+            const args = parse(rest, [], ["signal"]);
+            const sbx = await use(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]);
+            const args = parse(rest, [], ["command"]);
+            const sbx = await use(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")));
+            const sbx = await use(rest[0]);
+            // Streamed, any size; a stream that ends short throws, so exit is 1.
+            const { Writable } = await import("node:stream");
+            await (await sbx.files.readStream(need(rest[1], "a path"))).pipeTo(Writable.toWeb(process.stdout), { preventClose: true, preventAbort: true });
             return 0;
         }
         case "files": {
-            const args = parse(rest);
-            const sbx = await get(args.positional[0]);
+            const args = parse(rest, [], ["depth", "glob"]);
+            const sbx = await use(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") } : {}),
@@ -1286,36 +1512,51 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "cp": {
-            const [from, to] = parse(rest).positional;
+            const [from, to] = parse(rest, ["r", "recursive"], []).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);
+            // A destination ending in / (or a local directory) takes the source's
+            // own name inside it, as cp does.
+            const inside = (dir, path) => `${dir.replace(/\/+$/, "")}/${path.replace(/\/+$/, "").split("/").pop()}`;
+            if (source && !target) {
+                const local = await import("node:fs/promises").then((fs) => fs.stat(to).catch(() => null));
+                await (await use(source.id)).files.download(source.path, to.endsWith("/") || local?.isDirectory() ? inside(to, source.path) : to);
+            }
             else if (!source && target)
-                await (await get(target.id)).files.upload(from, target.path);
+                await (await use(target.id)).files.upload(from, target.path.endsWith("/") ? inside(target.path, 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);
+            return runCode(await use(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"));
+            if (rest[0] === "rotate") {
+                const port = portOf(rest[2], "runtime sandbox preview rotate <id> 3000");
+                const sbx = await use(rest[1]);
+                const preview = await sbx.previews.rotate(port);
+                print(preview.visibility === "public"
+                    ? `Port ${port} is public: it takes no token, so there was none to refuse.`
+                    : `${preview.urlWithToken ?? preview.url}\nEvery earlier token for port ${port} is refused. New header: x-runtime-preview-token: ${preview.token} (expires ${preview.tokenExpiresAt}).`, preview);
+                return 0;
+            }
+            const args = parse(rest, ["public"], ["ttl"]);
+            const port = portOf(args.positional[1], "runtime sandbox preview <id> 3000");
+            const sbx = await use(args.positional[0]);
             const preview = await sbx.previews.create(port, {
                 ...(has(args, "public") ? { visibility: "public" } : {}),
                 ...(integer(args, "ttl") ? { ttlSeconds: integer(args, "ttl") } : {}),
             });
-            print((preview.visibility === "public"
+            // The link and how to use it, nothing more: the API's `hint` (which
+            // carries a referral line) stays in --json, not in the command's words.
+            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);
+                : `${preview.urlWithToken ?? preview.url}\nPrivate: send the header x-runtime-preview-token: ${preview.token} (expires ${preview.tokenExpiresAt}).`, preview);
             return 0;
         }
         case "previews": {
-            const list = await (await get(rest[0])).previews.list();
+            const list = await (await use(rest[0])).previews.list();
             print(list.length
                 ? table([
                     ["PORT", "VISIBILITY", "URL"],
@@ -1325,14 +1566,14 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "unshare": {
-            const sbx = await get(rest[0]);
-            const port = Number(need(rest[1], "the port"));
+            const port = portOf(rest[1], "runtime sandbox unshare <id> 3000");
+            const sbx = await use(rest[0]);
             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 args = parse(rest, ["no-internet", "internet"], ["allow", "deny", "connect"]);
+            const sbx = await use(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({
@@ -1342,7 +1583,10 @@ async function sandbox(argv, env, out) {
                 : await sbx.network.get();
             print(table([
                 ["internet", policy.internet ? "on" : "off"],
-                ["allow", policy.allow.join(", ") || "(the public web)"],
+                [
+                    "allow",
+                    policy.allow.join(", ") || (policy.internet ? "(the public web)" : "(nothing)"),
+                ],
                 ["deny", policy.deny.join(", ") || "-"],
                 ["connect", policy.connect.join(", ") || "-"],
                 ["enforced", policy.enforced ? "yes" : "not yet; run the same command again"],
@@ -1350,9 +1594,9 @@ async function sandbox(argv, env, out) {
             return 0;
         }
         case "desktop":
-            return desktop(await get(rest[0]), rest.slice(1), out);
+            return desktop(await use(rest[0]), rest.slice(1), out);
         case "watch":
-            return (await import("./cli-extras.js")).watchCommand(await get(rest[0]), rest.slice(1), out, kit);
+            return (await import("./cli-extras.js")).watchCommand(await use(rest[0]), rest.slice(1), out, kit);
         case "mcp":
             if (rest[0] === "catalog" || rest[0] === undefined) {
                 const catalog = await runtime.mcp.catalog();
@@ -1371,10 +1615,10 @@ async function sandbox(argv, env, out) {
                 ]), catalog);
                 return 0;
             }
-            return (await import("./cli-extras.js")).mcpCommand(await get(rest[0]), rest.slice(1), out, kit);
+            return (await import("./cli-extras.js")).mcpCommand(await use(rest[0]), rest.slice(1), out, kit);
         case "metrics": {
-            const args = parse(rest);
-            const sbx = await get(args.positional[0]);
+            const args = parse(rest, [], ["range"]);
+            const sbx = await use(args.positional[0]);
             const range = (flag(args, "range") ?? "1h");
             if (!["15m", "1h", "6h", "24h", "7d", "30d"].includes(range))
                 throw usage("--range is one of 15m, 1h, 6h, 24h, 7d, 30d.");
@@ -1436,20 +1680,49 @@ async function readSecret() {
         stdin.pause();
     }
 }
+/** `--allow` values as secret rules: each is `[METHOD[,METHOD]...] PATH`, and
+ * rules naming the same methods share one rule's paths. Only the shape is read
+ * here; the API holds every rule to the same check the host makes
+ * (ARCHITECTURE.md section 10, "Per-path rules on an egress secret") and says
+ * which one it refused. */
+export function parseSecretRules(values) {
+    const byMethods = new Map();
+    for (const value of values) {
+        const words = value.trim().split(/\s+/);
+        const path = words.at(-1);
+        if (!path || words.length > 2 || !path.startsWith("/"))
+            throw usage(`--allow takes optional methods and one path, such as --allow "GET,HEAD /repos/acme/*" or --allow /v1/chat/completions; got ${JSON.stringify(value)}.`);
+        const methods = words.length === 2
+            ? [...new Set(words[0].toUpperCase().split(",").filter(Boolean))].sort()
+            : undefined;
+        const key = methods?.join(",") ?? "";
+        const rule = byMethods.get(key) ?? { ...(methods ? { methods } : {}), paths: [] };
+        if (!rule.paths.includes(path))
+            rule.paths.push(path);
+        byMethods.set(key, rule);
+    }
+    return [...byMethods.values()];
+}
+const ruleText = (rules) => rules?.length
+    ? rules
+        .map((rule) => `${rule.methods ? `${rule.methods.join(",")} ` : ""}${rule.paths.join(" ")}`)
+        .join("; ")
+    : "-";
 export async function secretsCommand(argv, env, out, 
 /** Tests give the value here; the CLI reads standard input. */
 read = readSecret) {
     const [verb, ...rest] = argv;
-    const args = parse(rest);
+    const args = parse(rest, [], ["host", "header", "format", "allow", "value"]);
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     const rows = (list) => list.length
         ? table([
-            ["name", "hosts", "header", "placeholder"],
+            ["name", "hosts", "header", "placeholder", "allow"],
             ...list.map((secret) => [
                 secret.name,
                 secret.hosts.join(","),
                 secret.header ? `${secret.header}: ${secret.format ?? "{value}"}` : "-",
                 secret.placeholder,
+                ruleText(secret.rules),
             ]),
         ])
         : "No secrets.";
@@ -1470,17 +1743,21 @@ read = readSecret) {
             throw usage('The value is empty. Pipe it in: printf %s "$KEY" | runtime secrets set NAME --host ...');
         const header = flag(args, "header");
         const format = flag(args, "format");
+        const allow = args.flags.get("allow");
+        const rules = allow ? parseSecretRules(allow) : undefined;
         const saved = await (await client(env)).secrets.set(name, {
             value,
             hosts,
             ...(header ? { header } : {}),
             ...(format ? { format } : {}),
+            ...(rules ? { rules } : {}),
         });
         print([
             `Stored ${saved.name}. Sandboxes see ${saved.name}=${saved.placeholder}.`,
             saved.header
                 ? `Requests to ${saved.hosts.join(", ")} get ${saved.header}: ${saved.format ?? "{value}"} over HTTPS.`
                 : `Over HTTPS to ${saved.hosts.join(", ")}, the placeholder becomes the value in the URL and headers.`,
+            ...(saved.rules?.length ? [`Only these requests get it: ${ruleText(saved.rules)}.`] : []),
             ...(saved.enforced
                 ? []
                 : ["A host is catching up; running sandboxes have it within a minute."]),
@@ -1504,7 +1781,7 @@ async function readInput(source) {
     return Buffer.concat(chunks).toString("utf8");
 }
 async function runCode(sbx, argv, out) {
-    const args = parse(argv);
+    const args = parse(argv, [], ["lang", "context", "timeout", "out-dir"]);
     const source = need(args.positional[0], "a file, or - to read the code from standard input");
     const code = await readInput(source);
     const byExtension = {
@@ -1572,7 +1849,7 @@ async function desktop(sbx, argv, out) {
     const d = sbx.desktop;
     switch (action) {
         case "start": {
-            const args = parse(rest);
+            const args = parse(rest, [], ["width", "height"]);
             const started = await d.start({
                 ...(integer(args, "width") ? { width: integer(args, "width") } : {}),
                 ...(integer(args, "height") ? { height: integer(args, "height") } : {}),
@@ -1638,6 +1915,7 @@ async function accountCommand(argv, env, out) {
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     const store = connectionStore(env);
     if (verb === "add") {
+        const { authenticationCommand } = await import("./login.js");
         const result = await authenticationCommand(["login", "--another-account", ...rest], env);
         if (result.pending)
             throw notApprovedYet(result);
@@ -1660,8 +1938,35 @@ async function accountCommand(argv, env, out) {
         });
         return 0;
     }
+    if (verb === "close") {
+        /* ARCHITECTURE.md section 3.1: an owner's key for every product, and the
+           account's name typed exactly. Nothing is asked twice: --confirm is the
+           confirmation, as the website's typed name is. */
+        const args = parse(rest, [], ["confirm"]);
+        for (const name of args.flags.keys())
+            if (name !== "confirm")
+                throw usage(`Unknown option --${name}.`);
+        const confirm = flag(args, "confirm");
+        const runtime = await client(env);
+        if (!confirm) {
+            const who = await runtime.me();
+            throw usage(`Closing stops and deletes everything in the account, ends every key and cannot be undone. To go ahead, type its name: ${me} account close --confirm "${who.orgName ?? "<account name>"}".`);
+        }
+        const closed = await runtime.account.close({ confirm });
+        // This machine's key died with the account.
+        if (!env.RUNTIME_API_KEY)
+            await store.remove().catch(() => undefined);
+        print([
+            `Closed ${closed.name}. Every key has stopped working.`,
+            closed.released
+                ? "Nothing was left running or stored."
+                : "What was still running is stopping, and everything stored is being deleted.",
+            "Credit bought in the last 15 days and not spent is refunded on request: write to support@withruntime.com.",
+        ].join("\n"), closed);
+        return 0;
+    }
     if (verb !== "ls" && verb !== "list")
-        throw unknown("account command", verb, ["ls", "switch", "add"]);
+        throw unknown("account command", verb, ["ls", "switch", "add", "close"]);
     await nameSaved(env).catch(() => undefined);
     const current = await store.read().catch(() => null);
     const saved = [
@@ -1717,7 +2022,7 @@ async function keys(argv, env, out) {
         throw usage("List and revoke keys at https://withruntime.com/account/keys. No key can list or revoke keys.");
     if (verb !== "create")
         throw unknown("keys command", verb, ["create"]);
-    const args = parse(rest, ["read-only"]);
+    const args = parse(rest, ["read-only"], ["name", "daily-limit"]);
     const known = new Set(["name", "read-only", "daily-limit"]);
     for (const name of args.flags.keys())
         if (!known.has(name))
@@ -1728,6 +2033,7 @@ async function keys(argv, env, out) {
     const limit = flag(args, "daily-limit");
     if (readOnly && limit !== undefined)
         throw usage("A read-only key cannot spend, so it takes no --daily-limit.");
+    const { createKey, dailyLimitMicros } = await import("./keys.js");
     const created = await createKey({
         name: flag(args, "name") ?? (readOnly ? "Read-only key" : "My API key"),
         access: readOnly ? "read" : "full",
@@ -1754,8 +2060,8 @@ const SNAPSHOT_HELP = `runtime snapshot <command>
   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().
+  Take one with \`runtime sandbox snapshot <sandboxId>\`; start a sandbox from it
+  with \`runtime sandbox create --snapshot <snapshotId>\`.
 `;
 async function snapshot(argv, env, out) {
     const [verb, ...rest] = argv;
@@ -1768,7 +2074,7 @@ async function snapshot(argv, env, out) {
     switch (verb) {
         case "ls":
         case "list": {
-            const args = parse(rest);
+            const args = parse(rest, [], ["sandbox", "name"]);
             const all = await (await api.list({
                 ...(flag(args, "sandbox")
                     ? { sandboxId: await sandboxIdOf(await client(env), flag(args, "sandbox")) }
@@ -1785,11 +2091,11 @@ async function snapshot(argv, env, out) {
         }
         case "get": {
             const found = await api.get(need(rest[0], "a snapshot id"));
-            print(JSON.stringify(found, null, 2), found);
+            print((await import("./cli-extras.js")).describeSnapshot(found, table), found);
             return 0;
         }
         case "extend": {
-            const days = integer(parse(rest.slice(1)), "days") ?? Number(need(rest[1], "days"));
+            const days = integer(parse(rest.slice(1), [], ["days"]), "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;
@@ -1809,8 +2115,10 @@ const IMAGE_HELP = `runtime image <command>
   build [<folder>] [-f <Dockerfile>] | --from <image> | --pip <pkg>... --apt <pkg>... --npm <pkg>...
         [-t name[:tag]]... [--target <stage>] [--build-arg K=V]... [--no-cache]
         [--start <command>] [--ready-port <port> | --ready-command <command>]
-        [--max-image-mib 8192] [--timeout <seconds>]
+        [--max-image-mib 8192] [--disk-mib <1024-32768>] [--timeout <seconds>]
                         Build and stream the log; prints the image id when ready.
+                        --disk-mib sizes the build's scratch disk, where earlier
+                        stages and the context live.
                         A Dockerfile's folder is the context: everything its
                         .dockerignore leaves in (100 MiB compressed at most) is
                         sent, and a rebuild sends only what changed.
@@ -1831,6 +2139,28 @@ const IMAGE_HELP = `runtime image <command>
   registry rm <registry>
   Use one: runtime sandbox create --image app:latest
 `;
+/** Options `image build` takes with a value. */
+const IMAGE_BUILD_VALUES = [
+    "f",
+    "file",
+    "dockerfile",
+    "from",
+    "pip",
+    "apt",
+    "npm",
+    "t",
+    "tag",
+    "name",
+    "target",
+    "build-arg",
+    "start",
+    "ready-port",
+    "ready-command",
+    "ready-timeout",
+    "max-image-mib",
+    "disk-mib",
+    "timeout",
+];
 export async function imageCommand(argv, env, out, 
 /** Tests give the registry secret here; the CLI reads standard input. */
 read = readSecret) {
@@ -1843,7 +2173,7 @@ read = readSecret) {
     const api = (await client(env)).images;
     switch (verb) {
         case "build": {
-            const args = parse(rest, ["no-cache"]);
+            const args = parse(rest, ["no-cache"], IMAGE_BUILD_VALUES);
             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;
@@ -1855,6 +2185,7 @@ read = readSecret) {
                 throw usage("Give exactly one of a folder with a Dockerfile (or -f <Dockerfile>), --from <image>, or --pip/--apt/--npm.");
             const build = {
                 ...(integer(args, "max-image-mib") ? { maxImageMiB: integer(args, "max-image-mib") } : {}),
+                ...(integer(args, "disk-mib") ? { diskMiB: integer(args, "disk-mib") } : {}),
                 ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
             };
             // -t app, -t app:v2 -t app:latest: one name, its tags.
@@ -1944,7 +2275,7 @@ read = readSecret) {
             return 0;
         }
         case "logs": {
-            const args = parse(rest, ["follow", "f"]);
+            const args = parse(rest, ["follow", "f"], []);
             const id = (await api.resolve(need(args.positional[0], "an image"))).id;
             if (has(args, "follow") || has(args, "f")) {
                 const lines = [];
@@ -1993,7 +2324,7 @@ read = readSecret) {
                 return 0;
             }
             if (action === "set") {
-                const args = parse(more);
+                const args = parse(more, [], ["username", "access-key-id"]);
                 const registry = need(args.positional[0], "a registry, such as ghcr.io");
                 const accessKeyId = flag(args, "access-key-id");
                 if (accessKeyId === undefined && flag(args, "username") === undefined)
@@ -2055,7 +2386,7 @@ async function volume(argv, env, out) {
     const api = (await client(env)).volumes;
     switch (verb) {
         case "create": {
-            const args = parse(rest);
+            const args = parse(rest, [], ["size-mib", "name"]);
             const created = await api.create({
                 sizeMiB: integer(args, "size-mib") ?? Number(need(undefined, "--size-mib <N>")),
                 ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
@@ -2093,7 +2424,7 @@ async function volume(argv, env, out) {
             return 0;
         }
         case "backup": {
-            const args = parse(rest, ["no-wait"]);
+            const args = parse(rest, ["no-wait"], ["retention-days"]);
             const id = need(args.positional[0], "a volume id");
             const days = integer(args, "retention-days");
             const made = await api.backup(id, days === undefined ? {} : { retentionDays: days }, has(args, "no-wait") ? { wait: 0 } : {});
@@ -2123,7 +2454,7 @@ async function volume(argv, env, out) {
             return 0;
         }
         case "restore": {
-            const args = parse(rest);
+            const args = parse(rest, [], ["name"]);
             const created = await api.restore(need(args.positional[0], "a backup id"), flag(args, "name") ? { name: flag(args, "name") } : {});
             if (!out.json && created.state === "creating")
                 out.error(`Restoring; check with: ${me} volume get ${created.id}`);
@@ -2137,7 +2468,7 @@ async function volume(argv, env, out) {
             return 0;
         }
         case "backup-policy": {
-            const args = parse(rest);
+            const args = parse(rest, [], ["daily", "retention-days"]);
             const id = need(args.positional[0], "a volume id");
             const daily = flag(args, "daily");
             if (daily !== undefined && !["on", "off", "true", "false"].includes(daily))
@@ -2175,6 +2506,49 @@ const CREATE_FLAGS = [
     "persistent",
     "get-or-create",
 ];
+/** Says on standard error, once for each reason, why a create has not
+ * answered yet: it is waiting for a trial slot or room, which can take up to
+ * two minutes, and silence reads as a hang. */
+function waiting(out) {
+    const said = new Set();
+    return (refusal) => {
+        if (said.has(refusal.code))
+            return;
+        said.add(refusal.code);
+        out.error(`${refusal.message} Waiting for room, up to 2 minutes; Ctrl-C stops.`);
+    };
+}
+/** Options `sandbox create` and `run` take with a value. */
+const CREATE_VALUES = [
+    "name",
+    "label",
+    "region",
+    "vcpu",
+    "memory",
+    "disk",
+    "cpu",
+    "cpu-floor",
+    "timeout",
+    "on-timeout",
+    "idle-pause",
+    "max-cost",
+    "max-total-cost",
+    "allow",
+    "deny",
+    "connect",
+    "image",
+    "snapshot",
+    "volume",
+];
+/** Dollars from the command line as integer microdollars: 25, 2.50 or 0.000001. */
+function usdMicros(args, name) {
+    const value = flag(args, name);
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+(\.\d{1,6})?$/.test(value))
+        throw usage(`--${name} takes dollars, such as 25 or 2.50.`);
+    return Math.round(Number(value) * 1e6);
+}
 /** A create body from the command line's flags. */
 function createInput(args) {
     const rules = ["allow", "deny", "connect"].filter((name) => args.flags.has(name));
@@ -2195,9 +2569,16 @@ function createInput(args) {
         ...(integer(args, "vcpu") ? { vcpu: integer(args, "vcpu") } : {}),
         ...(integer(args, "memory") ? { memoryMiB: integer(args, "memory") } : {}),
         ...(integer(args, "disk") ? { diskMiB: integer(args, "disk") } : {}),
+        ...(flag(args, "cpu") ? { cpu: oneOf(args, "cpu", ["shared", "reserved"]) } : {}),
+        ...(integer(args, "cpu-floor") ? { cpuFloorMillis: integer(args, "cpu-floor") } : {}),
+        ...(flag(args, "region") ? { region: flag(args, "region") } : {}),
+        ...(usdMicros(args, "max-cost") ? { maxCostMicros: usdMicros(args, "max-cost") } : {}),
+        ...(usdMicros(args, "max-total-cost")
+            ? { maxTotalCostMicros: usdMicros(args, "max-total-cost") }
+            : {}),
         ...(integer(args, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
         ...(flag(args, "on-timeout")
-            ? { onLeaseEnd: flag(args, "on-timeout") }
+            ? { onLeaseEnd: oneOf(args, "on-timeout", ["pause", "stop"]) }
             : {}),
         ...(integer(args, "idle-pause") !== undefined
             ? { idlePauseSeconds: integer(args, "idle-pause") }
@@ -2215,7 +2596,9 @@ function createInput(args) {
 }
 /** 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) {
+async function execute(sbx, command, args, out, timeout, 
+/** `run` stops its whole sandbox on Ctrl-C, so it handles the signal itself. */
+ownInterrupt = true) {
     const target = command.length === 1 ? command[0] : command;
     const extras = await import("./cli-extras.js");
     const stdin = await extras.pipedStdin();
@@ -2225,13 +2608,32 @@ async function execute(sbx, command, args, out, timeout) {
         ...(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),
-        });
+    // Ctrl-C stops the command in the sandbox too, and says so; without this
+    // the CLI exited and the command ran on unseen.
+    const interrupt = new AbortController();
+    const onInterrupt = () => interrupt.abort(new Error("Interrupted"));
+    if (ownInterrupt)
+        process.once("SIGINT", onInterrupt);
+    let result;
+    try {
+        result = out.json
+            ? await sbx.exec(target, { ...options, signal: interrupt.signal })
+            : await sbx.exec(target, {
+                ...options,
+                signal: interrupt.signal,
+                onStdout: (t) => process.stdout.write(t),
+                onStderr: (t) => process.stderr.write(t),
+            });
+    }
+    catch (error) {
+        if (!interrupt.signal.aborted)
+            throw error;
+        out.error(describeError(error, out.json));
+        return 130;
+    }
+    finally {
+        process.off("SIGINT", onInterrupt);
+    }
     if (out.json)
         out.write(JSON.stringify(result));
     else if (result.timedOut)
@@ -2253,13 +2655,12 @@ async function shell(sbx, command) {
     });
     if (stdin.isTTY)
         stdin.setRawMode(true);
+    const unhook = (await import("./cli-extras.js")).pipeShellInput(stdin, terminal);
     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);
+    unhook();
     process.stdout.off("resize", onResize);
     if (stdin.isTTY)
         stdin.setRawMode(false);
@@ -2289,7 +2690,13 @@ export function describeError(error, json) {
                     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})` : ""}`;
+        return `Error [${error.code}]: ${error.message}${error.hint ? `\nHint: ${error.hint}` : ""}${error.requestId
+            ? // A refusal of what was sent is the caller's to fix; only a failure
+                // of ours is worth a report.
+                error.status >= 400 && error.status < 500
+                    ? `\nRequest: ${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}`;
@@ -2367,7 +2774,7 @@ async function webhooksCommand(argv, env, out) {
         return 0;
     }
     const hooks = (await client(env)).webhooks;
-    const args = parse(rest, ["enable", "disable"]);
+    const args = parse(rest, ["enable", "disable"], ["events", "description", "url", "keep", "limit"]);
     const id = () => need(args.positional[0], "a webhook id");
     const events = () => flag(args, "events")
         ?.split(",")
@@ -2463,7 +2870,7 @@ async function otelCommand(argv, env, out) {
     product = "otel";
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     const otel = (await client(env)).otel;
-    const args = parse(rest, ["enable", "disable"]);
+    const args = parse(rest, ["enable", "disable"], ["endpoint", "header", "signals"]);
     const id = () => need(args.positional[0], "an export id");
     const signals = () => flag(args, "signals")
         ?.split(",")