@tonbo/cli 0.22.0 → 0.23.0

package/README.md

@@ -26,7 +26,7 @@ The login file, `login.json`, and the device id it is tied to are shared with [`
 
 ## Commands and the Management API
 
-Every command other than `login` and `logout` is named by one operation of the [Management API](../../contracts/management/openapi-v1.yaml) through its `x-tonbo-cli` and calls that operation, plus reads of the same resource (a `--wait`, the Machine a `name_taken` refusal names, the activations `machine show` reads for the last end, or the Volume a `machine create` or `update --volume` names, read for its id and region); `tonbo machine logs`, once it ships, is the named Streams exception, reading the stream at the Machine's `logs.url`. `tonbo volume move` is the one command that sends another command's operation: it reads the Volume and both Machines and sends the target's `updateMachine` with `move_from` (the `machine create --move-from` of an existing Machine, docs/design/machines-volume-move.md). Apart from it, the command set and the operations tagged with a command are the same set, which `test/commands.test.ts` checks in both directions. The CLI resolves each request from the operation table of the internal package [`@tonbo/cli-core`](../../packages/tonbo-cli-core) (`src/generated/contracts.ts`, which `pnpm --filter @tonbo/cli-core generate:contracts` derives from the contract). `login`, `logout`, `account list` and `account use` are the named exception: they obtain, choose among and discard what the other commands present as their Bearer credential. What a command may do is what your role in the account it acts in allows; the CLI never decides it.
+Every command other than `login` and `logout` is named by one operation of the [Management API](../../contracts/management/openapi-v1.yaml) through its `x-tonbo-cli` and calls that operation, plus reads of the same resource (a `--wait`, the Machine a `name_taken` refusal names, the activations `machine show` reads for the last end, the Volume a `machine create` or `update --volume` names, read for its id and region, or the Volume list `machine show` and `machine delete` read for the name of the Machine's Volume); `tonbo machine logs`, once it ships, is the named Streams exception, reading the stream at the Machine's `logs.url`. `tonbo volume move` is the one command that sends another command's operation: it reads the Volume and both Machines and sends the target's `updateMachine` with `move_from` (the `machine create --move-from` of an existing Machine, docs/design/machines-volume-move.md). Apart from it, the command set and the operations tagged with a command are the same set, which `test/commands.test.ts` checks in both directions. The CLI resolves each request from the operation table of the internal package [`@tonbo/cli-core`](../../packages/tonbo-cli-core) (`src/generated/contracts.ts`, which `pnpm --filter @tonbo/cli-core generate:contracts` derives from the contract). `login`, `logout`, `account list` and `account use` are the named exception: they obtain, choose among and discard what the other commands present as their Bearer credential. What a command may do is what your role in the account it acts in allows; the CLI never decides it.
 
 The help lives with the commands: [`src/app.ts`](src/app.ts) defines each command, its arguments and flags with their one-line descriptions, and [`src/help.ts`](src/help.ts) holds the long help, each flag's default, the examples, the shared rules and the environment. [`commands.json`](commands.json) is all of it as `--help` prints it, which the docs' CLI reference renders; `test/commands.test.ts` holds it to the program, and holds every runnable command to its details and example and the environment list to the variables the code reads, so after changing a command run `pnpm --filter @tonbo/cli commands`.
 

package/dist/bin/tonbo.js

@@ -673,7 +673,9 @@ var managementOperations = {
     "pathParams": [
       "name"
     ],
-    "query": [],
+    "query": [
+      "delete_volume"
+    ],
     "idempotencyKey": false,
     "cli": "tonbo machine delete"
   },
@@ -687,6 +689,16 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo machine sleep"
   },
+  "rebuildMachine": {
+    "method": "POST",
+    "path": "/machines/{name}/rebuild",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo machine rebuild"
+  },
   "wakeMachine": {
     "method": "POST",
     "path": "/machines/{name}/wake",
@@ -1941,6 +1953,10 @@ var machineTimings = {
   "wakeHoldSeconds": 25,
   "earlyReclaimSeconds": 120
 };
+var machineRebuildWarning = [
+  "**Rebuild deletes changes outside /home, /workspace and /root.**",
+  "Rebuild moves this Machine to the image `<image>`. Files in /home, /workspace and /root are kept. Everything else you changed on this Machine's disk is deleted and cannot be recovered: installed packages, files you edited in /etc, global npm or pip packages, and anything in /usr, /opt or /var. To keep those changes, add them to the image's Dockerfile. The Machine sleeps now and starts on the new image at its next wake."
+];
 var machineSecretLimits = {
   "perMachine": 64,
   "valueMaxBytes": 65536,
@@ -2483,6 +2499,36 @@ var ManagementApi = class {
     const answer = await this.request("updateMachine", key, { params: { name }, body: withoutUndefined(change), ifMatch: etag });
     return { machine: answer.data, volumeMove: answer.volume_move ?? null };
   }
+  /** A Rebuild (machine-v2.json `rebuild`): `POST /machines/{name}/rebuild`
+   * with `image`, or the Machine's own reference resolved again without it.
+   * A 202 (`waiting_for_sleep`) carries the `Retry-After` to read the Machine
+   * again after; the request is then sent again once it is asleep. With
+   * `etag`, only the Machine that ETag names is rebuilt
+   * (machine-v2.json `etag.if_match.rebuild` is optional). */
+  async rebuildMachine(key, name, request, etag) {
+    const headers = { retryAfter: null };
+    const answer = await this.request("rebuildMachine", key, { params: { name }, body: withoutUndefined(request), ...etag ? { ifMatch: etag } : {} }, (response) => {
+      headers.retryAfter = response.headers.get("retry-after");
+    });
+    return {
+      machine: answer.data,
+      rebuild: answer.rebuild,
+      retryAfterSeconds: retryAfterSeconds(headers.retryAfter)
+    };
+  }
+  /** An update with `rebuild: true` and `image`, which answers as
+   * rebuildMachine does (machine-v2.json `rebuild.answers`). */
+  async updateMachineRebuild(key, name, etag, change) {
+    const headers = { retryAfter: null };
+    const answer = await this.request("updateMachine", key, { params: { name }, body: withoutUndefined({ ...change, rebuild: true }), ifMatch: etag }, (response) => {
+      headers.retryAfter = response.headers.get("retry-after");
+    });
+    return {
+      machine: answer.data,
+      rebuild: answer.rebuild,
+      retryAfterSeconds: retryAfterSeconds(headers.retryAfter)
+    };
+  }
   /** With `etag`, only the Machine that ETag names, at that revision, is put
    * to sleep (machine-v2.json `etag.if_match.sleep` is optional). A 202
    * carries the `Retry-After` to read the Machine again after
@@ -2511,14 +2557,25 @@ var ManagementApi = class {
    * says whether a name was released (`managed`: its create never reached its
    * region) or a device was forgotten (`byoc`: its region held no row). With
    * `etag`, only the Machine that ETag names is deleted
-   * (machine-v2.json `etag.if_match.delete` is optional). */
-  async deleteMachine(key, name, etag) {
+   * (machine-v2.json `etag.if_match.delete` is optional). `deleteVolume`
+   * decides the Volume a managed Machine holds (machine-v2.json
+   * `delete_volume`); without it the server's default applies, and a 202
+   * says in `volume` what became of it. */
+  async deleteMachine(key, name, etag, deleteVolume) {
     const headers = { kind: null };
-    const answer = await this.request("deleteMachine", key, { params: { name }, ...etag ? { ifMatch: etag } : {} }, (response) => {
+    const answer = await this.request("deleteMachine", key, {
+      params: { name },
+      query: { delete_volume: deleteVolume === void 0 ? void 0 : String(deleteVolume) },
+      ...etag ? { ifMatch: etag } : {}
+    }, (response) => {
       headers.kind = response.headers.get("x-tonbo-machine-kind");
     });
     if (answer?.data)
-      return { machine: answer.data, kind: answer.data.kind };
+      return {
+        machine: answer.data,
+        kind: answer.data.kind,
+        ...answer.volume === void 0 ? {} : { volume: answer.volume }
+      };
     return { machine: null, kind: headers.kind === "byoc" ? "byoc" : "managed" };
   }
   /** One page of a managed Machine's activations, newest first; the cursor
@@ -5777,12 +5834,13 @@ var MACHINE_ERROR_HINTS = {
   machine_kind_mismatch: "That Machine is one of your computers: `tonbo machine show` and `tonbo machine delete` serve it, and nothing else does.",
   volumes_not_offered: "Volumes are not offered to this account in the Machine's region yet; nothing was created or changed.",
   root_mode_not_offered: "A Volume as the Machine's whole disk is not offered to this account yet; nothing was created or changed. Mount it at a path instead: --volume <name>:<path>.",
-  rebuild_required: "This Machine's Volume is its whole disk, so its image changes only by Rebuild, which keeps /home, /workspace and /root and deletes every other change on the disk. Rebuild is not available yet: keep the image, or create a new Machine with the new image and a new Volume.",
-  volume_mode_change: "The Volume cannot move between being the Machine's whole disk and being mounted at a path; nothing was changed. Bind a new Volume in the mode you want.",
+  rebuild_required: "This Machine's Volume is its whole disk, so its image changes only by Rebuild; nothing was changed. Once you have read what Rebuild deletes, run `tonbo machine rebuild <name> --image <reference>`, or the same update with --rebuild.",
+  volume_not_whole_disk: "This Machine's Volume is mounted at a path, or it has none, so it needs no Rebuild; nothing was changed. Change its image with `tonbo machine update <name> --image <reference>`.",
+  volume_mode_change: "A Machine's whole disk is never mounted at a path, and a Volume mounted at a path becomes a whole disk only on its own Machine; nothing was changed.",
   volume_attached: "The Machine the message names is awake with the Volume attached; nothing was changed. Put it to sleep with `tonbo machine sleep <machine>`, then run the command again.",
   volume_holder_changed: "The Volume is not on the Machine you named; nothing was changed. `tonbo volume show <volume>` says which Machine has it: name that one, or use `tonbo volume move`.",
   volume_image_mismatch: "The Volume is a Machine's whole disk, made against one image; it moves only to a Machine on that same image. Nothing was changed.",
-  volume_rebuild_pending: "The Volume's Rebuild has not finished; move it once it has. Nothing was changed.",
+  volume_rebuild_pending: "The Volume's Rebuild is recorded and applies at its Machine's next wake: wake that Machine once (`tonbo machine wake <machine>`), then move the Volume. Nothing was changed.",
   secret_env_conflict: "Use another secret key or remove the non-secret env variable with that name.",
   secret_limit: "Reduce the number or byte size of this Machine's secrets.",
   wake_unavailable: "The wake was refused for now; nothing woke. Wake it again after a while; `tonbo machine show` says why it is blocked."
@@ -5902,7 +5960,8 @@ var MACHINE_WAKE_BLOCKED_HINTS = {
   capacity: "No host had room for its shape: Tonbo is adding a host, <minutes>, and the next request after that wakes it.",
   region_closed: "Machines are closed in its region for now; the next request after they reopen wakes it.",
   budget_slowdown: "Its budget is close to running out, and this wake would pass the budget's slow-down rate: sleep another Machine of the budget, or lower this one's shape, then wake it again. Machines already awake keep running.",
-  budget_exhausted: "Its budget is used up for the month: it wakes after the budget resets, or once a person raises it in the console."
+  budget_exhausted: "Its budget is used up for the month: it wakes after the budget resets, or once a person raises it in the console.",
+  root_image_mismatch: "Its disk was made over another image than the Machine's: run `tonbo machine rebuild <name>` to move the disk to the Machine's image (Rebuild deletes changes outside /home, /workspace and /root)."
 };
 var MACHINE_ACCOUNT_EGRESS_BLOCKED_HINT = "If this is the free egress cap: 10 GiB a month without purchased credit; buy credit at <billing> to lift it.";
 function minutesUntil(retryAt, now = Date.now()) {
@@ -5975,7 +6034,7 @@ function imageFailureFields(machine) {
     ...next ? [["Next step", next]] : []
   ];
 }
-function machineFields(machine, billing, etag = null, lastEnd = null) {
+function machineFields(machine, billing, etag = null, lastEnd = null, volumeName2 = null) {
   return fields([
     ["Name", machine.name],
     ["ID", machine.id],
@@ -5998,7 +6057,7 @@ function machineFields(machine, billing, etag = null, lastEnd = null) {
     ["SSH", `${machine.hostnames.ssh} (tonbo ssh ${machine.name})`],
     ["Env", Object.keys(machine.env).sort().join(", ") || "none"],
     ["Stop grace", `${machine.stop_grace_seconds} s`],
-    ["Volume", volumeText(machine)],
+    ["Volume", volumeText(machine, volumeName2)],
     ...deleteFields(machine),
     ["Database", machine.database ? `${machine.database.name} (${machine.database.url})` : "none"],
     ["Logs", machine.logs.url],
@@ -6043,13 +6102,28 @@ function deleteFields(machine) {
     ]
   ];
 }
-function volumeText(machine) {
+function volumeText(machine, name = null) {
   const binding = machine.volumes?.[0];
   if (!binding) return "none";
-  return binding.path === void 0 ? `${binding.volume} (whole disk)` : `${binding.volume} at ${binding.path}`;
+  if (name === null)
+    return binding.path === void 0 ? `${binding.volume} (whole disk)` : `${binding.volume} at ${binding.path}`;
+  return binding.path === void 0 ? `${name} (whole disk; id ${binding.volume})` : `${name} at ${binding.path} (id ${binding.volume})`;
 }
-function machineText(machine, billing, etag = null, lastEnd = null) {
-  return [machineFields(machine, billing, etag, lastEnd), ...privatePortLines(machine)].join("\n");
+async function volumeName(deps, key, machine) {
+  const id = machine.volumes?.[0]?.volume;
+  if (id === void 0) return null;
+  try {
+    return (await deps.api.listVolumes(key)).data.find((volume) => volume.id === id)?.name ?? null;
+  } catch (error) {
+    if (!(error instanceof HttpError || error instanceof AccessTokenError)) throw error;
+    return null;
+  }
+}
+function machineText(machine, billing, etag = null, lastEnd = null, volume = null) {
+  return [
+    machineFields(machine, billing, etag, lastEnd, volume),
+    ...privatePortLines(machine)
+  ].join("\n");
 }
 function keyStateText(machine) {
   const state = machine.byoc.key_state;
@@ -6074,8 +6148,8 @@ function deviceFields(machine) {
     ["Updated", machine.updated_at]
   ]);
 }
-function anyMachineText(machine, billing, etag = null, lastEnd = null) {
-  return machine.kind === "byoc" ? deviceFields(machine) : machineText(machine, billing, etag, lastEnd);
+function anyMachineText(machine, billing, etag = null, lastEnd = null, volume = null) {
+  return machine.kind === "byoc" ? deviceFields(machine) : machineText(machine, billing, etag, lastEnd, volume);
 }
 function parsePorts(specs) {
   const accesses = machinePortAccess;
@@ -6444,11 +6518,15 @@ async function machineShowCommand(deps, name, options = {}) {
       ...processes.running.map((line) => `Background process: ${line}`),
       ...processes.last ? [`Last background process: ${processes.last}`] : []
     ] : [];
+    const volume = options.json || machine.kind === "byoc" ? null : await volumeName(deps, key, machine);
     print(
       deps,
       options.json,
       machine,
-      [anyMachineText(machine, await billingUrl(deps), etag, lastEnd), ...processLines].join("\n")
+      [
+        anyMachineText(machine, await billingUrl(deps), etag, lastEnd, volume),
+        ...processLines
+      ].join("\n")
     );
   });
 }
@@ -6532,6 +6610,8 @@ function appliesText(name, change) {
 }
 async function machineUpdateCommand(deps, name, command, options = {}) {
   await machineCommand(async () => {
+    if (options.rebuild && options.image === void 0)
+      throw new Error("--rebuild needs --image: it moves the Machine's whole disk to that image.");
     if (command.length && options.imageCommand)
       throw new Error("Give a command or --image-command, not both.");
     if (options.clearPorts && (options.port?.length || options.defaultPort !== void 0))
@@ -6576,7 +6656,27 @@ async function machineUpdateCommand(deps, name, command, options = {}) {
     if (options.discardSnapshot) change.discard_snapshot = true;
     if (Object.values(change).every((value) => value === void 0))
       throw new Error("Nothing to change: pass at least one option or a command.");
-    const machine = await deps.api.updateMachine(key, name, etag, change);
+    const rebuild = () => rebuildUntilDone(
+      deps,
+      key,
+      name,
+      DEFAULT_WAIT_SECONDS,
+      () => deps.api.updateMachineRebuild(key, name, etag, change)
+    );
+    let rebuilt = options.rebuild ? await rebuild() : null;
+    let machine = rebuilt?.machine;
+    if (!machine)
+      try {
+        machine = await deps.api.updateMachine(key, name, etag, change);
+      } catch (error) {
+        if (!(error instanceof HttpError && error.code === "rebuild_required" && deps.interactive()))
+          throw error;
+        const question = `${rebuildWarning(options.image ?? current.image.reference)}
+This Machine's Volume is its whole disk, so its image changes only by Rebuild. Type the Machine's name to rebuild it with this change:`;
+        if (await deps.ask(question) !== name) throw new Error("Cancelled; nothing was changed.");
+        rebuilt = await rebuild();
+        machine = rebuilt.machine;
+      }
     specWarnings(deps, machine.ports, Object.keys(setEnv));
     print(
       deps,
@@ -6584,12 +6684,80 @@ async function machineUpdateCommand(deps, name, command, options = {}) {
       machine,
       [
         `Updated Machine ${machine.name} to revision ${machine.revision}.`,
-        ...appliesText(machine.name, change),
+        ...rebuilt ? [rebuiltText(machine.name, rebuilt.rebuild)] : appliesText(machine.name, change),
         machineText(machine, await billingUrl(deps))
       ].join("\n")
     );
   });
 }
+function rebuildWarning(image) {
+  return machineRebuildWarning.map((paragraph) => paragraph.replaceAll("**", "").replaceAll("<image>", image)).join("\n");
+}
+function rebuiltText(name, answer) {
+  const { reference, digest } = answer.image;
+  const image = digest === null ? reference : `${reference} (${digest})`;
+  if (answer.state === "not_needed")
+    return `Machine ${name}'s disk was never used, so it moves to ${image} with no Rebuild.`;
+  return `Machine ${name} rebuilds onto ${image} at its next wake; files in /home, /workspace and /root are kept.`;
+}
+async function rebuildUntilDone(deps, key, name, timeout, send) {
+  const now = deps.now ?? Date.now;
+  const start = now();
+  for (; ; ) {
+    const answer = await send();
+    if (answer.rebuild.state !== "waiting_for_sleep") return answer;
+    deps.notice(
+      `Machine ${name} is awake with its disk attached, so it is going to sleep first; the Rebuild is sent again once it is asleep.`
+    );
+    const { machine: asleep } = await waitForMachine(
+      deps,
+      key,
+      name,
+      answer.retryAfterSeconds ?? sleepPollAfterSeconds,
+      sleepPollAfterSeconds,
+      timeout - (now() - start) / 1e3,
+      (read) => read.status.power === "asleep" || read.state !== "active"
+    );
+    if (!asleep)
+      throw new Error(
+        `Machine ${name} is not asleep after ${Math.round((now() - start) / 1e3)} s, so nothing was rebuilt; run the command again once it sleeps. \`tonbo machine show ${name}\` says what keeps it awake.`
+      );
+    if (asleep.status.power !== "asleep")
+      throw new Error(`Machine ${name} is ${asleep.state}; nothing was rebuilt.`);
+  }
+}
+async function machineRebuildCommand(deps, name, options = {}) {
+  await machineCommand(async () => {
+    const key = await deps.auth.apiKey();
+    const { machine: read, etag } = await deps.api.getMachineWithEtag(key, name);
+    if (read.kind === "byoc")
+      throw new Error(
+        `${name} is one of your computers; only \`tonbo machine show\` and \`tonbo machine delete\` serve it.`
+      );
+    const image = options.image ?? read.image.reference;
+    await confirm(
+      deps,
+      options.yes,
+      `rebuild Machine ${name}`,
+      () => Promise.resolve(`${rebuildWarning(image)}
+Type the Machine's name to rebuild it:`),
+      name
+    );
+    const answer = await rebuildUntilDone(
+      deps,
+      key,
+      name,
+      options.timeout ?? DEFAULT_WAIT_SECONDS,
+      () => deps.api.rebuildMachine(key, name, { image: options.image }, etag ?? void 0)
+    );
+    print(
+      deps,
+      options.json,
+      { data: answer.machine, rebuild: answer.rebuild },
+      rebuiltText(name, answer.rebuild)
+    );
+  });
+}
 function sleptText(machine) {
   if (machine.state === "creating")
     return `Machine ${machine.name} is still creating; nothing to put to sleep.`;
@@ -6672,43 +6840,61 @@ async function machineWakeCommand(deps, name, options = {}) {
 }
 async function machineDeleteCommand(deps, name, options = {}) {
   await machineCommand(async () => {
+    if (options.keepVolume && options.deleteVolume)
+      throw new Error("Give --keep-volume or --delete-volume, not both.");
+    const deleteVolume = options.deleteVolume ? true : options.keepVolume ? false : void 0;
     const key = await deps.auth.apiKey();
     const read = { etag: null };
     await confirm(
       deps,
       options.yes,
       `delete Machine ${name}`,
-      () => deleteQuestion(deps, key, name, read),
+      () => deleteQuestion(deps, key, name, read, deleteVolume),
       name
     );
-    const { machine, kind } = await deps.api.deleteMachine(
+    const { machine, kind, volume } = await deps.api.deleteMachine(
       key,
       name,
-      ifMatchHeader(options.ifMatch) ?? read.etag ?? void 0
+      ifMatchHeader(options.ifMatch) ?? read.etag ?? void 0,
+      deleteVolume
+    );
+    print(
+      deps,
+      options.json,
+      machine,
+      [deletedText(name, machine, kind), ...volume ? [volumeFateText(volume)] : []].join("\n")
     );
-    print(deps, options.json, machine, deletedText(name, machine, kind));
     if (machine?.kind === "byoc" && machine.byoc.key_state === "active")
       deps.notice(
         `Its key is still active, so ${name} registers again at its next start. Run \`yield logout\` on it, or revoke its key with \`tonbo api-key revoke\`, then forget it again.`
       );
   });
 }
-async function deleteQuestion(deps, key, name, read) {
-  let kind = null;
-  let ownDatabase = false;
+async function deleteQuestion(deps, key, name, read, deleteVolume) {
+  let machine = null;
   try {
     const answer = await deps.api.getMachineWithEtag(key, name);
-    kind = answer.machine.kind;
-    ownDatabase = answer.machine.kind === "managed" && !!answer.machine.database?.name.startsWith("m.");
+    machine = answer.machine;
     read.etag = answer.etag;
   } catch (error) {
     if (!(error instanceof HttpError && error.status === 404)) throw error;
   }
-  if (kind === "byoc")
+  if (machine?.kind === "byoc")
     return `Forget your computer ${name}? It disappears from your Machines; its key is not revoked. Type its name to confirm:`;
-  if (kind === "managed")
-    return `Delete Machine ${name} with its disk${ownDatabase ? ", database" : ""} and logs? This cannot be undone. Type the Machine's name to confirm:`;
-  return `Delete Machine ${name}? Type its name to confirm:`;
+  if (machine?.kind !== "managed") return `Delete Machine ${name}? Type its name to confirm:`;
+  const ownDatabase = !!machine.database?.name.startsWith("m.");
+  const binding = machine.volumes?.[0];
+  const parts = [
+    ...binding && binding.path === void 0 ? [] : ["disk"],
+    ...ownDatabase ? ["database"] : []
+  ];
+  const what = parts.length ? `${parts.join(", ")} and logs` : "logs";
+  const volume = binding ? `Volume ${await volumeName(deps, key, machine) ?? binding.volume}` : "";
+  const fate = !binding ? "" : deleteVolume === true ? ` Its ${volume} is deleted with it.` : deleteVolume === false ? ` Its ${volume} is kept.` : ` Its ${volume} is deleted with it if it was made for this Machine (as the console makes a new Machine's disk), and kept otherwise; --keep-volume or --delete-volume decides.`;
+  return `Delete Machine ${name} with its ${what}?${fate} This cannot be undone. Type the Machine's name to confirm:`;
+}
+function volumeFateText(volume) {
+  return volume.deleted ? `Volume ${volume.name}: deleted with it.` : `Volume ${volume.name}: kept; delete it with \`tonbo volume delete ${volume.name}\`.`;
 }
 function deletedText(name, machine, kind) {
   if (kind === "byoc")
@@ -6838,7 +7024,7 @@ var TOPICS = [
     id: "confirmations",
     title: "Destructive commands",
     text: [
-      "`api-key revoke`, `bucket delete`, `database delete`, `stream delete`, `machine delete` and `volume delete` ask before they act when stdin and stderr are a terminal: a revocation is confirmed by typing `yes`, a deletion by typing the resource's name, as in the console. Without a terminal they refuse unless `--yes` is given."
+      "`api-key revoke`, `bucket delete`, `database delete`, `stream delete`, `machine delete`, `machine rebuild` and `volume delete` ask before they act when stdin and stderr are a terminal: a revocation is confirmed by typing `yes`, a deletion or a Rebuild by typing the resource's name, as in the console. Without a terminal they refuse unless `--yes` is given."
     ]
   }
 ];
@@ -7176,7 +7362,7 @@ var COMMAND_HELP = {
   },
   "tonbo machine show": {
     about: [
-      "Prints the Machine's state and what it means (an `active` Machine that is asleep boots on its first request), its hostnames, image and whether it is pulled, the live activation and conditions with what to do about each, when it sleeps, the database it binds (or none) and its logs URL, a link to what its disk keeps, its ETag and who created it. For an `active` Machine it also reads the newest activations and prints how the last one ended. When the live activation runs an older revision than the Machine's, it says which changes already apply and that the rest apply after `tonbo machine sleep <name>`.",
+      "Prints the Machine's state and what it means (an `active` Machine that is asleep boots on its first request), its hostnames, image and whether it is pulled, the live activation and conditions with what to do about each, when it sleeps, the database it binds (or none), its Volume by name and id as its whole disk or where it is mounted (or none), its logs URL, a link to what its disk keeps, its ETag and who created it. For an `active` Machine it also reads the newest activations and prints how the last one ended. When the live activation runs an older revision than the Machine's, it says which changes already apply and that the rest apply after `tonbo machine sleep <name>`.",
       "When the default port is private, it prints the `curl` call that reaches it with a personal key. For one of your computers it prints its system, harnesses, hostname and device id, which only you see."
     ],
     examples: ["tonbo machine show web"],
@@ -7207,10 +7393,13 @@ var COMMAND_HELP = {
   "tonbo machine update": {
     about: [
       "Changes only what its options name. It reads the Machine and sends the ETag it read, or `--if-match`'s, so a change someone made in between is refused with `precondition_failed` rather than overwritten; a Machine whose creation failed is refused with `machine_failed`. `--env` and `--unset-env` change single variables; `--port` replaces every port, and the current default port stays the default while it is still listed.",
-      "Ports and `--sleep-after` apply at once. The image, command, shape, env, Volume and database apply at the next boot, and the command says how to apply them now: `tonbo machine sleep`, after which the next request boots the new spec. Naming the same tag again resolves its digest again. A Machine whose Volume is its whole disk keeps its image: another image is refused with `rebuild_required`, since only Rebuild, which keeps /home, /workspace and /root and deletes every other change on the disk, may move it, and Rebuild is not available yet. `--database <name>` binds another database of the account in the Machine's region, which no other Machine binds, and `--no-database` binds none; the database it leaves is kept. A Machine created with its own database keeps it.",
+      "Ports and `--sleep-after` apply at once. The image, command, shape, env, Volume and database apply at the next boot, and the command says how to apply them now: `tonbo machine sleep`, after which the next request boots the new spec. Naming the same tag again resolves its digest again. A Machine whose Volume is its whole disk keeps its image: another image is refused with `rebuild_required`, since only Rebuild, which keeps /home, /workspace and /root and deletes every other change on the disk, may move it. At a terminal the CLI then prints what Rebuild deletes and, once you type the Machine's name, sends the change again as a Rebuild; `--rebuild` with `--image` sends it as one at once, as `tonbo machine rebuild` does, and on a Machine whose Volume is mounted at a path, or that has none, it is refused with `volume_not_whole_disk`. `--database <name>` binds another database of the account in the Machine's region, which no other Machine binds, and `--no-database` binds none; the database it leaves is kept. A Machine created with its own database keeps it.",
       "`--delete-after` applies at once and keeps the clock, which counts from the end of the Machine's last activation (or its creation), so a lower value can delete a Machine that has already slept that long; `--no-delete-after` turns it off. `tonbo machine show` prints when it will be deleted."
     ],
-    examples: ["tonbo machine update web --env MODE=staging --sleep-after 300"],
+    examples: [
+      "tonbo machine update web --env MODE=staging --sleep-after 300",
+      "tonbo machine update agent --image ghcr.io/acme/agent:v2 --rebuild"
+    ],
     arguments: {
       name: "the Machine's name",
       command: "the command that replaces the Machine's command at the next boot, after `--`"
@@ -7346,9 +7535,25 @@ var COMMAND_HELP = {
     arguments: NAME("Machine"),
     defaults: { "--timeout": String(DEFAULT_WAIT_SECONDS) }
   },
+  "tonbo machine rebuild": {
+    about: [
+      "Moves a Machine whose Volume is its whole disk to an image: `--image`, or without it the Machine's own reference resolved again, so a newer build of its tag is taken. Rebuild keeps /home, /workspace and /root and deletes every other change on the disk. At a terminal it prints the warning of what it deletes and asks you to type the Machine's name first, and sends the ETag it read then.",
+      "An asleep Machine answers at once: the Rebuild is recorded and the disk moves to the image at the next wake, or, when the disk was never used, the image changes with no Rebuild. An awake Machine with its disk attached is put to sleep first and nothing else changes; the CLI reads it until it is asleep, for up to `--timeout`, and sends the Rebuild again. A Machine whose Volume is mounted at a path, or that has none, is refused with `volume_not_whole_disk`: change its image with `tonbo machine update --image`."
+    ],
+    examples: [
+      "tonbo machine rebuild agent --image ghcr.io/acme/agent:v2",
+      "tonbo machine rebuild agent --yes"
+    ],
+    arguments: NAME("Machine"),
+    defaults: {
+      "--image": "the Machine's own image reference, resolved again",
+      "--timeout": String(DEFAULT_WAIT_SECONDS)
+    },
+    json: "answer"
+  },
   "tonbo machine delete": {
     about: [
-      "Deletes the Machine with its disk and logs; a Volume or database it binds stays. Its name is free for a new Machine at once. At a terminal it asks you to type the Machine's name first, and sends the ETag it read then.",
+      "Deletes the Machine with its disk and logs; a database it binds stays. The Volume it holds is deleted with it when it was made for it, as the console makes a new Machine's disk, and kept otherwise; `--delete-volume` deletes any Volume it holds and `--keep-volume` keeps it. The command then says which. Its name is free for a new Machine at once. At a terminal it asks you to type the Machine's name first, and sends the ETag it read then.",
       "For one of your computers it forgets the computer: it leaves the list at once, and its name is free once the forget completes. Forgetting does not revoke the computer's key, so a computer whose key is still active registers again at its next start; run `yield logout` on it, or `tonbo api-key revoke`, first."
     ],
     examples: ["tonbo machine delete web --yes"],
@@ -9252,7 +9457,10 @@ function createProgram(makeDependencies = createDependencies) {
     machineSpecOptions(
       machine.command("update <name> [command...]").description(
         "change a Machine; [command...] after -- replaces its command at the next boot"
-      ).option("--image <reference>", "a new image, named as for create; applies at the next boot").option("--image-command", "run the image's own CMD again at the next boot").option("--unset-env <KEY>", "remove an environment variable; repeat for several", repeated).option("--clear-ports", "remove every port").option("--if-match <etag>", ifMatchHelp("change")).option("--discard-snapshot", "apply a change that discards the Machine's snapshot").option("--no-volume", "remove the Machine's Volume at the next boot; the Volume is kept").option(
+      ).option("--image <reference>", "a new image, named as for create; applies at the next boot").option("--image-command", "run the image's own CMD again at the next boot").option(
+        "--rebuild",
+        "with --image, move a Machine whose Volume is its whole disk to the image by Rebuild, which deletes changes outside /home, /workspace and /root"
+      ).option("--unset-env <KEY>", "remove an environment variable; repeat for several", repeated).option("--clear-ports", "remove every port").option("--if-match <etag>", ifMatchHelp("change")).option("--discard-snapshot", "apply a change that discards the Machine's snapshot").option("--no-volume", "remove the Machine's Volume at the next boot; the Volume is kept").option(
         "--database <name>",
         "bind the account's database <name> of the Machine's region instead; applies at the next wake"
       ).option("--no-database", "bind no database from the next wake; the database is kept").option("--no-delete-after", "never delete the Machine for being asleep"),
@@ -9378,7 +9586,19 @@ function createProgram(makeDependencies = createDependencies) {
     async (name, options) => machineWakeCommand(dependencies(), name, options)
   );
   operationOptions(
-    machine.command("delete <name>").description("delete a Machine with its disk and logs, or forget one of your computers").option("--yes", "delete without asking; required when stdin is not a terminal").option("--if-match <etag>", ifMatchHelp("delete")),
+    machine.command("rebuild <name>").description(
+      "move a Machine whose Volume is its whole disk to an image; deletes changes outside /home, /workspace and /root"
+    ).option("--image <reference>", "the image to move to, named as for create").option("--yes", "rebuild without asking; required when stdin is not a terminal").option(
+      "--timeout <seconds>",
+      "how long to wait for an awake Machine to sleep, in seconds",
+      parseWhole
+    ),
+    "rebuildMachine"
+  ).action(
+    async (name, options) => machineRebuildCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    machine.command("delete <name>").description("delete a Machine with its disk and logs, or forget one of your computers").option("--yes", "delete without asking; required when stdin is not a terminal").option("--if-match <etag>", ifMatchHelp("delete")).option("--keep-volume", "keep the Machine's Volume, even one made for it").option("--delete-volume", "delete the Machine's Volume with it, even one not made for it"),
     "deleteMachine"
   ).action(
     async (name, options) => machineDeleteCommand(dependencies(), name, options)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "The Tonbo CLI. Compute, disks, databases and streams for AI agents: your agent picks what it needs, sets it up, and knows what it costs, from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {