withruntime 0.4.0 → 0.5.0

package/dist/cli.js

@@ -1,20 +1,23 @@
 #!/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 { readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveCredential } from "./credentials.js";
+import { connectionStore, resolveCredential } from "./credentials.js";
 import { authenticationCommand, me, named } from "./login.js";
+import { createKey, dailyLimitMicros } from "./keys.js";
 import { Runtime } from "./client.js";
 import { RuntimeError } from "./errors.js";
 import { envFetch } from "./proxy.js";
+import { portForwardCommand, sshCommand } from "./ssh.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
+  sandbox run [--keep] [create options] -- <command>
+                                               A fresh sandbox runs one command, then stops
 
 Account
   login [--agent-name <name>] [--no-browser] [--wait]
@@ -22,9 +25,25 @@ Account
   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
+  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)
+  audit [--action member.] [--limit 50] [--before <next>]
+                                               The account's audit log (owner or admin keys)
   usage                                        Balance, trial time and charges
   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
+  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
+  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
   feedback "<text>" [--kind bug|missing_feature|competitor_gap|migration_blocker|docs|pricing|praise|other]
                    [--detail <text>] [--competitor <name>] [--request-id <req_...>]
@@ -36,10 +55,26 @@ Account
   docs [topic]                                 Print a docs page (start, cli, api, python...)
   mcp                                          Serve MCP on stdio for agents that need it
 
+Connect
+  sandbox ssh <id|name> [-- <command...>]      Log in over SSH; \`runtime sandbox ssh help\` for editors
+  sandbox ssh config [--install]               Make \`ssh <id|name>.runtime\` work (VS Code, JetBrains)
+  sandbox port-forward <id|name> <port|local:remote>...
+                                               Forward local ports to ports in a sandbox
+
+Observability
+  sandbox metrics <id> [--range 1h]            CPU and memory over time (15m 1h 6h 24h 7d 30d)
+  events [--sandbox <id>] [--type <type>]      Lifecycle events, newest first
+  webhooks ls | create <url> [--events a,b] | test <id> | deliveries <id>
+           | update <id> [--url u] [--events a,b] [--enable|--disable]
+           | rotate-secret <id> [--keep <seconds>] | retry <deliveryId> | rm <id>
+                                               Signed lifecycle events POSTed to your URL
+  otel ls | create <endpoint> [--header K=V]... [--signals logs,metrics] | flush <id> | rm <id>
+                                               Events and metrics to an OpenTelemetry endpoint
+
 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
+  image     Custom images from a Dockerfile, any public or private image, or a package list
   volume    Persistent disks to attach to sandboxes
   Each has its own help: \`runtime sandbox help\`, \`runtime image help\`...
 
@@ -48,10 +83,14 @@ Behind a proxy: HTTPS_PROXY and NO_PROXY are read, on Node and Bun alike.
 `;
 const SANDBOX_HELP = `runtime sandbox <command>
 
+  run [--keep] [create options] -- <command>                  A fresh sandbox runs one command, then stops
+  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]
          [--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]]...
+         [--image <name:tag|imageId> | --snapshot <snapshotId>] [--volume <volumeId>:/data[:snapshot]]...
+         [--idle-pause <seconds>] [--no-auto-wake] [--persistent] [--get-or-create]
                                                               Create one; prints its id
   ls [--all] [--label k=v]... [--state running]               List (live ones unless --all)
   get <id>                                                    One sandbox, in full
@@ -68,6 +107,9 @@ const SANDBOX_HELP = `runtime sandbox <command>
   files <id> [path] [--depth 2] [--glob '**/*.py']
   stop <id> | pause <id> | wake <id> | restart <id>
   extend <id> <seconds>                       More time before the lease ends
+  update <id> [--name n] [--label k=v]... [--idle-pause <seconds>] [--auto-wake on|off]
+              [--persistent on|off] [--max-total-cost <usd>|none]
+                                              Change its settings; persistent keeps it running
   snapshot <id> [--name n] [--retention days] Keep its whole machine; prints the snapshot id
   fork <id> [--count 3] [--name n] [--keep-snapshot] [--trial|--paid]
                                               Copies of it as it is now, running; prints their ids
@@ -78,6 +120,8 @@ const SANDBOX_HELP = `runtime sandbox <command>
   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
+  metrics <id> [--range 15m|1h|6h|24h|7d|30d]
+                                              CPU and memory over time, and the latest reading
   desktop <id> start | stop | screenshot [file.png] | open <url> | click <x> <y>
                | type <text> | press <keys> | windows
 
@@ -162,7 +206,11 @@ const COMMANDS = [
     "whoami",
     "usage",
     "limits",
+    "secrets",
+    "keys",
     "referrals",
+    "compare",
+    "switch",
     "ls",
     "feedback",
     "support",
@@ -172,10 +220,18 @@ const COMMANDS = [
     "snapshot",
     "image",
     "volume",
+    "webhooks",
+    "otel",
+    "events",
     "help",
     "version",
 ];
+/** Sandbox commands that once sat at the top level. */
+const SANDBOX_MOVED = ["run", "ssh", "port-forward", "forward"];
 const SANDBOX_VERBS = [
+    "run",
+    "ssh",
+    "port-forward",
     "create",
     "ls",
     "get",
@@ -186,6 +242,7 @@ const SANDBOX_VERBS = [
     "snapshot",
     "fork",
     "extend",
+    "update",
     "exec",
     "spawn",
     "ps",
@@ -201,6 +258,7 @@ const SANDBOX_VERBS = [
     "unshare",
     "network",
     "desktop",
+    "metrics",
 ];
 function need(value, what) {
     if (!value)
@@ -261,6 +319,14 @@ function describe(info) {
         ["funding", info.funding],
         ["region", info.region],
         ["expires", info.expiresAt ?? "-"],
+        ["auto wake", info.autoWake === false ? "off" : "on"],
+        [
+            "idle pause",
+            info.idlePauseSeconds
+                ? `${info.idlePauseSeconds} s${info.idlePauseUnusedOnly ? " while unused" : " idle"}`
+                : "off",
+        ],
+        ["persistent", info.persistent ? "yes" : "no"],
         [
             "labels",
             Object.entries(info.labels ?? {})
@@ -276,7 +342,16 @@ function remote(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 [first, ...remaining] = argv.filter((arg) => arg !== "--json" || (argv.indexOf("--") !== -1 && argv.indexOf(arg) > argv.indexOf("--")));
+    // Sandbox is one product of several, so its commands live under it
+    // (AGENTS.md, 23 September 2026): `runtime sandbox run`, `sandbox ssh` and
+    // `sandbox port-forward`. The old top-level forms were removed, not aliased.
+    if (first && SANDBOX_MOVED.includes(first))
+        throw usage(`\`${me} ${first}\` is now \`${me} sandbox ${first === "forward" ? "port-forward" : first}\`.`);
+    const nested = (first === "sandbox" || first === "sandboxes" || first === "sbx") &&
+        SANDBOX_MOVED.includes(remaining[0] ?? "");
+    const command = nested ? remaining[0] : first;
+    const rest = nested ? remaining.slice(1) : remaining;
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     product = "";
     if (!command) {
@@ -289,7 +364,8 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             ? 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 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
@@ -304,7 +380,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         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)'`);
+            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);
@@ -402,6 +478,60 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         ]), l);
         return 0;
     }
+    if (command === "secrets")
+        return secretsCommand(rest, env, out);
+    if (command === "webhooks" || command === "webhook")
+        return webhooksCommand(rest, env, out);
+    if (command === "otel")
+        return otelCommand(rest, env, out);
+    if (command === "events") {
+        const args = parse(rest);
+        const page = await (await client(env)).events.list({
+            ...(flag(args, "sandbox") ? { resourceId: flag(args, "sandbox") } : {}),
+            ...(flag(args, "type") ? { type: flag(args, "type") } : {}),
+            ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
+        });
+        print(page.data.length
+            ? table(page.data.map((e) => {
+                const subject = (Object.values(e.data)[0] ?? {});
+                return [e.createdAt, e.type, e.resourceId ?? "-", subject.stopReason ?? ""];
+            }))
+            : "No events in the last 14 days.", page);
+        return 0;
+    }
+    if (command === "keys")
+        return keys(rest, env, out);
+    if (command === "account" || command === "accounts")
+        return accountCommand(rest, env, out);
+    if (command === "audit") {
+        const args = parse(rest);
+        const known = new Set(["action", "limit", "before"]);
+        for (const name of args.flags.keys())
+            if (!known.has(name))
+                throw usage(`Unknown option --${name}.`);
+        const page = await (await client(env)).audit.list({
+            ...(flag(args, "action") ? { action: flag(args, "action") } : {}),
+            ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
+            ...(flag(args, "before") ? { before: flag(args, "before") } : {}),
+        });
+        print(page.events.length
+            ? [
+                table([
+                    ["when (UTC)", "action", "who", "from"],
+                    ...page.events.map((event) => [
+                        event.at.slice(0, 19).replace("T", " "),
+                        event.action,
+                        event.actor.kind === "runtime"
+                            ? "Runtime"
+                            : `${event.actor.name ?? event.actor.kind}${event.actor.person ? ` (${event.actor.person})` : ""}`,
+                        event.ip ?? event.via,
+                    ]),
+                ]),
+                ...(page.next ? ["", `Older: ${me} audit --before ${page.next}`] : []),
+            ].join("\n")
+            : "Nothing recorded yet.", page);
+        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 })}`;
@@ -423,6 +553,8 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
         ].join("\n"), r);
         return 0;
     }
+    if (command === "compare" || command === "switch")
+        return switching(command, rest, env, out);
     if (command === "mcp") {
         const { serveMcp } = await import("./mcp.js");
         await serveMcp(env);
@@ -496,6 +628,14 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
             : "Nothing yet. Start with: runtime sandbox create", items);
         return 0;
     }
+    if (command === "ssh") {
+        product = "ssh";
+        return sshCommand(rest, env, out, () => client(env), me);
+    }
+    if (command === "port-forward" || command === "forward") {
+        product = "ssh";
+        return portForwardCommand(rest, out, () => client(env), me);
+    }
     if (command === "sandbox" || command === "sandboxes" || command === "sbx") {
         product = "sandbox";
         return sandbox(rest, env, out);
@@ -506,7 +646,7 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     if (command === "image" || command === "images") {
         product = "image";
-        return image(rest, env, out);
+        return imageCommand(rest, env, out);
     }
     if (command === "volume" || command === "volumes") {
         product = "volume";
@@ -514,6 +654,121 @@ export async function run(argv, env = process.env, out = defaultOut(argv)) {
     }
     throw unknown("command", command, COMMANDS);
 }
+/** Dollars from integer microdollars: cents from a dollar up, and four
+ * places below one, so a few minutes of use does not round to $0.01. */
+function dollars(micros) {
+    const value = BigInt(micros);
+    const sign = value < 0n ? "-" : "";
+    const size = value < 0n ? -value : value;
+    const places = size < 1000000n ? 4 : 2;
+    const unit = 10n ** BigInt(6 - places);
+    const rounded = (size + unit / 2n) / unit;
+    const whole = rounded / 10n ** BigInt(places);
+    const part = (rounded % 10n ** BigInt(places)).toString().padStart(places, "0");
+    return `${sign}$${whole.toLocaleString("en-US")}.${part}`;
+}
+const SWITCH_FROM = {
+    e2b: "e2b",
+    daytona: "daytona",
+    vercel: "vercel",
+    modal: "modal",
+    cloudflare: "cloudflare",
+    fly: "fly",
+    "fly-machines": "fly",
+};
+const RIVAL_NAMES = {
+    e2b: "E2B",
+    daytona: "Daytona",
+    vercel: "Vercel Sandbox",
+    modal: "Modal",
+    cloudflare: "Cloudflare Sandbox",
+    fly: "Fly",
+};
+/** One line on the switching credit: how to claim it, or what it did. */
+function switchingLine(summary, provider) {
+    const cap = dollars(summary.maxMicros);
+    const sw = summary.switch;
+    if (!sw) {
+        if (!summary.eligible || !provider)
+            return undefined;
+        return `Switching from ${RIVAL_NAMES[provider]}? Run \`${me} switch --from ${provider}\` before your first top-up and we match that top-up, up to ${cap}.`;
+    }
+    const from = RIVAL_NAMES[sw.provider];
+    switch (sw.status) {
+        case "pending":
+            return `Your switch from ${from} is recorded: your first top-up is matched, up to ${cap}, once the payment settles.`;
+        case "paid":
+            return `Your switch from ${from} matched your first top-up: ${dollars(sw.creditMicros)} of credit.`;
+        case "superseded":
+            return `Your first top-up was matched by your referral instead, which is never less than the switching credit.`;
+        case "reversed":
+            return `The top-up your switching credit matched was refunded, so the credit was taken back.`;
+        case "refused":
+            return sw.refusedReason === "program_off"
+                ? "The switching credit was paused when your first top-up arrived."
+                : "Your first top-up was not matched. Ask support if you think that is wrong.";
+    }
+}
+async function switching(command, argv, env, out) {
+    const args = parse(argv);
+    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())
+        if (!known.has(name))
+            throw usage(`Unknown option --${name}.`);
+    if (args.positional.length || args.rest)
+        throw usage(`Unexpected ${args.positional[0] ?? "--"}.`);
+    const from = flag(args, "from")?.trim().toLowerCase();
+    const api = (await client(env)).switching;
+    if (command === "switch") {
+        if (!from) {
+            const summary = await api.get();
+            print(switchingLine(summary) ??
+                (summary.eligible
+                    ? `Moving from a rival? Run \`${me} switch --from <provider>\` (${summary.providers.join(", ")}) before your first top-up, and that top-up is matched, up to ${dollars(summary.maxMicros)}.`
+                    : "The switching credit matches a first top-up, and this organization has made one already."), summary);
+            return 0;
+        }
+        const provider = SWITCH_FROM[from];
+        if (!provider || from === "fly-machines")
+            throw unknown("provider", from, Object.keys(RIVAL_NAMES));
+        const summary = await api.record({ provider });
+        print(`Recorded: switching from ${RIVAL_NAMES[provider]}. ${switchingLine(summary) ?? ""}`.trim(), summary);
+        return 0;
+    }
+    if (!from)
+        throw usage(`Name the rival: ${me} compare --from e2b (or daytona, vercel, modal, cloudflare, fly, fly-machines...).`);
+    /* 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");
+    const c = await api.compare({ provider: from, days });
+    const saving = BigInt(c.savingMicros);
+    const percent = c.savingPercent === null ? "" : ` (${Math.abs(c.savingPercent)}%)`;
+    const verdict = saving >= 0n
+        ? `you save ${dollars(saving)}${percent}`
+        : `${c.rival.name} would cost ${dollars(-saving)} less${percent}`;
+    const figures = `${dollars(c.runtimeMicros)} on Runtime; the same sandboxes on ${c.rival.name}: ${dollars(c.rivalMicros)}; ${verdict}`;
+    const month = c.perMonth ? BigInt(c.perMonth.savingMicros) : undefined;
+    const lines = c.basis === "usage"
+        ? [
+            `Your last ${c.window.days} days: ${figures}${month === undefined
+                ? "."
+                : month >= 0n
+                    ? `, about ${dollars(month)} a month.`
+                    : `, about ${dollars(-month)} a month more on Runtime.`}`,
+            `Priced: ${c.usage.sandboxes.toLocaleString("en-US")} sandbox${c.usage.sandboxes === 1 ? "" : "es"}, ${(c.usage.runSeconds / 3600).toLocaleString("en-US", { maximumFractionDigits: 2 })} hours running.${c.usage.unpricedSandboxes ? ` ${c.usage.unpricedSandboxes} left out: ${c.rival.name} publishes no price for their size.` : ""}`,
+        ]
+        : [
+            `No settled sandboxes in your last ${c.window.days} days yet, so this prices an example: ${c.usage.sandboxes.toLocaleString("en-US")} runs of ${(c.usage.runSeconds / c.usage.sandboxes).toLocaleString("en-US")} seconds using ${(c.usage.activeCpuSeconds / c.usage.sandboxes).toLocaleString("en-US")} CPU-seconds each.`,
+            `The example: ${figures}.`,
+        ];
+    lines.push(`${c.rival.name}'s published rates, checked ${new Date(`${c.rival.checked}T12:00:00Z`).toLocaleDateString("en-GB", { day: "numeric", month: "long", year: "numeric", timeZone: "UTC" })}: ${c.rival.rates.join("; ")}. Compute only: storage, network, plan fees and free allowances are left out.`);
+    const line = switchingLine(c.switching, Object.hasOwn(SWITCH_FROM, from) ? SWITCH_FROM[from] : undefined);
+    if (line)
+        lines.push("", line);
+    print(lines.join("\n"), c);
+    return 0;
+}
 async function support(argv, env, out) {
     const args = parse(argv);
     const api = (await client(env)).support;
@@ -639,6 +894,40 @@ async function sandbox(argv, env, out) {
             print(forks.map((f) => f.id).join("\n"), forks.map((f) => f.info));
             return 0;
         }
+        case "update": {
+            const args = parse(rest);
+            const sbx = await get(args.positional[0]);
+            const onOff = (name) => {
+                const value = flag(args, name);
+                if (value === undefined)
+                    return undefined;
+                if (value !== "on" && value !== "off")
+                    throw usage(`--${name} takes on or off.`);
+                return value === "on";
+            };
+            const cost = flag(args, "max-total-cost");
+            if (cost !== undefined && cost !== "none" && !/^\d+(\.\d{1,6})?$/.test(cost))
+                throw usage("--max-total-cost takes dollars, such as 25 or 2.50, or none.");
+            const settings = {
+                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+                ...(integer(args, "idle-pause") !== undefined
+                    ? { idlePauseSeconds: integer(args, "idle-pause") }
+                    : {}),
+                ...(onOff("auto-wake") === undefined ? {} : { autoWake: onOff("auto-wake") }),
+                ...(onOff("persistent") === undefined ? {} : { persistent: onOff("persistent") }),
+                ...(cost === undefined
+                    ? {}
+                    : {
+                        maxTotalCostMicros: cost === "none" ? null : Math.round(Number(cost) * 1e6),
+                    }),
+            };
+            if (!Object.keys(settings).length)
+                throw usage("Say what to change: --name, --label, --idle-pause, --auto-wake, --persistent or --max-total-cost.");
+            await sbx.update(settings);
+            print(describe(sbx.info), sbx.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"));
@@ -792,6 +1081,16 @@ async function sandbox(argv, env, out) {
         }
         case "desktop":
             return desktop(await get(rest[0]), rest.slice(1), out);
+        case "metrics": {
+            const args = parse(rest);
+            const sbx = await get(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.");
+            const m = await sbx.metrics({ range });
+            print(metricsText(m), m);
+            return 0;
+        }
     }
     throw unknown("sandbox command", verb, SANDBOX_VERBS);
 }
@@ -802,6 +1101,109 @@ function attachment(spec) {
         throw usage("--volume takes <volumeId>:/path, or <volumeId>:/path:snapshot for a copy.");
     return { volumeId, path, mode };
 }
+/** A secret's value, from standard input only, so it never sits in shell
+ * history or a process list. Piped: everything, less one trailing newline.
+ * A terminal: one line, not shown. */
+async function readSecret() {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of stdin)
+            chunks.push(chunk);
+        return Buffer.concat(chunks)
+            .toString("utf8")
+            .replace(/\r?\n$/, "");
+    }
+    process.stderr.write("Value (not shown), then Enter: ");
+    stdin.setRawMode(true);
+    stdin.resume();
+    try {
+        return await new Promise((done, fail) => {
+            let value = "";
+            const onData = (chunk) => {
+                for (const char of chunk.toString("utf8")) {
+                    if (char === "\r" || char === "\n") {
+                        stdin.off("data", onData);
+                        process.stderr.write("\n");
+                        return done(value);
+                    }
+                    if (char === "\u0003") {
+                        stdin.off("data", onData);
+                        return fail(usage("Cancelled."));
+                    }
+                    if (char === "\u007f" || char === "\b")
+                        value = value.slice(0, -1);
+                    else
+                        value += char;
+                }
+            };
+            stdin.on("data", onData);
+        });
+    }
+    finally {
+        stdin.setRawMode(false);
+        stdin.pause();
+    }
+}
+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 print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    const rows = (list) => list.length
+        ? table([
+            ["name", "hosts", "header", "placeholder"],
+            ...list.map((secret) => [
+                secret.name,
+                secret.hosts.join(","),
+                secret.header ? `${secret.header}: ${secret.format ?? "{value}"}` : "-",
+                secret.placeholder,
+            ]),
+        ])
+        : "No secrets.";
+    if (verb === "ls" || verb === "list" || verb === undefined) {
+        const list = await (await client(env)).secrets.list();
+        print(rows(list), list);
+        return 0;
+    }
+    if (verb === "set") {
+        const name = need(args.positional[0], "the secret's name, such as OPENAI_API_KEY");
+        const hosts = args.flags.get("host") ?? [];
+        if (!hosts.length)
+            throw usage("Give --host once for each host the value may go to, such as --host api.openai.com.");
+        if (args.flags.has("value"))
+            throw usage('The value is read from standard input, never an argument: printf %s "$KEY" | runtime secrets set NAME --host ...');
+        const value = await read();
+        if (!value)
+            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 saved = await (await client(env)).secrets.set(name, {
+            value,
+            hosts,
+            ...(header ? { header } : {}),
+            ...(format ? { format } : {}),
+        });
+        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.enforced
+                ? []
+                : ["A host is catching up; running sandboxes have it within a minute."]),
+        ].join("\n"), saved);
+        return 0;
+    }
+    if (verb === "rm" || verb === "delete") {
+        const name = need(args.positional[0], "the secret's name");
+        const removed = await (await client(env)).secrets.delete(name);
+        print(`Deleted ${name}.`, removed);
+        return 0;
+    }
+    throw usage("secrets takes set, ls or rm. Run `runtime help`.");
+}
 async function readInput(source) {
     if (source !== "-")
         return readFile(source, "utf8");
@@ -904,6 +1306,141 @@ async function desktop(sbx, argv, out) {
     }
     throw usage(`${me} sandbox desktop <id> start|stop|screenshot|open|click|type|press|windows`);
 }
+const KEYS_HELP = `runtime keys <command>
+
+  create [--name <name>] [--read-only] [--daily-limit <usd>]
+      A new API key, for a CI runner or any place with no browser. Prints a link
+      and a code; an account owner approves the key in the browser, seeing its
+      name, access and limit. The key is printed once, alone on stdout, and
+      lasts until revoked. --json prints it as JSON, still alone on stdout.
+
+  runtime keys create --name ci --daily-limit 25 | gh secret set RUNTIME_API_KEY
+
+List, limit and revoke keys at https://withruntime.com/account/keys.
+`;
+/* `runtime keys create`: a key made from the terminal and approved in the
+   browser. Marc, 23 September 2026; ARCHITECTURE.md section 10, "Keys from the
+   terminal". Only the options the keys page offers. No key can list, create or
+   revoke keys through the API, so `ls` and `revoke` send you to the page. */
+/* `runtime account`: the accounts this machine is connected to, and which one
+   every command uses (ARCHITECTURE.md section 3.9). Each is its own saved
+   connection with its own key; the SDK itself stays key-based. */
+async function accountCommand(argv, env, out) {
+    product = "account";
+    const [verb = "ls", ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    const store = connectionStore(env);
+    if (verb === "add") {
+        const result = await authenticationCommand(["login", "--another-account", ...rest], env);
+        if (result.pending)
+            throw notApprovedYet(result);
+        await nameSaved(env);
+        print(`Connected${"orgId" in result && result.orgId ? ` to ${String(result.orgId)}` : ""}.`, result);
+        return 0;
+    }
+    if (verb === "switch" || verb === "use") {
+        const which = rest.join(" ").trim();
+        if (!which)
+            throw usage(`Name the account: ${me} account switch <name|id>.`);
+        if (env.RUNTIME_API_KEY)
+            throw usage("RUNTIME_API_KEY is set, and it names one account. Unset it to switch.");
+        const chosen = await store.use(which);
+        if (!chosen)
+            throw usage(`No saved connection for "${which}". Run \`${me} account\` to list them, or \`${me} account add\` to connect it.`);
+        print(`Now using ${chosen.orgName ?? chosen.orgId}.`, {
+            orgId: chosen.orgId,
+            orgName: chosen.orgName ?? null,
+        });
+        return 0;
+    }
+    if (verb !== "ls" && verb !== "list")
+        throw unknown("account command", verb, ["ls", "switch", "add"]);
+    await nameSaved(env).catch(() => undefined);
+    const current = await store.read().catch(() => null);
+    const saved = [
+        ...(current ? [{ ...current, current: true }] : []),
+        ...(await store.others()).map((one) => ({ ...one, current: false })),
+    ];
+    const rows = saved.map((one) => ({
+        orgId: one.orgId,
+        orgName: one.orgName ?? null,
+        agentName: one.agentName,
+        current: one.current,
+    }));
+    print(rows.length
+        ? table([
+            ["", "account", "id", "agent"],
+            ...rows.map((row) => [
+                row.current ? "*" : "",
+                row.orgName ?? "-",
+                row.orgId,
+                row.agentName,
+            ]),
+        ])
+        : `Not connected. Run \`${me} login\`.`, { accounts: rows, environmentKey: Boolean(env.RUNTIME_API_KEY) });
+    return 0;
+}
+/** Fill in the saved connection's account name from the API, once. */
+async function nameSaved(env) {
+    if (env.RUNTIME_API_KEY)
+        return;
+    const store = connectionStore(env);
+    const saved = await store.read();
+    if (!saved || saved.orgName)
+        return;
+    const who = await new Runtime({
+        apiKey: saved.key,
+        baseUrl: env.RUNTIME_API_URL,
+        maxRetries: 1,
+    }).me();
+    if (who.orgName && who.orgId === saved.orgId) {
+        const again = await store.read();
+        if (again && again.key === saved.key)
+            await store.save({ ...again, orgName: who.orgName });
+    }
+}
+async function keys(argv, env, out) {
+    product = "keys";
+    const [verb, ...rest] = argv;
+    if (!verb || verb === "help" || verb === "--help" || verb === "-h") {
+        out.write(out.json ? JSON.stringify({ usage: named(KEYS_HELP) }) : named(KEYS_HELP));
+        return 0;
+    }
+    if (verb === "ls" || verb === "list" || verb === "revoke")
+        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 known = new Set(["name", "read-only", "daily-limit"]);
+    for (const name of args.flags.keys())
+        if (!known.has(name))
+            throw usage(`Unknown option --${name}.`);
+    if (args.positional.length || args.rest)
+        throw usage(`Unexpected ${args.positional[0] ?? "--"}.`);
+    const readOnly = has(args, "read-only");
+    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 created = await createKey({
+        name: flag(args, "name") ?? (readOnly ? "Read-only key" : "My API key"),
+        access: readOnly ? "read" : "full",
+        dailyLimitMicros: limit === undefined ? null : dailyLimitMicros(limit),
+    }, env, { notify: out.error });
+    const { confirm, ...key } = created;
+    out.write(out.json ? JSON.stringify(key) : key.key);
+    const terms = [
+        key.access === "read" ? "read only" : "full access",
+        key.access === "read"
+            ? undefined
+            : key.dailyLimitMicros === null
+                ? "no daily limit"
+                : `daily limit $${(Number(BigInt(key.dailyLimitMicros) / 10000n) / 100).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`,
+        "until revoked",
+    ].filter(Boolean);
+    out.error(`Created key "${key.name}" (${terms.join(", ")}). Store it now: it is not shown again, and Runtime keeps only a hash of it.\nIn CI, give it to your jobs as RUNTIME_API_KEY from the secret store.`);
+    await confirm();
+    return 0;
+}
 const SNAPSHOT_HELP = `runtime snapshot <command>
 
   ls [--sandbox <id>] [--name n]              Your snapshots
@@ -960,18 +1497,34 @@ async function snapshot(argv, env, out) {
 }
 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 [<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>]
                         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).
+                        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.
   ls                    Your images
-  get <id>              One image
-  logs <id>             Its build log
-  rm <id>               Delete it
-  Use one: runtime sandbox create --image <id>
+  versions <name>       Every version of a name, newest first
+  get <image>           One image: an id, name, name:tag or name@version
+  logs <image> [--follow]
+                        Its build log
+  tag <image> <tag>     Point a tag of the image's name at this version
+  untag <image> <tag>   Take a tag off
+  rm <image>            Delete that version and its tags
+  registry ls           Registries you keep credentials for
+  registry set <registry> --username <user>
+                        Store credentials to pull private images; the token or
+                        password is read from standard input and never shown again
+  registry set <ecr registry> --access-key-id <id>
+                        Amazon ECR: the secret access key is read from standard input
+  registry rm <registry>
+  Use one: runtime sandbox create --image app:latest
 `;
-async function image(argv, env, out) {
+export async function imageCommand(argv, env, out, 
+/** Tests give the registry secret here; the CLI reads standard input. */
+read = readSecret) {
     const [verb, ...rest] = argv;
     const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
     if (!verb || verb === "help" || verb === "--help") {
@@ -981,30 +1534,72 @@ async function image(argv, env, out) {
     const api = (await client(env)).images;
     switch (verb) {
         case "build": {
-            const args = parse(rest);
+            const args = parse(rest, ["no-cache"]);
             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];
+            const dockerfile = flag(args, "dockerfile") ?? flag(args, "file") ?? flag(args, "f");
+            const folder = args.positional[0];
+            const fromDockerfile = dockerfile !== undefined || folder !== undefined;
+            const sources = [fromDockerfile || undefined, 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.");
+                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, "timeout") ? { timeoutSeconds: integer(args, "timeout") } : {}),
             };
+            // -t app, -t app:v2 -t app:latest: one name, its tags.
+            let name = flag(args, "name");
+            const tags = [];
+            for (const tagged of [...(args.flags.get("t") ?? []), ...(args.flags.get("tag") ?? [])]) {
+                const [repository, tag] = tagged.split(":");
+                if (!repository)
+                    throw usage("-t takes name or name:tag.");
+                if (name !== undefined && name !== repository)
+                    throw usage("Every -t names the same image; give one name and several tags.");
+                name = repository;
+                if (tag)
+                    tags.push(tag);
+            }
+            const start = {
+                ...(flag(args, "start") ? { command: flag(args, "start") } : {}),
+                ...(integer(args, "ready-port") ? { readyPort: integer(args, "ready-port") } : {}),
+                ...(flag(args, "ready-command") ? { readyCommand: flag(args, "ready-command") } : {}),
+                ...(integer(args, "ready-timeout")
+                    ? { readyTimeoutSeconds: integer(args, "ready-timeout") }
+                    : {}),
+            };
             const common = {
-                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+                ...(name ? { name } : {}),
+                ...(tags.length ? { tags } : {}),
                 ...(Object.keys(build).length ? { build } : {}),
+                ...(Object.keys(start).length ? { start } : {}),
+                ...(has(args, "no-cache") ? { cache: false } : {}),
             };
-            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)),
-                    };
+            let input;
+            if (fromDockerfile) {
+                const context = resolve(folder ?? dirname(dockerfile));
+                const file = resolve(context, dockerfile ?? "Dockerfile");
+                const text = await readFile(file, "utf8").catch(() => {
+                    throw usage(`No Dockerfile at ${file}.`);
+                });
+                input = {
+                    ...common,
+                    dockerfile: text,
+                    contextDir: context,
+                    ...(flag(args, "target") ? { target: flag(args, "target") } : {}),
+                    ...(args.flags.get("build-arg") ? { buildArgs: pairs(args, "build-arg") } : {}),
+                };
+                if (!out.json)
+                    out.error(`Sending the build context from ${context}`);
+            }
+            else if (flag(args, "from"))
+                input = { ...common, image: flag(args, "from") };
+            else
+                input = {
+                    ...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) }),
             });
