withruntime 0.17.1 → 0.18.0

package/dist/apps-cli.js

@@ -0,0 +1,564 @@
+import { me, named } from "./cli-name.js";
+import { RuntimeError } from "./errors.js";
+import { logStream } from "./terminal.js";
+import { apps, } from "./products/apps.js";
+import { builds, } from "./products/builds.js";
+export const APP_HELP = `runtime apps <command>
+
+  An App serves your web server from an image or a build. Copies start when
+  requests come and stop when they end, between --min-copies and --max-copies.
+  In a private beta: outside it, each command says how to ask to join.
+
+  create [<name>] --vcpu <1-16> --memory <128-65536> --max-copies <1-1000>
+         [--min-copies 0] [--concurrency 100] [--spares 2] [--port 8080]
+         [--health-path /healthz] [--label key=value]...
+                                              Make an App, waiting for its first deploy; prints its id
+  ls [--all]                                  Your Apps: state, live version, copies; --all, deleted too
+  get <app>                                   One App, in full (an id or its name)
+  update <app> [--name <name>] [--vcpu n] [--memory n] [--min-copies n] [--max-copies n]
+         [--concurrency n] [--spares n] [--port n] [--health-path /path] [--label key=value]...
+                                              Change its settings
+  rm <app>                                    Delete it and stop its copies
+  deploy <app> (--image <image> | --build <buildId>) [--env KEY=VALUE]... [--keep-env]
+         [--port 8080] [--health-path /healthz] [--no-wait]
+                                              A new version. Waits until it is live, or says why it
+                                              failed; --no-wait prints the deploy's id at once.
+                                              --image: an image of yours (id, name, name:tag);
+                                              --build: a build that succeeded (runtime builds).
+                                              --env KEY alone sends KEY's value from your environment.
+                                              --keep-env keeps the last deploy's environment, sealed
+  deploys <app> [<deployId>] [--wait]         Each version's deploy: state and address; with an id,
+                                              that one (--wait: until it ends)
+  versions <app>                              Its versions; the live and previous ones keep saved copies
+  copies <app>                                Its copies now: version, region, state
+  rollback <app> [--no-wait]                  Put the previous version live again
+
+Examples
+  runtime apps create web --vcpu 1 --memory 512 --max-copies 3
+  runtime apps deploy web --image web:latest --env NODE_ENV=production
+  runtime apps rollback web
+`;
+export const BUILD_HELP = `runtime builds <command>
+
+  A build turns a commit of a connected repository into a saved server an App
+  deploys. A push to the production branch builds and deploys by itself.
+  In a private beta: outside it, each command says how to ask to join.
+
+  repos connect <owner/name | https URL> --deploy <app name> [--branch main] [--no-previews]
+        [--root <folder>] [--install <command>] [--build <command>] [--start <command>]
+        [--port 8080] [--health-path /healthz] [--build-env KEY=VALUE]... [--name <name>]
+                                              Connect a repository; prints its id. --deploy takes an
+                                              App's name, or function:<name>. --start runs once the
+                                              build is done, with PORT set: the server the App deploys
+  repos ls                                    Connected repositories
+  repos change <repoId> [the options of connect but the repository]
+                                              Change its settings; its id and builds stay
+  repos disconnect <repoId>                   Stop building it; its builds stay
+  repos install                               A link to install Runtime's GitHub App, so a private
+                                              repository builds
+  create <repoId> [--ref main] [--branch <name>] [--name <name>]
+                                              Build a branch, tag or commit now; prints the build's id
+  run <repoId> [--ref main] [--branch <name>] [--name <name>] [--raw]
+                                              The same, then follows its log; exits 0 once it succeeds
+  ls [--repository <repoId>] [--commit <sha>] [--state <state>]...
+                                              Builds, oldest first; --commit: a full sha
+  get <buildId>                               One build: state, commit, step times, what it made
+  cancel <buildId>                            Stop a build that has not ended
+  logs <buildId> [--follow] [--raw]           Its last 200 lines, or every line as it comes until it
+                                              ends; on a terminal control characters show as \\uXXXX
+                                              unless --raw
+
+Examples
+  runtime builds repos connect acme/web --deploy web --start "npm start"
+  runtime builds run <repoId> --ref main
+  runtime builds ls --commit $(git rev-parse HEAD)
+`;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const when = (ms) => (ms == null ? "-" : new Date(ms).toISOString());
+const ENDED = ["succeeded", "failed", "cancelled", "superseded"];
+/** An App's id from its id or its name: a name is looked up among the Apps
+ * not deleted, and must be one App's alone. */
+async function appIdOf(api, target, kit) {
+    if (UUID.test(target))
+        return target;
+    const found = (await api.list({ name: target, state: ["waiting", "live", "failed"] })).data;
+    if (found.length === 1)
+        return found[0].id;
+    throw kit.usage(found.length
+        ? `${found.length} Apps are named ${target}; give one's id (${me} apps ls).`
+        : `No App is named ${target}. Your Apps: ${me} apps ls`);
+}
+/** The flags an App's settings are given with, as the API names them. */
+function settings(args, kit) {
+    const { integer, flag } = kit;
+    const number = (name, field) => integer(args, name) === undefined ? {} : { [field]: integer(args, name) };
+    return {
+        ...number("vcpu", "vcpu"),
+        ...number("memory", "memoryMiB"),
+        ...number("min-copies", "minCopies"),
+        ...number("max-copies", "maxCopies"),
+        ...number("concurrency", "concurrency"),
+        ...number("spares", "spares"),
+        ...number("port", "port"),
+        ...(flag(args, "health-path") === undefined ? {} : { healthPath: flag(args, "health-path") }),
+    };
+}
+const SETTINGS = [
+    "vcpu",
+    "memory",
+    "min-copies",
+    "max-copies",
+    "concurrency",
+    "spares",
+    "port",
+    "health-path",
+    "label",
+];
+/** A deploy that ended badly, said with its own words, hint and last output. */
+function deployFailure(deploy) {
+    if (!deploy.error)
+        return undefined;
+    const last = deploy.error.lastOutput?.trim();
+    return new RuntimeError({
+        code: deploy.error.code,
+        status: 0,
+        message: `Version ${deploy.version} did not go live: ${deploy.error.message}${last ? `\nIts last output:\n${last}` : ""}`,
+        hint: deploy.error.hint,
+        details: { deploy },
+    });
+}
+export async function appsCommand(argv, env, out, client, kit) {
+    const { parse, flag, has, need, pairs, envPairs, table, usage } = kit;
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(APP_HELP), { usage: named(APP_HELP) });
+        return 0;
+    }
+    const api = apps((await client()).transport);
+    const idOf = (target) => appIdOf(api, need(target, "an App's id or name"), kit);
+    switch (verb) {
+        case "create": {
+            const args = parse(rest, [], SETTINGS);
+            if (args.positional.length > 1)
+                throw usage(`Give one name: ${me} apps create web --vcpu 1 --memory 512 --max-copies 2`);
+            const given = settings(args, kit);
+            for (const [option, field] of [
+                ["vcpu", "vcpu"],
+                ["memory", "memoryMiB"],
+                ["max-copies", "maxCopies"],
+            ])
+                if (given[field] === undefined)
+                    throw usage(`Give --${option}: ${me} apps create ${args.positional[0] ?? "web"} --vcpu 1 --memory 512 --max-copies 2`);
+            const input = {
+                ...given,
+                ...(args.positional[0] ? { name: args.positional[0] } : {}),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+            };
+            const app = await api.create(input);
+            if (!out.json)
+                out.error(`Created ${app.name ?? app.id}, waiting for its first version. Deploy one: ${me} apps deploy ${app.name ?? app.id} --image <image>`);
+            print(app.id, app);
+            return 0;
+        }
+        case "ls":
+        case "list": {
+            const args = parse(rest, ["all"], []);
+            const all = await (await api.list({
+                limit: 100,
+                ...(has(args, "all")
+                    ? { state: ["waiting", "live", "failed", "deleting", "deleted"] }
+                    : {}),
+            })).toArray(Infinity);
+            print(all.length
+                ? table([
+                    ["ID", "NAME", "STATE", "LIVE", "COPIES", "SIZE", "CREATED"],
+                    ...all.map((a) => [
+                        a.id,
+                        a.name ?? "-",
+                        a.state,
+                        a.liveVersion === null ? "-" : `v${a.liveVersion}`,
+                        `${a.minCopies}-${a.maxCopies}`,
+                        `${a.vcpu} vCPU, ${a.memoryMiB} MiB`,
+                        when(a.createdAt),
+                    ]),
+                ])
+                : `No Apps. Make one: ${me} apps create web --vcpu 1 --memory 512 --max-copies 2`, all);
+            return 0;
+        }
+        case "get": {
+            const app = await api.get(await idOf(rest[0]));
+            print(JSON.stringify(app, null, 2), app);
+            return 0;
+        }
+        case "update": {
+            const args = parse(rest, [], [...SETTINGS, "name"]);
+            const id = await idOf(args.positional[0]);
+            const change = {
+                ...settings(args, kit),
+                ...(flag(args, "name") === undefined ? {} : { name: flag(args, "name") }),
+                ...(args.flags.has("label") ? { labels: pairs(args, "label") } : {}),
+            };
+            if (!Object.keys(change).length)
+                throw usage(`Give a setting to change, such as ${me} apps update ${args.positional[0]} --max-copies 4`);
+            const app = await api.update(id, change);
+            print(`${app.name ?? app.id} updated.`, app);
+            return 0;
+        }
+        case "rm":
+        case "delete": {
+            const app = await api.delete(await idOf(rest[0]));
+            print(`${app.name ?? app.id} ${app.state}.`, app);
+            return 0;
+        }
+        case "deploy": {
+            const args = parse(rest, ["keep-env", "no-wait"], ["image", "build", "env", "port", "health-path"]);
+            const id = await idOf(args.positional[0]);
+            const image = flag(args, "image");
+            const build = flag(args, "build");
+            if ((image === undefined) === (build === undefined))
+                throw usage(`Give --image <image> to deploy an image of yours, or --build <buildId> for a build that succeeded.`);
+            const port = kit.integer(args, "port");
+            const healthPath = flag(args, "health-path");
+            const wait = !has(args, "no-wait");
+            const input = {
+                ...(image !== undefined ? { image } : { build: build }),
+                ...(args.flags.has("env") ? { env: envPairs(args, env) } : {}),
+                ...(has(args, "keep-env") ? { keepEnv: true } : {}),
+                ...(port === undefined ? {} : { port }),
+                ...(healthPath === undefined ? {} : { healthPath }),
+                wait,
+            };
+            if (wait && !out.json)
+                out.error(`Deploying ${args.positional[0]}...`);
+            const deploy = await api.deploy(id, input, { timeoutMs: 15 * 60_000 });
+            const failed = deployFailure(deploy);
+            if (failed && !out.json)
+                throw failed;
+            print(deploy.state === "live"
+                ? `Version ${deploy.version} is live at ${deploy.url}`
+                : `Version ${deploy.version}: ${deploy.state}. Follow it: ${me} apps deploys ${args.positional[0]} ${deploy.id} --wait`, deploy);
+            return failed ? 1 : 0;
+        }
+        case "deploys": {
+            const args = parse(rest, ["wait"], []);
+            const id = await idOf(args.positional[0]);
+            const deployId = args.positional[1];
+            if (deployId) {
+                const deploy = has(args, "wait")
+                    ? await api.waitDeploy(id, deployId, { timeoutMs: 15 * 60_000 })
+                    : await api.getDeploy(id, deployId);
+                const failed = deployFailure(deploy);
+                if (failed && !out.json)
+                    throw failed;
+                print(JSON.stringify(deploy, null, 2), deploy);
+                return failed ? 1 : 0;
+            }
+            // Newest first; a version's deploy is read once per line, so the list
+            // stops at the last 20.
+            const versions = (await api.versions(id)).sort((a, b) => b.version - a.version).slice(0, 20);
+            const deploys = await Promise.all(versions.map((v) => api.getDeploy(id, v.deploy)));
+            print(deploys.length
+                ? table([
+                    ["VERSION", "DEPLOY", "STATE", "FROM", "ADDRESS"],
+                    ...deploys.map((d, i) => [
+                        `v${d.version}${versions[i].live ? " (live)" : versions[i].previous ? " (previous)" : ""}`,
+                        d.id,
+                        d.state,
+                        versions[i].build ? `build ${versions[i].build}` : "image",
+                        d.url,
+                    ]),
+                ])
+                : `No deploys yet. Deploy one: ${me} apps deploy ${args.positional[0]} --image <image>`, deploys);
+            return 0;
+        }
+        case "versions": {
+            const id = await idOf(rest[0]);
+            const versions = (await api.versions(id)).sort((a, b) => b.version - a.version);
+            print(versions.length
+                ? table([
+                    ["VERSION", "LIVE", "PREVIOUS", "SAVED", "DEPLOY", "BUILD"],
+                    ...versions.map((v) => [
+                        `v${v.version}`,
+                        v.live ? "yes" : "-",
+                        v.previous ? "yes" : "-",
+                        v.saved ? "yes" : "-",
+                        v.deploy,
+                        v.build ?? "-",
+                    ]),
+                ])
+                : "No versions yet.", versions);
+            return 0;
+        }
+        case "copies": {
+            const id = await idOf(rest[0]);
+            const copies = await api.copies(id);
+            print(copies.length
+                ? table([
+                    ["COPY", "VERSION", "REGION", "STATE", "SINCE"],
+                    ...copies.map((c) => [c.id, `v${c.version}`, c.region, c.state, when(c.since)]),
+                ])
+                : "No copies awake. A request starts one.", copies);
+            return 0;
+        }
+        case "rollback": {
+            const args = parse(rest, ["no-wait"], []);
+            const id = await idOf(args.positional[0]);
+            const deploy = await api.rollback(id, {
+                wait: !has(args, "no-wait"),
+                timeoutMs: 15 * 60_000,
+            });
+            const failed = deployFailure(deploy);
+            if (failed && !out.json)
+                throw failed;
+            print(deploy.state === "live"
+                ? `Version ${deploy.version} is live again at ${deploy.url}`
+                : `Rolling back to version ${deploy.version}: ${deploy.state}.`, deploy);
+            return failed ? 1 : 0;
+        }
+    }
+    throw kit.unknown("apps command", verb, [
+        "create",
+        "ls",
+        "get",
+        "update",
+        "rm",
+        "deploy",
+        "deploys",
+        "versions",
+        "copies",
+        "rollback",
+    ]);
+}
+/** A repository as connect takes it: GitHub's owner/name, a github.com
+ * address read as that, or any other https address as plain git. */
+function source(repository) {
+    const github = /^(?:https:\/\/github\.com\/)?([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(repository);
+    return github ? { provider: "github", repository: github[1] } : { provider: "git", repository };
+}
+/** connect's and change's settings. */
+function repositorySettings(args, kit) {
+    const { flag, has, integer, pairs } = kit;
+    const text = (name, field) => flag(args, name) === undefined ? {} : { [field]: flag(args, name) };
+    const deploy = flag(args, "deploy");
+    return {
+        ...(deploy === undefined
+            ? {}
+            : {
+                deploy: (/^(app|function|container):/.test(deploy)
+                    ? deploy
+                    : `app:${deploy}`),
+            }),
+        ...text("branch", "productionBranch"),
+        ...(has(args, "no-previews") ? { previews: false } : {}),
+        ...text("root", "rootDirectory"),
+        ...text("install", "installCommand"),
+        ...text("build", "buildCommand"),
+        ...text("start", "startCommand"),
+        ...(integer(args, "port") === undefined ? {} : { port: integer(args, "port") }),
+        ...text("health-path", "healthPath"),
+        ...(args.flags.has("build-env") ? { buildEnv: pairs(args, "build-env") } : {}),
+        ...text("name", "name"),
+    };
+}
+const REPOSITORY_VALUES = [
+    "deploy",
+    "branch",
+    "root",
+    "install",
+    "build",
+    "start",
+    "port",
+    "health-path",
+    "build-env",
+    "name",
+];
+export async function buildsCommand(argv, out, client, kit) {
+    const { parse, flag, has, need, table, usage } = kit;
+    const [verb, ...rest] = argv;
+    const print = (human, value) => out.write(out.json ? JSON.stringify(value) : human);
+    if (!verb || verb === "help" || verb === "--help") {
+        print(named(BUILD_HELP), { usage: named(BUILD_HELP) });
+        return 0;
+    }
+    const api = builds((await client()).transport);
+    const buildRow = (b) => [
+        b.id,
+        b.state,
+        b.ref,
+        b.commit ? b.commit.slice(0, 12) : "-",
+        when(b.createdAt),
+        b.reason ?? "-",
+    ];
+    /** A build's log, its last lines or followed to its end. */
+    const logs = async (id, follow, raw) => {
+        const [stdout, stderr] = [logStream(process.stdout, raw), logStream(process.stderr, raw)];
+        const write = (line) => (line.stream === "stderr" ? stderr : stdout)(line.text.endsWith("\n") ? line.text : `${line.text}\n`);
+        if (!follow) {
+            const log = await api.logs(id);
+            if (out.json) {
+                out.write(JSON.stringify(log));
+                return 0;
+            }
+            log.lines.forEach(write);
+            if (log.failingStep)
+                out.error(`[${log.state} at ${log.failingStep.name}${log.failingStep.exitCode === null ? "" : `, exit code ${log.failingStep.exitCode}`}]`);
+            else
+                out.error(ENDED.includes(log.state)
+                    ? `[${log.state}${log.reason ? `, ${log.reason}` : ""}]`
+                    : `[${log.state}; follow it: ${me} builds logs ${id} --follow]`);
+            return 0;
+        }
+        // A follow lasts until the build ends: no deadline of the SDK's own.
+        for await (const event of api.logs(id, { follow: true }, { timeoutMs: 0 })) {
+            if (out.json)
+                out.write(JSON.stringify(event));
+            else if (event.type === "line")
+                write(event);
+            else if (event.type === "gap")
+                out.error("[older lines were dropped before they were read; going on from the oldest kept]");
+            if (event.type === "terminal") {
+                if (!out.json) {
+                    out.error(`[${event.state}, ${event.reason}]`);
+                    if (event.failingStep)
+                        out.error(`${event.failingStep.name} failed${event.failingStep.exitCode === null ? "" : ` with exit code ${event.failingStep.exitCode}`}. Its last lines:\n${event.failingStep.lastLines.join("\n")}`);
+                }
+                return event.state === "succeeded" ? 0 : 1;
+            }
+        }
+        return 1;
+    };
+    switch (verb) {
+        case "repos":
+        case "repositories": {
+            const [action, ...more] = rest;
+            switch (action) {
+                case "connect": {
+                    const args = parse(more, ["no-previews"], REPOSITORY_VALUES);
+                    const repository = need(args.positional[0], "the repository, such as acme/web");
+                    const given = repositorySettings(args, kit);
+                    if (!given.deploy)
+                        throw usage(`Give --deploy with the App it deploys: ${me} builds repos connect ${repository} --deploy web`);
+                    const repo = await api.repositories.connect({
+                        ...source(repository),
+                        ...given,
+                    });
+                    if (!out.json)
+                        out.error(`Connected ${repo.repository}: a push to ${repo.productionBranch} builds and deploys ${repo.deploy}. Build now: ${me} builds run ${repo.id}`);
+                    print(repo.id, repo);
+                    return 0;
+                }
+                case "ls":
+                case "list": {
+                    const all = await (await api.repositories.list({ limit: 100 })).toArray(Infinity);
+                    print(all.length
+                        ? table([
+                            ["ID", "REPOSITORY", "BRANCH", "DEPLOYS", "STATE"],
+                            ...all.map((r) => [
+                                r.id,
+                                r.repository,
+                                r.productionBranch,
+                                r.deploy,
+                                r.state,
+                            ]),
+                        ])
+                        : `No repositories. Connect one: ${me} builds repos connect acme/web --deploy web`, all);
+                    return 0;
+                }
+                case "change":
+                case "update": {
+                    const args = parse(more, ["no-previews"], REPOSITORY_VALUES);
+                    const id = need(args.positional[0], "a repository's id");
+                    const change = repositorySettings(args, kit);
+                    if (!Object.keys(change).length)
+                        throw usage(`Give a setting to change, such as --branch main or --start "npm start".`);
+                    const repo = await api.repositories.update(id, change);
+                    print(`${repo.repository} changed.`, repo);
+                    return 0;
+                }
+                case "disconnect":
+                case "rm": {
+                    const repo = await api.repositories.disconnect(need(more[0], "a repository's id"));
+                    print(`${repo.repository} disconnected; its builds stay.`, repo);
+                    return 0;
+                }
+                case "install": {
+                    const link = await api.repositories.installGithub();
+                    print(`Open this within 15 minutes, install the App on the repositories Runtime may read, and confirm the organization:\n${link.url}`, link);
+                    return 0;
+                }
+            }
+            throw kit.unknown("repos command", action ?? "", [
+                "connect",
+                "ls",
+                "change",
+                "disconnect",
+                "install",
+            ]);
+        }
+        case "create":
+        case "run": {
+            const args = parse(rest, verb === "run" ? ["raw"] : [], ["ref", "branch", "name"]);
+            const repositoryId = need(args.positional[0], "a repository's id (runtime builds repos ls)");
+            const build = await api.create({
+                repositoryId,
+                ref: flag(args, "ref") ?? flag(args, "branch") ?? "main",
+                ...(flag(args, "branch") ? { branch: flag(args, "branch") } : {}),
+                ...(flag(args, "name") ? { name: flag(args, "name") } : {}),
+            });
+            if (verb === "create") {
+                if (!out.json)
+                    out.error(`Building ${build.ref}${build.commit ? ` at ${build.commit.slice(0, 12)}` : ""}. Follow it: ${me} builds logs ${build.id} --follow`);
+                print(build.id, build);
+                return 0;
+            }
+            if (!out.json)
+                out.error(`Build ${build.id}, ${build.ref}${build.commit ? ` at ${build.commit.slice(0, 12)}` : ""}:`);
+            else
+                out.write(JSON.stringify(build));
+            return logs(build.id, true, has(args, "raw"));
+        }
+        case "ls":
+        case "list": {
+            const args = parse(rest, [], ["repository", "commit", "state"]);
+            const commit = flag(args, "commit");
+            if (commit !== undefined && !/^([0-9a-f]{40}|[0-9a-f]{64})$/.test(commit))
+                throw usage(`--commit takes a full sha in lower case: ${me} builds ls --commit $(git rev-parse HEAD)`);
+            const states = args.flags.get("state");
+            const all = await (await api.list({
+                limit: 100,
+                ...(flag(args, "repository") ? { repositoryId: flag(args, "repository") } : {}),
+                ...(commit ? { commit } : {}),
+                ...(states ? { state: states } : {}),
+            })).toArray(Infinity);
+            print(all.length
+                ? table([["ID", "STATE", "REF", "COMMIT", "CREATED", "REASON"], ...all.map(buildRow)])
+                : "No builds.", all);
+            return 0;
+        }
+        case "get": {
+            const build = await api.get(need(rest[0], "a build's id"));
+            print(JSON.stringify(build, null, 2), build);
+            return 0;
+        }
+        case "cancel": {
+            const build = await api.cancel(need(rest[0], "a build's id"));
+            print(`${build.id} ${build.state}.`, build);
+            return 0;
+        }
+        case "logs": {
+            const args = parse(rest, ["f", "follow", "raw"], []);
+            const id = need(args.positional[0], "a build's id");
+            return logs(id, has(args, "f") || has(args, "follow"), has(args, "raw"));
+        }
+    }
+    throw kit.unknown("builds command", verb, [
+        "repos",
+        "create",
+        "run",
+        "ls",
+        "get",
+        "cancel",
+        "logs",
+    ]);
+}

package/dist/billing-cli.d.ts

@@ -1,5 +1,5 @@
 import type { Runtime } from "./client.js";
-import type { claimWalletAccount, openWalletAccount } from "./wallet.js";
+import type { claimWalletAccount, openWalletAccount, rekeyWalletAccount } from "./wallet.js";
 type Out = {
     json: boolean;
     write: (text: string) => void;
@@ -9,11 +9,13 @@ type Args = {
     positional: string[];
     flags: Map<string, string[]>;
 };
-export declare const BILLING_HELP = "runtime billing <command>\n\n  topup <usd> [--wait]      Buy credit with stablecoins (USDC on Base, Solana or Tempo).\n                            Prints an address per network and the exact amount to send.\n                            Send exactly that, from any wallet, before the time shown.\n                            --wait keeps checking until the credit lands.\n  status <id> [--wait]      Whether a top-up's payment has arrived\n\n  auto-top-up               Show auto top-up: the card is charged when credit runs low\n  auto-top-up on [--below <usd>] [--amount <usd>] [--monthly <usd>]\n                            Charge <amount> plus tax when credit falls below <below>,\n                            at most <monthly> a month: $10, $20 and $500 unless given,\n                            or as last set. At least $10, $20 and $100. 5% more as\n                            credit each time, and 200 sandboxes at once while on.\n                            A person saves the card at\n                            https://withruntime.com/account/billing\n  auto-top-up off           Turn it off. Running sandboxes are never stopped.\n\n  No account yet? An agent can open one with a wallet alone:\n  topup <usd> --new-account --accept-terms [--wait]\n                            Opens an account and its first top-up. Prints a claim code,\n                            shown once. --wait saves the key here once the money lands.\n  claim <code> [--wait]     Exchange a paid account's claim code for its key, saved here\n\n  $10 to $10,000 a top-up; $500 in an account's first week. By card:\n  https://withruntime.com/account/billing\n";
+export declare const BILLING_HELP = "runtime billing <command>\n\n  topup <usd> [--wait]      Buy credit with stablecoins (USDC on Base, Solana or Tempo).\n                            Prints an address per network and the exact amount to send.\n                            Send exactly that, from any wallet, before the time shown.\n                            --wait keeps checking until the credit lands.\n  status <id> [--wait]      Whether a top-up's payment has arrived\n\n  auto-top-up               Show auto top-up: the card is charged when credit runs low\n  auto-top-up on [--below <usd>] [--amount <usd>] [--monthly <usd>]\n                            Charge <amount> plus tax when credit falls below <below>,\n                            at most <monthly> a month: $10, $20 and $500 unless given,\n                            or as last set. At least $10, $20 and $100. 5% more as\n                            credit each time, and 200 sandboxes at once while on.\n                            A person saves the card at\n                            https://withruntime.com/account/billing\n  auto-top-up off           Turn it off. Running sandboxes are never stopped.\n\n  No account yet? An agent can open one with a wallet alone:\n  topup <usd> --new-account --accept-terms [--wait]\n                            Opens an account and its first top-up. Prints a claim code,\n                            shown once. --wait saves the key here once the money lands.\n  claim <code> [--wait]     Exchange a paid account's claim code for its key, saved here\n  claim <code> --new-key    Lost the key? Replace it with the claim code. The new key is\n                            saved here; every other key stops working.\n\n  $10 to $10,000 a top-up; $500 in an account's first week. By card:\n  https://withruntime.com/account/billing\n";
 /** Wallet-account commands need no key, and the claim saves the one they get. */
 export type WalletDeps = {
     open: typeof openWalletAccount;
     claim: typeof claimWalletAccount;
+    /** Replaces a lost key with the claim code. */
+    rekey: typeof rekeyWalletAccount;
     /** Saves a claimed key as this machine's connection, as `login --with-key` does. */
     save: (key: string, orgId: string) => Promise<void>;
 };

package/dist/billing-cli.js

@@ -23,6 +23,8 @@ export const BILLING_HELP = `runtime billing <command>
                             Opens an account and its first top-up. Prints a claim code,
                             shown once. --wait saves the key here once the money lands.
   claim <code> [--wait]     Exchange a paid account's claim code for its key, saved here
+  claim <code> --new-key    Lost the key? Replace it with the claim code. The new key is
+                            saved here; every other key stops working.
 
   $10 to $10,000 a top-up; $500 in an account's first week. By card:
   https://withruntime.com/account/billing
@@ -53,7 +55,15 @@ function describe(topup) {
     lines.push("", ...(topup.payBy ? [`Send before ${topup.payBy}.`] : []), "A different amount, token or network cannot be matched or returned automatically.", `The credit lands a few minutes after the transfer: \`${me} billing status ${topup.purchaseId}\`.`);
     return lines.join("\n");
 }
-const FLAGS = new Set(["wait", "new-account", "accept-terms", "below", "amount", "monthly"]);
+const FLAGS = new Set([
+    "wait",
+    "new-account",
+    "accept-terms",
+    "below",
+    "amount",
+    "monthly",
+    "new-key",
+]);
 export async function billingCommand(argv, args, out, client, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), wallet) {
     const [verb, value] = args.positional;
     const has = (name) => args.flags.get(name)?.at(-1) === "true";
@@ -68,6 +78,11 @@ export async function billingCommand(argv, args, out, client, sleep = (ms) => ne
     if ((verb === "topup" && has("new-account")) || verb === "claim") {
         if (!wallet)
             throw usage("Wallet accounts are not available here.");
+        if (has("new-key")) {
+            if (verb !== "claim")
+                throw usage("--new-key is for `billing claim <code> --new-key`.");
+            return rekeyCommand(value, out, wallet);
+        }
         return walletCommand(verb, value, has("accept-terms"), wait, out, sleep, wallet);
     }
     if (verb === "auto-top-up")
@@ -177,6 +192,17 @@ function dollarsOf(value) {
         throw usage("Say how many dollars of credit to buy, such as `billing topup 20`.");
     return usd;
 }
+/** `claim <code> --new-key`: the key was lost; the claim code makes a new one. */
+async function rekeyCommand(code, out, wallet) {
+    if (!code)
+        throw usage("Give the claim code.");
+    const replaced = await wallet.rekey(code);
+    await wallet.save(replaced.apiKey, replaced.orgId);
+    out.write(out.json
+        ? JSON.stringify({ status: "replaced", orgId: replaced.orgId, connected: true })
+        : "Replaced. This machine is connected with the new key, saved and not shown. Every other key of this account no longer works.");
+    return 0;
+}
 /** `topup <usd> --new-account` and `claim <code>`: an account with no key. */
 async function walletCommand(verb, value, acceptTerms, wait, out, sleep, wallet) {
     const me = named("runtime");

package/dist/cli-words.js

@@ -1,3 +1,4 @@
+import { me } from "./cli-name.js";
 import { RuntimeError } from "./errors.js";
 import { cliWords } from "./product-renames.js";
 /* What the CLI says in its own words where the API's would mislead: the
@@ -48,6 +49,15 @@ function issueWords(path, message) {
  * a hint that names the options rather than the request's fields. Anything
  * else is left as the API said it. */
 export function cliRefusal(error) {
+    // A beta's refusal names the support tool an agent calls; here, the command.
+    if (error.code === "product_in_beta") {
+        const product = typeof error.details?.product === "string" ? error.details.product : "";
+        const open = (error.hint ?? "").replace(/;?\s*ask Runtime support \(runtime_support\) to join it\.?$/, ".");
+        return {
+            message: error.message,
+            hint: `${open ? `${open} ` : ""}Ask to join: ${me} support "Please add us to the ${product || "product"} beta"`,
+        };
+    }
     const issues = error.details?.issues;
     if (error.code === "invalid_request" && Array.isArray(issues) && issues.length) {
         const lines = issues