@tonbo/cli 0.17.2 → 0.18.0

package/README.md

@@ -30,6 +30,10 @@ Every command other than `login` and `logout` is named by one operation of the [
 
 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`.
 
+## Updates
+
+Every request to the Management API and to tonbo.dev carries the CLI's release in `Tonbo-CLI-Version`, and every answer names the latest release in `Tonbo-CLI-Latest` and the oldest supported one in `Tonbo-CLI-Minimum`, by the contract [`versions-v1.json`](../../contracts/cli/versions-v1.json): Latest is this package's `version` on main, so merging a release bump moves it with no other change, and Minimum is declared in the contract. When Latest is newer, the command ends with one line on stderr, at most once a day (`update-notice.json` beside the login), never with `--json`, without a terminal, under `CI` or with `TONBO_NO_UPDATE_NOTICE=1`. A release below Minimum is refused with 410 `cli_upgrade_required` on any request; the CLI prints the detail and exits 1. `tonbo update` runs the update of the package manager that installed it (npm, pnpm, bun or yarn), printing the command first, and only prints the command for npx or a path it cannot tell; `--check` only compares. [`src/update.ts`](src/update.ts) holds all of it.
+
 ## Related design
 
 - [ADR-0008: Tonbo CLI onboarding and credential boundaries](../../apps/user-center/docs/decisions/adr-0008-tonbo-cli-onboarding.md)

package/dist/bin/tonbo.js

@@ -2,7 +2,6 @@
 
 // src/app.ts
 import { Command, InvalidArgumentError, Option } from "commander";
-import { readFileSync as readFileSync2 } from "node:fs";
 
 // ../../packages/tonbo-cli-core/dist/src/generated/contracts.js
 var agentNameContract = {
@@ -403,6 +402,7 @@ var managementOperations = {
     "query": [
       "origin",
       "scope",
+      "owners",
       "cursor",
       "limit"
     ],
@@ -1773,6 +1773,102 @@ var loginContract = {
     ]
   }
 };
+var cliVersionsContract = {
+  "version": 1,
+  "description": "Which `tonbo` CLI (@tonbo/cli) releases Tonbo supports, and how a CLI learns of a newer one without a request of its own. User Center answers every request to the Management API host, and every request that carries `headers.client`, with `headers.latest` and `headers.minimum`. A request whose `headers.client` is a release below `minimum` is refused with `refusal.code` (contracts/management/problems-v1.json holds its status and title), its detail naming the update; a request without the header, or with one that is not a release, is never refused for its version. @tonbo/cli sends `headers.client` on every request, prints `notice.line` when `headers.latest` is newer than itself, and on the refusal prints its detail and exits 1. @tonbo/yield does not send the header.",
+  "package": "@tonbo/cli",
+  "latest": {
+    "source": "cli/tonbo/package.json",
+    "field": "version",
+    "description": "The release main carries when User Center is deployed. Merging a version change to main is what publishes it (tonbo-cli-release.yml); the same push redeploys User Center, whose deploy waits until npm serves that version before it ships, so `latest` is always installable and follows each release with no bump of its own."
+  },
+  "minimum": "0.12.0",
+  "minimum_reason": "0.12.0 is the oldest release that can sign in: the login of 0.11 and earlier was retired when 0.12 shipped (contracts/iam/access-token-v1.json `cli_session.login.retired`). Raise it only when a change of the API leaves older releases unable to work, and in the same change say so in the CLI's changelog.",
+  "headers": {
+    "client": "Tonbo-CLI-Version",
+    "latest": "Tonbo-CLI-Latest",
+    "minimum": "Tonbo-CLI-Minimum"
+  },
+  "release_pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?$",
+  "release_order": "Semantic Versioning 2.0.0 precedence: major, minor and patch compare as numbers, and a release with a pre-release suffix is older than the same release without one; pre-release suffixes compare as text. A value that does not match `release_pattern` is not a release and orders with nothing. `order_examples` are [a, b, the sign of a compared with b, or null when either is not a release]; every implementation runs them.",
+  "order_examples": [
+    [
+      "0.17.2",
+      "0.17.3",
+      -1
+    ],
+    [
+      "0.17.3",
+      "0.17.3",
+      0
+    ],
+    [
+      "0.18.0",
+      "0.17.9",
+      1
+    ],
+    [
+      "0.9.0",
+      "0.12.0",
+      -1
+    ],
+    [
+      "1.0.0",
+      "0.99.99",
+      1
+    ],
+    [
+      "0.18.0-beta.1",
+      "0.18.0",
+      -1
+    ],
+    [
+      "0.18.0-beta.2",
+      "0.18.0-beta.1",
+      1
+    ],
+    [
+      "0.17",
+      "0.17.0",
+      null
+    ],
+    [
+      "v0.17.2",
+      "0.17.2",
+      null
+    ],
+    [
+      "0.17.2 ",
+      "0.17.2",
+      null
+    ],
+    [
+      "",
+      "0.12.0",
+      null
+    ]
+  ],
+  "refusal": {
+    "code": "cli_upgrade_required",
+    "registry": "contracts/management/problems-v1.json"
+  },
+  "update_command": "npm install --global @tonbo/cli@latest",
+  "notice": {
+    "line": "tonbo {latest} is available (you have {current}): run tonbo update",
+    "stream": "stderr",
+    "interval_hours": 24,
+    "state": {
+      "description": "When the CLI last printed the notice: `${XDG_CONFIG_HOME}/tonbo/update-notice.json`, else `${HOME}/.config/tonbo/update-notice.json`, beside the login. A state that cannot be read counts as never; one that cannot be written never fails the command.",
+      "file": "update-notice.json"
+    },
+    "silent_when": [
+      "the command line has --json",
+      "neither stdout nor stderr is a terminal",
+      "CI is set to anything but empty, 0 or false",
+      "TONBO_NO_UPDATE_NOTICE is set to anything but empty or 0"
+    ]
+  }
+};
 var cliSessionContract = {
   "prefix": "tbs_",
   "grant": "cli_session",
@@ -2036,7 +2132,7 @@ var ManagementApi = class {
   }
   async requestWith(operationId, key, { params = {}, query = {}, body, idempotencyKey, ifMatch }, seen) {
     const operation = managementOperation(operationId);
-    const path5 = operation.path.replace(/\{([^}]+)\}/g, (_, name) => {
+    const path6 = operation.path.replace(/\{([^}]+)\}/g, (_, name) => {
       const value = params[name];
       if (value === void 0)
         throw new Error(`${operationId} needs the path parameter ${name}.`);
@@ -2060,7 +2156,7 @@ var ManagementApi = class {
     if (ifMatch)
       headers["if-match"] = ifMatch;
     const queryString = search.toString();
-    const url = `${this.apiOrigin}${managementApiBasePath}${path5}${queryString ? `?${queryString}` : ""}`;
+    const url = `${this.apiOrigin}${managementApiBasePath}${path6}${queryString ? `?${queryString}` : ""}`;
     try {
       const fetcher = seen ? async (input, init) => {
         const response = await this.fetcher(input, init);
@@ -3867,7 +3963,7 @@ var CellApi = class {
   }
   url(operationId, region, request) {
     const operation = managementOperations[operationId];
-    const path5 = operation.path.replace(/\{([^}]+)\}/g, (_, name) => {
+    const path6 = operation.path.replace(/\{([^}]+)\}/g, (_, name) => {
       const value = request.params[name];
       if (value === void 0)
         throw new Error(`${operationId} needs the path parameter ${name}.`);
@@ -3878,7 +3974,7 @@ var CellApi = class {
       if (value !== void 0)
         search.set(name, value);
     const query = search.toString();
-    return `${cellOrigin(region)}${managementApiBasePath}${path5}${query ? `?${query}` : ""}`;
+    return `${cellOrigin(region)}${managementApiBasePath}${path6}${query ? `?${query}` : ""}`;
   }
   async init(operationId, key, request) {
     const headers = {
@@ -5424,12 +5520,22 @@ async function volumeDeleteCommand(deps, name, options = {}) {
     );
   });
 }
-async function resolveVolumeBinding(deps, key, spec) {
+function parseVolumeSpec(spec) {
   const split = spec.indexOf(":");
+  if (split === -1 && spec.length > 0) return { name: spec };
   if (split < 1 || split === spec.length - 1)
-    throw new Error(`--volume ${spec}: give <name>:<path>, such as data:/data.`);
-  const volume = await deps.api.getVolume(key, spec.slice(0, split));
-  return { binding: { volume: volume.id, path: spec.slice(split + 1) }, region: volume.region };
+    throw new Error(
+      `--volume ${spec}: give <name> for the Machine's whole disk, or <name>:<path> to mount it at a path, such as data:/data.`
+    );
+  return { name: spec.slice(0, split), path: spec.slice(split + 1) };
+}
+async function resolveVolumeBinding(deps, key, spec) {
+  const { name, path: path6 } = parseVolumeSpec(spec);
+  const volume = await deps.api.getVolume(key, name);
+  return {
+    binding: path6 === void 0 ? { volume: volume.id } : { volume: volume.id, path: path6 },
+    region: volume.region
+  };
 }
 
 // src/machine.ts
@@ -5455,6 +5561,9 @@ var MACHINE_ERROR_HINTS = {
   image_failed: "The Machine's image could not be pulled; `tonbo machine show` says why. Fix the image, then name it again with `tonbo machine update --image`.",
   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.",
   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."
@@ -5571,17 +5680,23 @@ var MACHINE_WAKE_BLOCKED_HINTS = {
   standing: "The account's Streams standing is not solvent: settle the account at <billing>, and the next request wakes it.",
   meter_lag: "Tonbo could not confirm the account's usage in time; the next request tries again.",
   crash_backoff: "Its recent wakes failed; see `tonbo machine activations <name>`.",
-  capacity: "No host had room for its shape; the next request tries again.",
+  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."
 };
 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()) {
+  const at = retryAt ? Date.parse(retryAt) : Number.NaN;
+  if (!Number.isFinite(at) || at <= now) return "which takes a few minutes";
+  const minutes = Math.ceil((at - now) / 6e4);
+  return `about ${minutes} minute${minutes === 1 ? "" : "s"}`;
+}
 function conditionText(name, condition, billing) {
   switch (condition.type) {
     case "wake_blocked": {
       const retry = condition.retry_at ? `, retry after ${condition.retry_at}` : "";
-      const hint = MACHINE_WAKE_BLOCKED_HINTS[condition.reason]?.replaceAll("<name>", name).replaceAll("<billing>", billing);
+      const hint = MACHINE_WAKE_BLOCKED_HINTS[condition.reason]?.replaceAll("<name>", name).replaceAll("<billing>", billing).replaceAll("<minutes>", minutesUntil(condition.retry_at));
       return `wake blocked (${condition.reason.replaceAll("_", " ")}) since ${condition.since}${retry}.${hint ? ` ${hint}` : ""}`;
     }
     case "creation_delayed":
@@ -5711,7 +5826,8 @@ function deleteFields(machine) {
 }
 function volumeText(machine) {
   const binding = machine.volumes?.[0];
-  return binding ? `${binding.volume} at ${binding.path}` : "none";
+  if (!binding) return "none";
+  return binding.path === void 0 ? `${binding.volume} (whole disk)` : `${binding.volume} at ${binding.path}`;
 }
 function machineText(machine, billing, etag = null, lastEnd = null) {
   return [machineFields(machine, billing, etag, lastEnd), ...privatePortLines(machine)].join("\n");
@@ -6396,7 +6512,15 @@ var ENVIRONMENT = [
   },
   {
     names: ["XDG_CONFIG_HOME"],
-    description: "Where the login file lives: `$XDG_CONFIG_HOME/tonbo/login.json` when it is set and not empty, else `$HOME/.config/tonbo/login.json`. A login an earlier release saved, `credentials.json` beside it, is read only when there is no `login.json`."
+    description: "Where the login file lives: `$XDG_CONFIG_HOME/tonbo/login.json` when it is set and not empty, else `$HOME/.config/tonbo/login.json`. A login an earlier release saved, `credentials.json` beside it, is read only when there is no `login.json`. `update-notice.json` beside it records when the update notice last printed."
+  },
+  {
+    names: ["TONBO_NO_UPDATE_NOTICE"],
+    description: "Set to `1` (anything but empty or `0`), the CLI never prints that a newer release is available."
+  },
+  {
+    names: ["CI"],
+    description: "Set to anything but empty, `0` or `false`, as CI services set it, the CLI never prints that a newer release is available."
   },
   {
     names: ["XDG_STATE_HOME"],
@@ -6451,6 +6575,14 @@ var TOPICS = [
       "`api-key create` takes no idempotency key, because a key's secret is never stored and a replay could not return it; a live key's name is unique, so a blind retry is refused with 409 rather than creating a second key. Every other command reads, or sets a resource to the state it names, so running it again does no more than the first run did; a repeated delete or revoke may be refused because the first one already removed it."
     ]
   },
+  {
+    id: "updates",
+    title: "Updates",
+    text: [
+      "The CLI names its release in a `Tonbo-CLI-Version` header on every request to the Management API and to tonbo.dev, and every answer of the Management API names the latest release in `Tonbo-CLI-Latest` and the oldest one Tonbo supports in `Tonbo-CLI-Minimum`, so the CLI learns of a new release with no request of its own; `curl -sI https://api.tonbo.dev/v1/openapi.json` shows both headers. When the latest is newer, the command ends with `tonbo <latest> is available (you have <current>): run tonbo update` on stderr, at most once a day. It never prints with `--json`, when neither stdout nor stderr is a terminal, under `CI=true`, or with `TONBO_NO_UPDATE_NOTICE=1`. An agent that runs the CLI in a terminal sees it too, and should run `tonbo update` before it goes on.",
+      "`tonbo update` updates the CLI with the package manager that installed it, printing the command before it runs it; nothing is ever updated in the background. A release older than `Tonbo-CLI-Minimum` is refused on every request with 410 `cli_upgrade_required`: the CLI prints the refusal, which names the update, and exits 1. `tonbo update` itself still works then."
+    ]
+  },
   {
     id: "confirmations",
     title: "Destructive commands",
@@ -6489,6 +6621,13 @@ var COMMAND_HELP = {
     ],
     examples: ["tonbo logout"]
   },
+  "tonbo update": {
+    about: [
+      "Reads the latest release from the `Tonbo-CLI-Latest` header of the Management API's answer, then updates the CLI with the package manager that installed it: `npm install --global @tonbo/cli@latest`, `pnpm add --global @tonbo/cli@latest`, `bun add --global @tonbo/cli@latest` or `yarn global add @tonbo/cli@latest`. It prints the command first, then runs it in this terminal, and exits with 1 if it fails. When this release is already the latest, it says so and runs nothing.",
+      "A CLI run through npx, `pnpm dlx` or bunx runs the release you name each time, so it prints `npx @tonbo/cli@latest` and runs nothing. When it cannot tell how the CLI was installed, as for a project's own dependency or a copy, it prints the command to run and exits 1. `--check` only prints this release and the latest one."
+    ],
+    examples: ["tonbo update", "tonbo update --check", "tonbo update --check --json"]
+  },
   "tonbo account show": {
     about: [
       "Prints the account commands act in: its id, name and kind, your member subject and role in it, and its limits."
@@ -6762,7 +6901,7 @@ var COMMAND_HELP = {
   },
   "tonbo machine create": {
     about: [
-      "Creates a Machine, a VM booted from an image in one region. It has no database of its own: `--database <name>` binds one of the account's databases of its region, which it then reaches at `TONBO_DATABASE_URL`, and a database binds one Machine at a time; its files can last on a Volume (`--volume`), and its program can open any other database by URL with a key. The image is a public OCI image with a linux/arm64 variant, from Docker Hub or another public registry (`nginx:1.27`, `ghcr.io/org/app:v1`, or one pinned by digest), or `tonbo.dev/platform`, the platform image. A registry reachable only over IPv6, one named by an IP address, and one that redirects its manifests are refused. The CLI resolves a registry image to its linux/arm64 digest, and the image is pulled before the Machine leaves `creating`.",
+      "Creates a Machine, a VM booted from an image in one region. It has no database of its own: `--database <name>` binds one of the account's databases of its region, which it then reaches at `TONBO_DATABASE_URL`, and a database binds one Machine at a time; its disk can last on a Volume (`--volume <name>` keeps the Machine's whole disk on it, and `--volume <name>:<path>` mounts it at a path instead), and its program can open any other database by URL with a key. The image is a public OCI image with a linux/arm64 variant, from Docker Hub or another public registry (`nginx:1.27`, `ghcr.io/org/app:v1`, or one pinned by digest), or `tonbo.dev/platform`, the platform image. A registry reachable only over IPv6, one named by an IP address, and one that redirects its manifests are refused. The CLI resolves a registry image to its linux/arm64 digest, and the image is pulled before the Machine leaves `creating`.",
       "The Machine is served at `https://<name>-<account>.tonbo.sh` on its default port. `--port <port>` serves a private port, which takes a member's token, and `--port <port>:public` an open one, which needs the `machines.public` capability. A command after `--` replaces the image's CMD. `--secret-env KEY=FILE` and `--secret-file KEY=FILE` read initial secrets from local files and store them with the Machine before its first boot; their values are never returned. The CLI warns on stderr when the Machine has no port, since nothing can wake it then, and when an `--env` key looks secret: env values are readable by every member through the API.",
       "The answer is the Machine while it is `creating`. With `--wait` the CLI reads it until it is `active` or `failed`, or `--timeout` passes: a failure prints what to do and exits 1, and a timeout says it is still creating and undoes nothing. A creation the network or a 5xx answer did not confirm is sent at most three times with the same idempotency key, each retry after its `Retry-After` (at most 30 s) or a short backoff; a `name_taken` refusal says which Machine holds the name and how old it is, in case it is yours from a lost reply. In a region not open for Machines the creation is refused with `region_not_offered`, and nothing is created."
     ],
@@ -6813,7 +6952,7 @@ 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. `--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, 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.",
       "`--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"],
@@ -7102,19 +7241,19 @@ function optionDescription(option) {
 function applyHelp(program) {
   const named = /* @__PURE__ */ new Set();
   const walk = (command, words2) => {
-    const path5 = words2.join(" ");
+    const path6 = words2.join(" ");
     command.configureHelp({ ...command.configureHelp(), optionDescription });
-    const help = COMMAND_HELP[path5];
+    const help = COMMAND_HELP[path6];
     if (help) {
-      named.add(path5);
+      named.add(path6);
       for (const [name, text] of Object.entries(help.arguments ?? {})) {
         const argument = command.registeredArguments.find((entry) => entry.name() === name);
-        if (!argument) throw new Error(`${path5} has no argument ${name}`);
+        if (!argument) throw new Error(`${path6} has no argument ${name}`);
         argument.description = text;
       }
       for (const [flag, text] of Object.entries(help.defaults ?? {})) {
         const option = command.options.find((entry) => entry.long === flag);
-        if (!option) throw new Error(`${path5} has no option ${flag}`);
+        if (!option) throw new Error(`${path6} has no option ${flag}`);
         option.defaultValueDescription = text;
       }
       command.addHelpText("after", commandHelpText(help));
@@ -7122,8 +7261,8 @@ function applyHelp(program) {
     for (const child of command.commands) walk(child, [...words2, child.name()]);
   };
   walk(program, [program.name()]);
-  for (const path5 of Object.keys(COMMAND_HELP))
-    if (!named.has(path5)) throw new Error(`The help of ${path5} names no command`);
+  for (const path6 of Object.keys(COMMAND_HELP))
+    if (!named.has(path6)) throw new Error(`The help of ${path6} names no command`);
   program.addHelpText("after", programHelpText());
   return program;
 }
@@ -7498,13 +7637,13 @@ async function machineProcessSummary(cell, key, region, name) {
     return null;
   }
 }
-async function machineFileReadCommand(deps, name, path5, options = {}) {
+async function machineFileReadCommand(deps, name, path6, options = {}) {
   try {
     const key = await deps.auth.apiKey();
     const region = await regionOf(deps, key, name);
     const response = await cellApi(deps).fetch("readMachineFile", key, region, {
       params: { name },
-      query: { path: path5 },
+      query: { path: path6 },
       headers: { range: options.range, "tonbo-expect-activation": options.expectActivation }
     });
     const bytes2 = new Uint8Array(await response.arrayBuffer());
@@ -7514,14 +7653,14 @@ async function machineFileReadCommand(deps, name, path5, options = {}) {
     throw explainMachineError(error);
   }
 }
-async function machineFileWriteCommand(deps, name, path5, options = {}) {
+async function machineFileWriteCommand(deps, name, path6, options = {}) {
   try {
     const bytes2 = options.from ? new Uint8Array(await readFile4(options.from)) : await readAllStdin(deps);
     const key = await deps.auth.apiKey();
     const region = await regionOf(deps, key, name);
     const written = await cellApi(deps).json("writeMachineFile", key, region, {
       params: { name },
-      query: { path: path5 },
+      query: { path: path6 },
       headers: {
         "content-type": "application/octet-stream",
         "if-match": options.ifMatch,
@@ -7543,7 +7682,7 @@ async function machineFileWriteCommand(deps, name, path5, options = {}) {
     throw explainMachineError(error);
   }
 }
-async function machineFileStatCommand(deps, name, path5, options = {}) {
+async function machineFileStatCommand(deps, name, path6, options = {}) {
   try {
     const key = await deps.auth.apiKey();
     const region = await regionOf(deps, key, name);
@@ -7553,7 +7692,7 @@ async function machineFileStatCommand(deps, name, path5, options = {}) {
       region,
       {
         params: { name },
-        query: { path: path5 },
+        query: { path: path6 },
         headers: { "tonbo-expect-activation": options.expectActivation }
       }
     );
@@ -7572,13 +7711,13 @@ async function machineFileStatCommand(deps, name, path5, options = {}) {
     throw explainMachineError(error);
   }
 }
-async function machineFileListCommand(deps, name, path5, options = {}) {
+async function machineFileListCommand(deps, name, path6, options = {}) {
   try {
     const key = await deps.auth.apiKey();
     const region = await regionOf(deps, key, name);
     const listing = await cellApi(deps).json("listMachineFiles", key, region, {
       params: { name },
-      query: { path: path5 },
+      query: { path: path6 },
       headers: { "tonbo-expect-activation": options.expectActivation }
     });
     noticeWake(deps, listing.machine, name);
@@ -7602,19 +7741,19 @@ async function machineFileListCommand(deps, name, path5, options = {}) {
     throw explainMachineError(error);
   }
 }
-async function machineFileDeleteCommand(deps, name, path5, options = {}) {
+async function machineFileDeleteCommand(deps, name, path6, options = {}) {
   try {
     const key = await deps.auth.apiKey();
     const region = await regionOf(deps, key, name);
     await cellApi(deps).fetch("deleteMachineFile", key, region, {
       params: { name },
-      query: { path: path5, recursive: options.recursive ? "true" : void 0 },
+      query: { path: path6, recursive: options.recursive ? "true" : void 0 },
       headers: {
         "tonbo-expect-activation": options.expectActivation,
         "idempotency-key": randomUUID8()
       }
     });
-    print(deps, options.json, { path: path5 }, `Deleted ${path5}.`);
+    print(deps, options.json, { path: path6 }, `Deleted ${path6}.`);
   } catch (error) {
     throw explainMachineError(error);
   }
@@ -7730,8 +7869,8 @@ var LEGACY_BEGIN = "# >>> tonbo project ssh >>>";
 var LEGACY_END = "# <<< tonbo project ssh <<<";
 var PROXY_COMMAND = /^\s*proxycommand(\s|=)/i;
 var SSH_PROXY = /(^|[\s'"/])ssh-proxy(\s|['"]|$)/;
-function shown(path5, home) {
-  return path5.startsWith(home + sep) ? `~${path5.slice(home.length)}` : path5;
+function shown(path6, home) {
+  return path6.startsWith(home + sep) ? `~${path6.slice(home.length)}` : path6;
 }
 function words(text) {
   const found = [];
@@ -7747,15 +7886,15 @@ async function expand(pattern) {
   let paths = [sep];
   for (const part of parts) {
     if (!/[*?]/.test(part)) {
-      paths = paths.map((path5) => join(path5, part));
+      paths = paths.map((path6) => join(path6, part));
       continue;
     }
     const matcher = wildcard(part);
     const next = [];
-    for (const path5 of paths) {
-      const names = await readdir(path5).catch(() => []);
+    for (const path6 of paths) {
+      const names = await readdir(path6).catch(() => []);
       for (const name of names.sort())
-        if (matcher.test(name) && !name.startsWith(".")) next.push(join(path5, name));
+        if (matcher.test(name) && !name.startsWith(".")) next.push(join(path6, name));
     }
     paths = next;
   }
@@ -7765,18 +7904,18 @@ async function scan(home) {
   const sshDir = join(home, ".ssh");
   const files = [];
   const seen = /* @__PURE__ */ new Set();
-  const visit = async (path5, depth) => {
-    if (depth > 16 || seen.has(path5) || !path5.startsWith(sshDir + sep)) return;
-    seen.add(path5);
+  const visit = async (path6, depth) => {
+    if (depth > 16 || seen.has(path6) || !path6.startsWith(sshDir + sep)) return;
+    seen.add(path6);
     let text;
     try {
-      if (!(await stat2(path5)).isFile()) return;
-      text = await readFile5(path5, "utf8");
+      if (!(await stat2(path6)).isFile()) return;
+      text = await readFile5(path6, "utf8");
     } catch {
       return;
     }
     const lines = text.split("\n");
-    const file = { path: path5, lines, blocks: [], handEdited: [] };
+    const file = { path: path6, lines, blocks: [], handEdited: [] };
     const includes = [];
     for (let index = 0; index < lines.length; index++) {
       if (lines[index].trim() === LEGACY_BEGIN) {
@@ -7915,10 +8054,10 @@ async function ensureKey(directory) {
   }
   return key;
 }
-async function writeAtomic(path5, data) {
-  const temporary = `${path5}.${process.pid}.tmp`;
+async function writeAtomic(path6, data) {
+  const temporary = `${path6}.${process.pid}.tmp`;
   await writeFile3(temporary, data, { mode: 384 });
-  await rename5(temporary, path5);
+  await rename5(temporary, path6);
 }
 function certificatePath(directory, user) {
   return join2(directory, `${user}-cert.pub`);
@@ -8122,33 +8261,255 @@ async function sshCertificateIssueCommand(deps, options) {
   print(deps, options.json, data, data.certificate);
 }
 
+// src/update.ts
+import { execFile as execFile3, spawn as spawn2 } from "node:child_process";
+import { readFileSync as readFileSync2 } from "node:fs";
+import { mkdir as mkdir5, readFile as readFile7, realpath as realpath2, rename as rename6, writeFile as writeFile4 } from "node:fs/promises";
+import path5 from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify as promisify3 } from "node:util";
+var contract = cliVersionsContract;
+var CLI_VERSION = JSON.parse(readFileSync2(new URL("../../package.json", import.meta.url), "utf8")).version;
+var RELEASE = new RegExp(contract.release_pattern);
+function compareReleases(a, b) {
+  const left = RELEASE.exec(a);
+  const right = RELEASE.exec(b);
+  if (!left || !right) return null;
+  for (let at = 1; at <= 3; at++) {
+    const difference = Number(left[at]) - Number(right[at]);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  const [leftPre, rightPre] = [left[4], right[4]];
+  if (leftPre === rightPre) return 0;
+  if (leftPre === void 0) return 1;
+  if (rightPre === void 0) return -1;
+  return leftPre < rightPre ? -1 : 1;
+}
+function latestOf(headers) {
+  const latest = headers.get(contract.headers.latest)?.trim() ?? "";
+  return RELEASE.test(latest) ? latest : null;
+}
+function noticeLine(current, latest) {
+  if (latest === null || (compareReleases(current, latest) ?? 0) >= 0) return null;
+  return contract.notice.line.replace("{latest}", latest).replace("{current}", current);
+}
+var ReleaseWatch = class {
+  constructor(current = CLI_VERSION, refuse = (message) => {
+    process.stderr.write(`${message}
+`);
+    process.exit(1);
+  }) {
+    this.current = current;
+    this.refuse = refuse;
+  }
+  latest = null;
+  fetch(fetcher) {
+    return async (input, init) => {
+      const headers = new Headers(
+        init?.headers ?? (input instanceof Request ? input.headers : void 0)
+      );
+      headers.set(contract.headers.client, this.current);
+      const response = await fetcher(input, { ...init, headers });
+      this.latest = latestOf(response.headers) ?? this.latest;
+      if (response.status === 410) {
+        const body = await response.clone().json().catch(() => null);
+        if (body?.code === contract.refusal.code) {
+          const reason2 = [body.detail, body.error].find(
+            (value) => typeof value === "string"
+          );
+          this.refuse(
+            reason2 ?? `This tonbo (${this.current}) is no longer supported. Run \`tonbo update\` (or \`${contract.update_command}\`).`
+          );
+        }
+      }
+      return response;
+    };
+  }
+};
+var set = (value) => !!value && value !== "0";
+function noticeAllowed({ env, argv, stdoutIsTTY, stderrIsTTY }) {
+  if (set(env.TONBO_NO_UPDATE_NOTICE)) return false;
+  if (set(env.CI) && env.CI?.toLowerCase() !== "false") return false;
+  if (argv.includes("--json")) return false;
+  return stdoutIsTTY || stderrIsTTY;
+}
+function noticeStatePath(env = process.env) {
+  return path5.join(path5.dirname(defaultLoginPath(env)), contract.notice.state.file);
+}
+var INTERVAL_MS = contract.notice.interval_hours * 60 * 60 * 1e3;
+function noticeDue(state, now) {
+  const at = state && typeof state === "object" ? Date.parse(String(state.notified_at)) : Number.NaN;
+  return !Number.isFinite(at) || at > now || now - at >= INTERVAL_MS;
+}
+async function showUpdateNotice(watch, {
+  context,
+  statePath,
+  now = Date.now(),
+  write = (line) => process.stderr.write(`${line}
+`)
+}) {
+  const line = noticeLine(watch.current, watch.latest);
+  if (line === null || !noticeAllowed(context)) return;
+  const state = await readFile7(statePath, "utf8").then((text) => JSON.parse(text)).catch(() => null);
+  if (!noticeDue(state, now)) return;
+  write(line);
+  try {
+    await mkdir5(path5.dirname(statePath), { recursive: true, mode: 448 });
+    const temporary = `${statePath}.${process.pid}.tmp`;
+    await writeFile4(
+      temporary,
+      `${JSON.stringify({ version: 1, notified_at: new Date(now).toISOString() })}
+`,
+      { mode: 384 }
+    );
+    await rename6(temporary, statePath);
+  } catch {
+  }
+}
+function installMethod(location) {
+  const at = location.replaceAll("\\", "/").toLowerCase();
+  if (at.includes("/_npx/") || at.includes("/bunx-") || at.includes("/pnpm/dlx/")) return "npx";
+  if (at.includes("/pnpm/global/") || at.includes("/global/") && at.includes("/.pnpm/"))
+    return "pnpm";
+  if (at.includes("/install/global/node_modules/")) return "bun";
+  if (at.includes("/yarn/global/") || at.includes("/yarn/data/global/")) return "yarn";
+  if (/\/(lib|npm|nodejs)\/node_modules\/@tonbo\/cli\//.test(at)) return "npm";
+  return "standalone";
+}
+var PACKAGE = `${contract.package}@latest`;
+var UPDATE_COMMANDS = {
+  npm: ["npm", "install", "--global", PACKAGE],
+  pnpm: ["pnpm", "add", "--global", PACKAGE],
+  bun: ["bun", "add", "--global", PACKAGE],
+  yarn: ["yarn", "global", "add", PACKAGE]
+};
+function updateCommandLine(method) {
+  if (method === "npx") return `npx ${PACKAGE}`;
+  if (method === "standalone") return contract.update_command;
+  return UPDATE_COMMANDS[method].join(" ");
+}
+async function readGlobalRoot(manager) {
+  try {
+    const { stdout } = await promisify3(execFile3)(manager, ["root", "-g"], {
+      shell: process.platform === "win32",
+      timeout: 15e3
+    });
+    return await realpath2(stdout.trim());
+  } catch {
+    return null;
+  }
+}
+function isInside(location, directory) {
+  const normal = (value) => value.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
+  return normal(location).startsWith(`${normal(directory)}/`);
+}
+async function confirmedInstallMethod(location, globalRoot) {
+  const method = installMethod(location);
+  if (method !== "npm" && method !== "pnpm") return method;
+  const root = await globalRoot(method);
+  if (root === null) return "standalone";
+  return isInside(location, method === "pnpm" ? path5.dirname(root) : root) ? method : "standalone";
+}
+async function readLatest(origin, fetcher = fetch) {
+  try {
+    const response = await fetcher(`${origin}/v1/openapi.json`, {
+      method: "HEAD",
+      signal: AbortSignal.timeout(1e4)
+    });
+    return latestOf(response.headers);
+  } catch {
+    return null;
+  }
+}
+function runCommand(command) {
+  return new Promise((resolve2, reject) => {
+    const child = spawn2(command[0], command.slice(1), {
+      stdio: "inherit",
+      // npm, pnpm and yarn are .cmd scripts on Windows, which only a shell runs.
+      shell: process.platform === "win32"
+    });
+    child.on("error", reject);
+    child.on("exit", (code, signal) => resolve2(code ?? (signal ? 1 : 0)));
+  });
+}
+var SCRIPT_LOCATION = fileURLToPath(import.meta.url);
+async function updateCommand(deps, options) {
+  if (options.json && !options.check) throw new Error("--json goes with --check.");
+  const latest = await deps.latest();
+  const method = await confirmedInstallMethod(deps.location, deps.globalRoot);
+  const command = updateCommandLine(method);
+  const order = latest === null ? null : compareReleases(deps.current, latest);
+  const available = order !== null && order < 0;
+  if (options.check) {
+    if (options.json) {
+      deps.output(
+        JSON.stringify({
+          current: deps.current,
+          latest,
+          update_available: available,
+          install: method,
+          command
+        })
+      );
+    } else if (latest === null) {
+      deps.output(`tonbo ${deps.current}; the latest release could not be read from Tonbo.`);
+    } else if (available) {
+      deps.output(`tonbo ${deps.current}; ${latest} is available: run tonbo update`);
+    } else {
+      deps.output(`tonbo ${deps.current} is the latest release.`);
+    }
+    return;
+  }
+  if (latest !== null && !available) {
+    deps.output(`tonbo ${deps.current} is the latest release.`);
+    return;
+  }
+  if (method === "npx") {
+    deps.notice(
+      `This tonbo runs through a package runner, which runs the release you name each time: run \`${command}\`.`
+    );
+    return;
+  }
+  if (method === "standalone") {
+    deps.notice(
+      `Could not tell how the tonbo at ${deps.location} was installed, so nothing was run. Update it with \`${command}\`, or the way you installed it.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  deps.notice(`Running: ${command}`);
+  const status = await deps.run(UPDATE_COMMANDS[method]);
+  if (status !== 0)
+    throw new Error(`${command} exited with status ${status}; tonbo was not updated.`);
+  deps.output(`Updated tonbo${latest ? ` to ${latest}` : ""}: run tonbo --version to check.`);
+}
+
 // src/app.ts
-var packageVersion = JSON.parse(
-  readFileSync2(new URL("../../package.json", import.meta.url), "utf8")
-);
+var releaseWatch = new ReleaseWatch();
 function createDependencies(selection = {}) {
   const api = apiOrigin();
+  const fetcher = releaseWatch.fetch(fetch);
   const account = selection.account?.trim() || process.env.TONBO_ACCOUNT?.trim() || void 0;
   const credentials = new LoginStore({
-    fetcher: fetch,
+    fetcher,
     apiOrigin: api,
     loginOrigin: loginOrigin(api),
     account
   });
   const notice = (text) => console.error(text);
   return {
-    api: new ManagementApi(noticingBudget(fetch, notice), api),
+    api: new ManagementApi(noticingBudget(fetcher, notice), api),
     ask: terminalAsk,
     auth: new AuthClient(
       credentials,
-      fetch,
+      fetcher,
       loginOrigin(api),
       void 0,
       void 0,
       void 0,
       void 0,
       process.env,
-      { client: "tonbo", clientVersion: packageVersion.version }
+      { client: "tonbo", clientVersion: CLI_VERSION }
     ),
     credentials,
     interactive: () => process.stdin.isTTY === true && process.stderr.isTTY === true,
@@ -8210,8 +8571,8 @@ function machineSpecOptions(command, update) {
     "the seconds between SIGTERM and SIGKILL on a planned stop",
     parseWhole
   ).option(
-    "--volume <name:path>",
-    `mount the Volume <name> (see tonbo volume list) at <path>; a Machine has at most one, of its own region${update ? "; applies at the next boot" : ""}`
+    "--volume <name[:path]>",
+    `keep the Machine's whole disk on the Volume <name> (see tonbo volume list), or with :<path> mount it at <path> instead; a Machine has at most one, of its own region${update ? "; applies at the next boot" : ""}`
   ).option(
     "--delete-after <seconds>",
     `delete the Machine once it has been asleep, never woken or failed this long (3600 to 7776000)${update ? "; applies at once, from its last activation's end" : ""}`,
@@ -8233,7 +8594,7 @@ function parseUsageSort(value) {
   }
 }
 function createProgram(makeDependencies = createDependencies) {
-  const program = new Command().name("tonbo").description("Sign in to Tonbo and manage account resources.").version(packageVersion.version).option(
+  const program = new Command().name("tonbo").description("Sign in to Tonbo and manage account resources.").version(CLI_VERSION).option(
     "--account <account>",
     "the account to act in, by name or id: any account you belong to; else TONBO_ACCOUNT, else the default `tonbo account use` set, else your personal account"
   );
@@ -8247,6 +8608,20 @@ function createProgram(makeDependencies = createDependencies) {
     const account2 = program.opts().account;
     await loginCommand(dependencies(), { ...options, account: account2 });
   });
+  program.command("update").description("update this CLI with the package manager that installed it").option("--check", "only print this release and the latest one").option("--json", "with --check, print the two releases and the update command as JSON").action(
+    async (options) => updateCommand(
+      {
+        current: CLI_VERSION,
+        latest: () => readLatest(apiOrigin()),
+        location: SCRIPT_LOCATION,
+        globalRoot: readGlobalRoot,
+        run: runCommand,
+        output: (text) => console.log(text),
+        notice: (text) => console.error(text)
+      },
+      options
+    )
+  );
   program.command("logout").description(
     "end this computer's CLI login and remove the saved login; Yield's capture here stops until the next login"
   ).action(async () => logoutCommand(dependencies()));
@@ -8646,31 +9021,31 @@ function createProgram(makeDependencies = createDependencies) {
     file.command("read <name> <path>").description("print a file of a Machine, waking it first").option("--output <file>", "write the bytes to this local file instead of stdout").option("--range <range>", "one byte range, such as bytes=0-1023").option("--expect-activation <activation>", "read only in this activation"),
     "readMachineFile"
   ).action(
-    async (name, path5, options) => machineFileReadCommand(dependencies(), name, path5, options)
+    async (name, path6, options) => machineFileReadCommand(dependencies(), name, path6, options)
   );
   operationOptions(
     file.command("write <name> <path>").description("replace a file of a Machine with stdin or --from, atomically").option("--from <file>", "the local file to send instead of stdin").option("--mode <mode>", "the file's mode, four octal digits such as 0755").option("--if-match <etag>", "replace only the version with this ETag").option("--create", "only create the file; refuse when it exists").option("--expect-activation <activation>", "write only in this activation"),
     "writeMachineFile"
   ).action(
-    async (name, path5, options) => machineFileWriteCommand(dependencies(), name, path5, options)
+    async (name, path6, options) => machineFileWriteCommand(dependencies(), name, path6, options)
   );
   operationOptions(
     file.command("stat <name> <path>").description("show a path's type, size, mode, owner and ETag").option("--expect-activation <activation>", "stat only in this activation"),
     "statMachineFile"
   ).action(
-    async (name, path5, options) => machineFileStatCommand(dependencies(), name, path5, options)
+    async (name, path6, options) => machineFileStatCommand(dependencies(), name, path6, options)
   );
   operationOptions(
     file.command("list <name> <path>").description("list a directory of a Machine").option("--expect-activation <activation>", "list only in this activation"),
     "listMachineFiles"
   ).action(
-    async (name, path5, options) => machineFileListCommand(dependencies(), name, path5, options)
+    async (name, path6, options) => machineFileListCommand(dependencies(), name, path6, options)
   );
   operationOptions(
     file.command("delete <name> <path>").description("delete a file, a symbolic link or an empty directory of a Machine").option("--recursive", "delete a directory and everything in it").option("--expect-activation <activation>", "delete only in this activation"),
     "deleteMachineFile"
   ).action(
-    async (name, path5, options) => machineFileDeleteCommand(dependencies(), name, path5, options)
+    async (name, path6, options) => machineFileDeleteCommand(dependencies(), name, path6, options)
   );
   const hold = machine.command("hold").description("keep a Machine awake for work that has no open connection");
   operationOptions(
@@ -8807,4 +9182,14 @@ try {
 } catch (error) {
   console.error(error instanceof Error ? error.message : error);
   if (!process.exitCode) process.exitCode = 1;
+} finally {
+  await showUpdateNotice(releaseWatch, {
+    context: {
+      env: process.env,
+      argv: process.argv,
+      stdoutIsTTY: process.stdout.isTTY === true,
+      stderrIsTTY: process.stderr.isTTY === true
+    },
+    statePath: noticeStatePath()
+  }).catch(() => void 0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.17.2",
+  "version": "0.18.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": {