@@ -1012,29 +1607,43 @@ async function image(argv, env, out) {
             return 0;
         }
         case "ls":
-        case "list": {
-            const all = await (await api.list()).toArray(1000);
+        case "list":
+        case "versions": {
+            const name = verb === "versions" ? need(rest[0], "a name") : undefined;
+            const all = await (await api.list(name ? { name } : {})).toArray(1000);
             print(all.length
                 ? table([
-                    ["ID", "NAME", "STATE", "MIB", "CREATED"],
+                    ["ID", "NAME", "VERSION", "TAGS", "STATE", "MIB", "CREATED"],
                     ...all.map((i) => [
                         i.id,
                         i.name ?? "-",
+                        i.version === null || i.version === undefined ? "-" : String(i.version),
+                        i.tags?.length ? i.tags.join(",") : "-",
                         i.state,
                         String(i.sizeMiB ?? "-"),
                         i.createdAt,
                     ]),
                 ])
-                : "No images. Build one: runtime image build --pip pandas", all);
+                : name
+                    ? `No versions of ${name}.`
+                    : "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"));
+            const found = await api.resolve(need(rest[0], "an image"));
             print(JSON.stringify(found, null, 2), found);
             return 0;
         }
         case "logs": {
-            const id = need(rest[0], "an image id");
+            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 = [];
+                const done = await api.followLogs(id, (line) => out.json ? lines.push(line.text) : out.write(line.text));
+                if (out.json)
+                    print("", { lines, state: done.state });
+                return done.state === "failed" ? 1 : 0;
+            }
             let after = 0;
             const lines = [];
             for (;;) {
@@ -1047,76 +1656,69 @@ async function image(argv, env, out) {
             print(lines.join("\n") || "(no log yet)", lines);
             return 0;
         }
+        case "tag":
+        case "untag": {
+            const ref = need(rest[0], "an image");
+            const tag = need(rest[1], "a tag");
+            const found = verb === "tag" ? await api.tag(ref, tag) : await api.untag(ref, tag);
+            print(`${found.name ?? found.id}@${found.version ?? "-"} tags: ${found.tags.join(", ") || "none"}`, found);
+            return 0;
+        }
         case "rm":
         case "delete": {
-            const found = await api.delete(need(rest[0], "an image id"));
+            const found = await api.delete(need(rest[0], "an image"));
             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));
