@tonbo/cli 0.17.1 → 0.17.3

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 = {
@@ -1773,6 +1772,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 +2131,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 +2155,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 +3962,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 +3973,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 = {
@@ -5571,17 +5666,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":
@@ -5688,7 +5789,10 @@ function awakeFields(machine) {
   const held = awake.held_by.length > 0;
   const sleeps = awake.sleeps_at_earliest ? `${awake.sleeps_at_earliest} (${awake.sleeps_by === "idle_early" ? `idle_early: quiet for ${duration(earlyReclaimSeconds)}` : `sleep_after: idle for ${duration(machine.sleep_after_seconds)}`})` : held ? "not while anything holds it" : "not known yet";
   return [
-    ["Held by", held ? awake.held_by.map(holderText).join(", ") : "nothing"],
+    [
+      "Held by",
+      held ? awake.held_by.map(holderText).join(", ") : `nothing${awake.sleeps_at_earliest ? `, so it sleeps at ${awake.sleeps_at_earliest}` : ""}; a detached process (tonbo machine exec ${machine.name} --detach -- <command>) or a hold (tonbo machine hold set ${machine.name} <hold> --for 15m) keeps it awake`
+    ],
     ...awake.idle_since ? [["Idle since", awake.idle_since]] : [],
     ["Quiet", awake.quiet.passes ? "yes" : `no: ${awake.quiet.reason ?? "measuring"}`],
     ["Sleeps at", sleeps],
@@ -6393,7 +6497,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"],
@@ -6448,6 +6560,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",
@@ -6486,6 +6606,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."
@@ -6825,7 +6952,7 @@ var COMMAND_HELP = {
   },
   "tonbo machine exec": {
     about: [
-      "Runs one command in the Machine's running activation through its region's cell origin, waking the Machine first when it is asleep, and streams its stdout and stderr here as they come; a call that woke the Machine prints its hourly ceiling on stderr. The command runs without a shell, as the image's User, and lives exactly as long as the call: there is no terminal and no streamed stdin, and `--stdin` sends at most 1 MiB read before the call.",
+      "Runs one command in the Machine's running activation through its region's cell origin, waking the Machine first when it is asleep, and streams its stdout and stderr here as they come; a call that woke the Machine prints its hourly ceiling on stderr. The command runs without a shell, as the image's User, and lives exactly as long as the call: what it starts in the background, with `nohup`, `setsid` or `&`, is ended when it returns, and the CLI then says how many it ended. There is no terminal and no streamed stdin, and `--stdin` sends at most 1 MiB read before the call.",
       "The CLI exits with the command's status: 128 plus the signal's number when a signal ended it, 124 at `--timeout`, 125 when it was refused, killed or passed 64 MiB of output, 126 or 127 when it could not run, and 255 when the connection ended first and the outcome is unknown. `--json` prints the answer's document instead, with the first and last 512 KiB of each stream.",
       "`--detach` starts the command in the background instead, prints its process id and returns at once: it runs whatever happens to this call, keeps the Machine awake until it ends, and is ended at `--timeout` (default 3600, at most 21600). Read it with `tonbo machine output`, wait for it with `tonbo machine wait`, list them with `tonbo machine ps` and end one with `tonbo machine kill`. A budget or funding stop, or a sleep you ask for, still ends it."
     ],
@@ -7099,19 +7226,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));
@@ -7119,8 +7246,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;
 }
@@ -7215,9 +7342,30 @@ function parseEnv2(pairs) {
   }
   return env;
 }
+var BACKGROUNDERS = /* @__PURE__ */ new Set(["nohup", "setsid"]);
+var SHELLS = /* @__PURE__ */ new Set(["sh", "bash", "zsh", "dash", "ash", "ksh", "mksh"]);
+function backgroundsWork(command) {
+  const base = (arg) => arg.slice(arg.lastIndexOf("/") + 1);
+  if (command.some((arg) => BACKGROUNDERS.has(base(arg)))) return true;
+  const shell = command.findIndex((arg) => SHELLS.has(base(arg)));
+  if (shell < 0) return false;
+  const flag = command.findIndex((arg, at) => at > shell && /^-[a-zA-Z]*c[a-zA-Z]*$/.test(arg));
+  const script = flag < 0 ? void 0 : command[flag + 1]?.trimEnd();
+  if (script === void 0) return false;
+  return script.endsWith("&") && !script.endsWith("&&") || /\b(nohup|disown|setsid)\b/.test(script);
+}
+var detachWay = (name) => `To keep work running after the call, use: tonbo machine exec ${name} --detach -- <command>`;
+function backgroundEndedNotice(name, count) {
+  const processes = count === 1 ? "1 background process" : `${count} background processes`;
+  return `${processes} this command started ${count === 1 ? "was" : "were"} ended when it returned. ${detachWay(name)}`;
+}
+function backgroundsWorkNotice(name, detach) {
+  return detach ? `--detach already keeps the command running after the call, and what it puts in the background with nohup or & is ended when the command itself returns. Run the work in the foreground: tonbo machine exec ${name} --detach -- <command>` : `This command puts work in the background, which is ended when the command returns. ${detachWay(name)}`;
+}
 async function machineExecCommand(deps, name, command, options = {}) {
   if (command.length === 0)
     throw new Error("Name the command after --, such as `tonbo machine exec web -- ls /`.");
+  if (backgroundsWork(command)) deps.notice(backgroundsWorkNotice(name, false));
   const key = await deps.auth.apiKey();
   const region = await regionOf(deps, key, name);
   const body = { command };
@@ -7244,6 +7392,7 @@ async function machineExecCommand(deps, name, command, options = {}) {
   if (options.json) {
     const answer = await response.json();
     print(deps, true, answer.data, "");
+    noticeEnded(deps, name, answer.data);
     exitWith(deps, answer.data.reason ? execExitCode(answer.data) : 0);
     return;
   }
@@ -7276,10 +7425,17 @@ async function machineExecCommand(deps, name, command, options = {}) {
   }
   line(buffered);
   const ended = end ?? { reason: "lost", exit_code: null, signal: null };
-  if (ended.reason !== "exited" && ended.reason !== "signaled")
+  if (ended.reason === "timeout") deps.notice(`The command ended: timeout. ${detachWay(name)}`);
+  else if (ended.reason !== "exited" && ended.reason !== "signaled")
     deps.notice(`The command ended: ${ended.reason}.`);
+  noticeEnded(deps, name, ended);
   exitWith(deps, execExitCode(ended));
 }
+function noticeEnded(deps, name, end) {
+  const count = end.killed_processes ?? 0;
+  if (count > 0 && (end.reason === "exited" || end.reason === "signaled"))
+    deps.notice(backgroundEndedNotice(name, count));
+}
 function processEndText(process2) {
   const end = process2.end;
   if (!end) return "-";
@@ -7299,6 +7455,7 @@ async function machineProcessStartCommand(deps, name, command, options = {}) {
     throw new Error(
       "Name the command after --, such as `tonbo machine exec web --detach -- npm run build`."
     );
+  if (backgroundsWork(command)) deps.notice(backgroundsWorkNotice(name, true));
   const body = { command };
   if (options.cwd) body.cwd = options.cwd;
   if (options.env?.length) body.env = parseEnv2(options.env);
@@ -7465,13 +7622,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());
@@ -7481,14 +7638,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,
@@ -7510,7 +7667,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);
@@ -7520,7 +7677,7 @@ async function machineFileStatCommand(deps, name, path5, options = {}) {
       region,
       {
         params: { name },
-        query: { path: path5 },
+        query: { path: path6 },
         headers: { "tonbo-expect-activation": options.expectActivation }
       }
     );
@@ -7539,13 +7696,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);
@@ -7569,19 +7726,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);
   }
@@ -7697,8 +7854,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 = [];
@@ -7714,15 +7871,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;
   }
@@ -7732,18 +7889,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) {
@@ -7882,10 +8039,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`);
@@ -8089,33 +8246,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,
@@ -8200,7 +8579,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"
   );
@@ -8214,6 +8593,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()));
@@ -8613,31 +9006,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(
@@ -8774,4 +9167,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.1",
+  "version": "0.17.3",
   "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": {