+        case "registry":
+        case "registries": {
+            const [action, ...more] = rest;
+            if (action === "ls" || action === "list" || action === undefined) {
+                const all = await api.registries.list();
+                print(all.length
+                    ? table([
+                        ["REGISTRY", "KIND", "USER", "SINCE"],
+                        ...all.map((r) => [r.registry, r.kind, r.username, r.createdAt]),
+                    ])
+                    : "No registry credentials. Store some: runtime image registry set ghcr.io --username you", all);
+                return 0;
+            }
+            if (action === "set") {
+                const args = parse(more);
+                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)
+                    throw usage("Give --username (or --access-key-id for Amazon ECR).");
+                if (!out.json && process.stdin.isTTY)
+                    out.error(accessKeyId ? "The secret access key:" : "The token or password:");
+                const secret = await read();
+                if (!secret)
+                    throw usage("Nothing on standard input.");
+                const saved = await api.registries.set(accessKeyId
+                    ? { registry, accessKeyId, secretAccessKey: secret }
+                    : { registry, username: flag(args, "username"), password: secret });
+                print(`Stored credentials for ${saved.registry} (${saved.username}).`, saved);
+                return 0;
+            }
+            if (action === "rm" || action === "delete") {
+                const gone = await api.registries.delete(need(more[0], "a registry"));
+                print(gone.deleted ? `Forgot ${gone.registry}.` : `Nothing stored for ${gone.registry}.`, gone);
+                return 0;
+            }
+            throw unknown("registry command", action, ["ls", "set", "rm"]);
         }
-        else
-            await add(absolute);
     }
-    return { dockerfile, files };
+    throw unknown("image command", verb, [
+        "build",
+        "ls",
+        "versions",
+        "get",
+        "logs",
+        "tag",
+        "untag",
+        "rm",
+        "registry",
+    ]);
 }
 const VOLUME_HELP = `runtime volume <command>
 
@@ -1179,7 +1781,15 @@ async function volume(argv, env, out) {
     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"];
+const CREATE_FLAGS = [
+    "trial",
+    "paid",
+    "no-wait",
+    "no-internet",
+    "no-auto-wake",
+    "persistent",
+    "get-or-create",
+];
 /** A create body from the command line's flags. */
 function createInput(args) {
     const rules = ["allow", "deny", "connect"].filter((name) => args.flags.has(name));
@@ -1204,6 +1814,12 @@ function createInput(args) {
         ...(flag(args, "on-timeout")
             ? { onLeaseEnd: flag(args, "on-timeout") }
             : {}),
+        ...(integer(args, "idle-pause") !== undefined
+            ? { idlePauseSeconds: integer(args, "idle-pause") }
+            : {}),
+        ...(has(args, "no-auto-wake") ? { autoWake: false } : {}),
+        ...(has(args, "persistent") ? { persistent: true } : {}),
+        ...(has(args, "get-or-create") ? { getOrCreate: true } : {}),
         ...(has(args, "trial")
             ? { funding: "trial" }
             : has(args, "paid")
@@ -1296,3 +1912,224 @@ if (import.meta.main ||
         process.exitCode = 1;
     });
 }
+// ------------------------------------------------------------------ observability
+/** A sparkline of up to 60 points, oldest first. */
+function spark(values) {
+    const bars = "▁▂▃▄▅▆▇█";
+    const known = values.filter((v) => v !== null);
+    const top = Math.max(1, ...known);
+    const step = Math.max(1, Math.ceil(values.length / 60));
+    const out = [];
+    for (let i = 0; i < values.length; i += step) {
+        const slice = values.slice(i, i + step).filter((v) => v !== null);
+        out.push(slice.length ? bars[Math.min(7, Math.round((Math.max(...slice) / top) * 7))] : " ");
+    }
+    return out.join("");
+}
+const mib = (bytes) => `${Math.round(bytes / 1_048_576).toLocaleString("en-US")} MiB`;
+function metricsText(m) {
+    const cpu = m.points.map((p) => p.cpuPercent);
+    const memory = m.points.map((p) => p.memoryBytes);
+    const peak = Math.max(0, ...m.points.map((p) => p.cpuPeakPercent ?? p.cpuPercent ?? 0));
+    const latest = m.latest;
+    return [
+        table([
+            ["state", m.state],
+            [
+                "cpu now",
+                latest?.cpuPercent == null
+                    ? "no reading in the last 15 minutes"
+                    : `${latest.cpuPercent}% of ${m.vcpu} vCPU (${latest.cpuCores} cores)`,
+            ],
+            ["memory now", latest ? `${mib(latest.memoryBytes)} of ${mib(m.memoryLimitBytes)}` : "-"],
+            [`cpu, ${m.range}`, m.points.length ? `${spark(cpu)}  peak ${peak}%` : "no readings"],
+            [
+                `memory, ${m.range}`,
+                m.points.length
+                    ? `${spark(memory)}  peak ${mib(Math.max(...m.points.map((p) => p.memoryPeakBytes)))}`
+                    : "no readings",
+            ],
+        ]),
+    ].join("\n");
+}
+const WEBHOOK_VERBS = [
+    "ls",
+    "create",
+    "get",
+    "update",
+    "test",
+    "deliveries",
+    "retry",
+    "rotate-secret",
+    "rm",
+];
+async function webhooksCommand(argv, env, out) {
+    const [verb = "ls", ...rest] = argv;
+    product = "webhooks";
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (verb === "help" || verb === "--help") {
+        out.write(HELP.split("\n")
+            .filter((line) => /webhooks|^\s{11}\|/.test(line))
+            .join("\n"));
+        return 0;
+    }
+    const hooks = (await client(env)).webhooks;
+    const args = parse(rest, ["enable", "disable"]);
+    const id = () => need(args.positional[0], "a webhook id");
+    const events = () => flag(args, "events")
+        ?.split(",")
+        .map((e) => e.trim())
+        .filter(Boolean);
+    const row = (h) => [
+        h.id,
+        h.url,
+        h.enabled ? (h.failingSince ? `failing since ${h.failingSince}` : "on") : "off",
+        h.events.join(","),
+    ];
+    switch (verb) {
+        case "ls":
+        case "list": {
+            const page = await hooks.list();
+            print(page.data.length
+                ? table(page.data.map(row))
+                : "No webhooks. Add one: runtime webhooks create <url>", page);
+            return 0;
+        }
+        case "get": {
+            const h = await hooks.get(id());
+            print(table([row(h)]), h);
+            return 0;
+        }
+        case "create":
+        case "add": {
+            const h = await hooks.create({
+                url: need(args.positional[0], "the https URL to send to"),
+                ...(events() ? { events: events() } : {}),
+                ...(flag(args, "description") ? { description: flag(args, "description") } : {}),
+            });
+            print(`${h.id}\nSigning secret (shown once, keep it): ${h.secret}\nVerify deliveries with verifyWebhook from the withruntime SDK.`, h);
+            return 0;
+        }
+        case "update": {
+            const h = await hooks.update(id(), {
+                ...(flag(args, "url") ? { url: flag(args, "url") } : {}),
+                ...(events() ? { events: events() } : {}),
+                ...(has(args, "enable") ? { enabled: true } : {}),
+                ...(has(args, "disable") ? { enabled: false } : {}),
+            });
+            print(table([row(h)]), h);
+            return 0;
+        }
+        case "rotate-secret": {
+            const keep = integer(args, "keep");
+            const h = await hooks.rotateSecret(id(), keep === undefined ? {} : { keepPreviousSeconds: keep });
+            print(`New signing secret (shown once): ${h.secret}${h.previousSecretExpiresAt ? `\nThe old one also signs until ${h.previousSecretExpiresAt}.` : ""}`, h);
+            return 0;
+        }
+        case "test": {
+            const d = await hooks.test(id());
+            print(d.state === "succeeded"
+                ? `Delivered: your endpoint answered ${d.lastStatus} in ${d.lastDurationMs} ms.`
+                : d.state === "pending"
+                    ? "Sent; no answer yet. See it with: runtime webhooks deliveries " + id()
+                    : `Not delivered: ${d.lastError ?? d.state}${d.lastStatus ? ` (HTTP ${d.lastStatus})` : ""}.`, d);
+            return d.state === "failed" ? 1 : 0;
+        }
+        case "deliveries": {
+            const page = await hooks.deliveries(id(), {
+                ...(integer(args, "limit") ? { limit: integer(args, "limit") } : {}),
+            });
+            print(page.data.length
+                ? table(page.data.map((d) => [
+                    d.id,
+                    d.createdAt,
+                    d.eventType,
+                    d.state,
+                    `${d.attempts}/${d.maxAttempts}`,
+                    d.lastStatus ? String(d.lastStatus) : (d.lastError ?? "-"),
+                ]))
+                : "No deliveries yet.", page);
+            return 0;
+        }
+        case "retry": {
+            const d = await hooks.retry(need(args.positional[0], "a delivery id"));
+            print(`Queued ${d.id} to send again.`, d);
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            print("Deleted.", await hooks.delete(id()));
+            return 0;
+        }
+    }
+    throw unknown("webhooks command", verb, WEBHOOK_VERBS);
+}
+const OTEL_VERBS = ["ls", "create", "get", "update", "flush", "rm"];
+async function otelCommand(argv, env, out) {
+    const [verb = "ls", ...rest] = argv;
+    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 id = () => need(args.positional[0], "an export id");
+    const signals = () => flag(args, "signals")
+        ?.split(",")
+        .map((s) => s.trim());
+    const row = (x) => [
+        x.id,
+        x.endpoint,
+        x.enabled ? "on" : "off",
+        x.signals.join(","),
+        x.lastError
+            ? `last error: ${x.lastError}`
+            : x.lastSuccessAt
+                ? `sent ${x.lastSuccessAt}`
+                : "not sent yet",
+    ];
+    switch (verb) {
+        case "ls":
+        case "list": {
+            const page = await otel.list();
+            print(page.data.length
+                ? table(page.data.map(row))
+                : "No exports. Add one: runtime otel create <endpoint>", page);
+            return 0;
+        }
+        case "get": {
+            const x = await otel.get(id());
+            print(table([row(x)]), x);
+            return 0;
+        }
+        case "create":
+        case "add": {
+            const x = await otel.create({
+                endpoint: need(args.positional[0], "the OTLP/HTTP endpoint"),
+                ...(args.flags.has("header") ? { headers: pairs(args, "header") } : {}),
+                ...(signals() ? { signals: signals() } : {}),
+            });
+            print(`${x.id}\nPushing ${x.signals.join(" and ")} to ${x.endpoint} about every 30 seconds.`, x);
+            return 0;
+        }
+        case "update": {
+            const x = await otel.update(id(), {
+                ...(flag(args, "endpoint") ? { endpoint: flag(args, "endpoint") } : {}),
+                ...(args.flags.has("header") ? { headers: pairs(args, "header") } : {}),
+                ...(signals() ? { signals: signals() } : {}),
+                ...(has(args, "enable") ? { enabled: true } : {}),
+                ...(has(args, "disable") ? { enabled: false } : {}),
+            });
+            print(table([row(x)]), x);
+            return 0;
+        }
+        case "flush": {
+            print("Pushing now; `runtime otel get <id>` shows the answer in a few seconds.", await otel.flush(id()));
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            print("Deleted.", await otel.delete(id()));
+            return 0;
+        }
+    }
+    throw unknown("otel command", verb, OTEL_VERBS);
+}