@tonbo/cli 0.13.0 → 0.14.1

package/dist/bin/tonbo.js

@@ -2,7 +2,7 @@
 
 // src/app.ts
 import { Command, InvalidArgumentError, Option } from "commander";
-import { readFileSync } from "node:fs";
+import { readFileSync as readFileSync2 } from "node:fs";
 
 // ../../packages/tonbo-cli-core/dist/src/generated/contracts.js
 var agentNameContract = {
@@ -359,6 +359,17 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo workspace list"
   },
+  "listProjects": {
+    "method": "GET",
+    "path": "/projects",
+    "pathParams": [],
+    "query": [
+      "origin",
+      "cursor",
+      "limit"
+    ],
+    "idempotencyKey": false
+  },
   "listProjectBindings": {
     "method": "GET",
     "path": "/projects/bindings",
@@ -804,6 +815,133 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo machine shapes"
   },
+  "listMachineSecrets": {
+    "method": "GET",
+    "path": "/machines/{name}/secrets",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo machine secret list"
+  },
+  "setMachineSecret": {
+    "method": "PUT",
+    "path": "/machines/{name}/secrets/{key}",
+    "pathParams": [
+      "name",
+      "key"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo machine secret set"
+  },
+  "unsetMachineSecret": {
+    "method": "DELETE",
+    "path": "/machines/{name}/secrets/{key}",
+    "pathParams": [
+      "name",
+      "key"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo machine secret unset"
+  },
+  "execMachineCommand": {
+    "method": "POST",
+    "path": "/machines/{name}/exec",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": true,
+    "cli": "tonbo machine exec",
+    "cell": true
+  },
+  "readMachineFile": {
+    "method": "GET",
+    "path": "/machines/{name}/files/content",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "path"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo machine file read",
+    "cell": true
+  },
+  "writeMachineFile": {
+    "method": "PUT",
+    "path": "/machines/{name}/files/content",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "path"
+    ],
+    "idempotencyKey": true,
+    "cli": "tonbo machine file write",
+    "cell": true
+  },
+  "deleteMachineFile": {
+    "method": "DELETE",
+    "path": "/machines/{name}/files/content",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "path",
+      "recursive"
+    ],
+    "idempotencyKey": true,
+    "cli": "tonbo machine file delete",
+    "cell": true
+  },
+  "statMachineFile": {
+    "method": "GET",
+    "path": "/machines/{name}/files/stat",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "path"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo machine file stat",
+    "cell": true
+  },
+  "listMachineFiles": {
+    "method": "GET",
+    "path": "/machines/{name}/files/list",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "path"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo machine file list",
+    "cell": true
+  },
+  "issueSshCertificate": {
+    "method": "POST",
+    "path": "/ssh/certificates",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo ssh certificate issue",
+    "cell": true
+  },
+  "getSshHostCa": {
+    "method": "GET",
+    "path": "/ssh/host-ca",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo ssh host-ca",
+    "cell": true
+  },
   "listVolumes": {
     "method": "GET",
     "path": "/volumes",
@@ -1538,6 +1676,11 @@ var machineTimings = {
   "wakeHoldSeconds": 25,
   "earlyReclaimSeconds": 120
 };
+var machineSecretLimits = {
+  "perMachine": 64,
+  "valueMaxBytes": 65536,
+  "totalMaxBytes": 262144
+};
 
 // ../../packages/tonbo-cli-core/dist/src/bearer.js
 var MANAGEMENT_AUDIENCE = cliSessionContract.audiences.management;
@@ -1817,6 +1960,21 @@ var ManagementApi = class {
   listMachines(key, page) {
     return this.page("listMachines", key, page);
   }
+  async listMachineSecrets(key, name) {
+    const answer = await this.request("listMachineSecrets", key, {
+      params: { name }
+    });
+    return answer.data;
+  }
+  setMachineSecret(key, name, secretKey, value) {
+    return this.call("setMachineSecret", key, {
+      params: { name, key: secretKey },
+      body: value
+    });
+  }
+  unsetMachineSecret(key, name, secretKey) {
+    return this.request("unsetMachineSecret", key, { params: { name, key: secretKey } });
+  }
   /**
    * A replay with the same idempotency key returns the Machine the first
    * request created, so a transport failure or a 5xx answer is retried here
@@ -3141,6 +3299,73 @@ async function openBrowser(url) {
   }
 }
 
+// ../../packages/tonbo-cli-core/dist/src/cell.js
+function cellOrigin(region, configured = process.env.TONBO_CELL_API_ORIGIN) {
+  if (!/^[a-z0-9-]+$/.test(region))
+    throw new Error(`${region} is not a region.`);
+  const url = new URL((configured?.trim() || "https://api.{region}.tonbo.sh").replace("{region}", region));
+  const loopback = ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback))
+    throw new Error("TONBO_CELL_API_ORIGIN must be an https origin.");
+  return url.origin;
+}
+var CellApi = class {
+  fetcher;
+  constructor(fetcher) {
+    this.fetcher = fetcher;
+  }
+  url(operationId, region, request) {
+    const operation = managementOperations[operationId];
+    const path4 = operation.path.replace(/\{([^}]+)\}/g, (_, name) => {
+      const value = request.params[name];
+      if (value === void 0)
+        throw new Error(`${operationId} needs the path parameter ${name}.`);
+      return encodeURIComponent(value);
+    });
+    const search = new URLSearchParams();
+    for (const [name, value] of Object.entries(request.query ?? {}))
+      if (value !== void 0)
+        search.set(name, value);
+    const query = search.toString();
+    return `${cellOrigin(region)}${managementApiBasePath}${path4}${query ? `?${query}` : ""}`;
+  }
+  async init(operationId, key, request) {
+    const headers = {
+      authorization: `Bearer ${await managementBearer(key)}`
+    };
+    for (const [name, value] of Object.entries(request.headers ?? {}))
+      if (value !== void 0)
+        headers[name.toLowerCase()] = value;
+    return { method: managementOperations[operationId].method, headers, body: request.body };
+  }
+  /** The raw answer; a refusal throws an HttpError naming the request id. */
+  async fetch(operationId, key, region, request) {
+    const url = this.url(operationId, region, request);
+    const response = await this.fetcher(url, await this.init(operationId, key, request));
+    if (response.ok)
+      return response;
+    const answered = () => Promise.resolve(response);
+    await requestJson(answered, url);
+    throw new HttpError(`Request failed with HTTP ${response.status}.`, response.status, null, null);
+  }
+  /** The answer's `data`. */
+  async json(operationId, key, region, request) {
+    const url = this.url(operationId, region, request);
+    const answer = await requestJson(this.fetcher, url, await this.init(operationId, key, request));
+    return answer.data;
+  }
+  /** machine-v2.json `op_kill` (`DELETE /v1/machines/{name}/ops/{op}`), which the Management
+   * API document leaves out as superseded by the planned process kill. Answers the op's record. */
+  async killOp(key, region, name, op) {
+    const url = `${cellOrigin(region)}${managementApiBasePath}/machines/${encodeURIComponent(name)}/ops/${encodeURIComponent(op)}`;
+    const answer = await requestJson(this.fetcher, url, {
+      method: "DELETE",
+      headers: { authorization: `Bearer ${await managementBearer(key)}` }
+    });
+    return answer.data;
+  }
+};
+
 // ../../packages/tonbo-cli-core/dist/src/format.js
 function table(headings, rows) {
   const widths = headings.map((heading, column) => Math.max(heading.length, ...rows.map((row) => (row[column] ?? "").length)));
@@ -4269,6 +4494,7 @@ import { Help } from "commander";
 
 // src/machine.ts
 import { randomUUID as randomUUID5 } from "node:crypto";
+import { readFileSync } from "node:fs";
 
 // src/volume.ts
 import { randomUUID as randomUUID4 } from "node:crypto";
@@ -4306,7 +4532,19 @@ function volumeFields(volume) {
     ["Machine", boundText(volume)],
     ["Size", `${volume.size_gib} GiB`],
     ["Live bytes", `${bytes(volume.live_bytes)} (billed)`],
-    ["Last commit", volume.last_commit_at ?? "none yet"],
+    ["Last meter report", volume.last_commit_at ?? "none yet"],
+    [
+      "Restored to",
+      volume.restored_to ? `${volume.restored_to.committed_at} (generation ${volume.restored_to.data_generation})` : "none"
+    ],
+    [
+      "Backed up to",
+      volume.backed_up_to ? volume.backed_up_to.committed_at ? `${volume.backed_up_to.committed_at} (generation ${volume.backed_up_to.data_generation}; ${volume.backed_up_to.dirty_bytes} bytes pending copy)` : `empty snapshot (generation ${volume.backed_up_to.data_generation}; ${volume.backed_up_to.dirty_bytes} bytes pending copy)` : "unknown"
+    ],
+    [
+      "Cold GETs",
+      volume.cold ? `${volume.cold.demand_gets} demand, ${volume.cold.hydrate_gets} hydration` : "none"
+    ],
     ["Durability", VOLUME_DURABILITY_LINK],
     ["Created", volume.created_at]
   ]);
@@ -4415,14 +4653,16 @@ var MACHINE_ERROR_HINTS = {
   precondition_failed: "The Machine changed since it was read, or another Machine now has its name; `tonbo machine show` it and run the command again.",
   machine_failed: "A Machine whose creation failed does not change: `tonbo machine show` says why; delete it with `tonbo machine delete` and create it again.",
   snapshot_would_be_discarded: "Pass --discard-snapshot to apply the change at the next boot, which then starts fresh.",
-  machine_limit_reached: "The account holds as many Machines as it may: delete one you no longer need (`tonbo machine list`), or ask for more.",
+  machine_limit_reached: "The account holds as many Machines as it may: delete one you no longer need (`tonbo machine list`).",
   database_bound: "Another Machine binds that database, and a database binds one Machine: name another, or delete the Machine that binds it first.",
   idempotency_conflict: "That idempotency key belongs to another request: leave out --idempotency-key to create a new Machine.",
   create_rate_limited: "Too many Machines were created in the last hour; try again later.",
   image_pulling: "The Machine's image is still being pulled; the request was not run. Try again shortly; `tonbo machine show` reports the image's state.",
   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."
+  volumes_not_offered: "Volumes are not offered to this account in the Machine's region yet; nothing was created or changed.",
+  secret_env_conflict: "Use another secret key or remove the non-secret env variable with that name.",
+  secret_limit: "Reduce the number or byte size of this Machine's secrets."
 };
 var MACHINE_IMAGE_FAILURE_HINTS = {
   image_unavailable: "The registry no longer serves that image publicly, or served other bytes for it: publish it again, or use another image",
@@ -4531,7 +4771,9 @@ var MACHINE_WAKE_BLOCKED_HINTS = {
   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.",
-  region_closed: "Machines are closed in its region for now; the next request after they reopen 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 conditionText(name, condition, billing) {
@@ -4617,7 +4859,7 @@ function machineFields(machine, billing, etag = null, lastEnd = null) {
     ["HTTPS", machine.hostnames.https],
     // The resource keeps the SSH destination as a receipt; SSH is not served
     // before tier P3.
-    ["SSH", `${machine.hostnames.ssh} (not served yet)`],
+    ["SSH", `${machine.hostnames.ssh} (tonbo ssh ${machine.name})`],
     ["Env", Object.keys(machine.env).sort().join(", ") || "none"],
     ["Stop grace", `${machine.stop_grace_seconds} s`],
     ["Volume", volumeText(machine)],
@@ -4708,15 +4950,11 @@ function parseEnv(pairs) {
   return env;
 }
 var SECRET_LOOKING = /(_KEY|_TOKEN)$|SECRET|PASSWORD/i;
-function specWarnings(deps, ports, envKeys) {
-  if (ports.length === 0)
-    deps.notice(
-      "This Machine has no port: until exec and SSH arrive, nothing can wake it. Add --port <port>."
-    );
+function specWarnings(deps, _ports, envKeys) {
   const secret = envKeys.filter((key) => SECRET_LOOKING.test(key)).sort();
   if (secret.length)
     deps.notice(
-      `${secret.join(", ")} ${secret.length === 1 ? "looks" : "look"} secret: env values are readable by every member through the API; Machine secrets come later.`
+      `${secret.join(", ")} ${secret.length === 1 ? "looks" : "look"} secret: env values are readable by every member through the API; use Machine secrets for private values.`
     );
 }
 function waitTimeout(options) {
@@ -4743,6 +4981,41 @@ async function waitForMachine(deps, key, name, firstWait, every, timeout, settle
     wait = every;
   }
 }
+function secretFromFile(key, file, delivery) {
+  if (!key || !file) throw new Error("Pass a secret as KEY=FILE.");
+  const bytes2 = readFileSync(file === "-" ? 0 : file);
+  if (bytes2.byteLength > machineSecretLimits.valueMaxBytes)
+    throw new Error(`Secret ${key} exceeds the ${machineSecretLimits.valueMaxBytes}-byte limit.`);
+  if (delivery === "file") return { delivery, value_base64: bytes2.toString("base64") };
+  let value;
+  try {
+    value = new TextDecoder("utf-8", { fatal: true }).decode(bytes2);
+  } catch {
+    throw new Error(`Secret ${key} is not UTF-8; use --secret-file for binary bytes.`);
+  }
+  return { delivery, value };
+}
+function createSecrets(options) {
+  const values = {};
+  let total = 0;
+  for (const [delivery, entries] of [
+    ["env", options.secretEnv],
+    ["file", options.secretFile]
+  ]) {
+    for (const entry of entries ?? []) {
+      const separator = entry.indexOf("=");
+      if (separator < 1) throw new Error("Pass a secret as KEY=FILE.");
+      const key = entry.slice(0, separator);
+      if (Object.hasOwn(values, key)) throw new Error(`Secret ${key} was named twice.`);
+      const secret = secretFromFile(key, entry.slice(separator + 1), delivery);
+      total += "value" in secret ? Buffer.byteLength(secret.value, "utf8") : Buffer.from(secret.value_base64, "base64").byteLength;
+      if (Object.keys(values).length >= machineSecretLimits.perMachine || total > machineSecretLimits.totalMaxBytes)
+        throw new Error("Machine secrets exceed their count or total byte limit.");
+      values[key] = secret;
+    }
+  }
+  return values;
+}
 function deleteAfterSeconds(option) {
   if (typeof option === "number") return option;
   return option === false ? null : void 0;
@@ -4795,6 +5068,50 @@ async function machineListCommand(deps, options = {}) {
       );
   });
 }
+async function machineSecretListCommand(deps, name, options = {}) {
+  await machineCommand(async () => {
+    const secrets = await deps.api.listMachineSecrets(await deps.auth.apiKey(), name);
+    print(
+      deps,
+      options.json,
+      secrets,
+      secrets.length ? table(
+        ["KEY", "DELIVERY", "VERSION", "UPDATED", "BY"],
+        secrets.map((secret) => [
+          secret.key,
+          secret.delivery,
+          String(secret.version),
+          secret.updated_at,
+          secret.updated_by.sub
+        ])
+      ) : `Machine ${name} has no secrets.`
+    );
+  });
+}
+async function machineSecretSetCommand(deps, name, secretKey, options) {
+  await machineCommand(async () => {
+    const entry = await deps.api.setMachineSecret(
+      await deps.auth.apiKey(),
+      name,
+      secretKey,
+      secretFromFile(secretKey, options.from, options.delivery ?? "env")
+    );
+    print(
+      deps,
+      options.json,
+      entry,
+      `Set ${entry.key} on Machine ${name} (version ${entry.version}; applies at the next activation).`
+    );
+  });
+}
+async function machineSecretUnsetCommand(deps, name, secretKey) {
+  await machineCommand(async () => {
+    await deps.api.unsetMachineSecret(await deps.auth.apiKey(), name, secretKey);
+    deps.output(
+      `Removed ${secretKey} from Machine ${name}; the next activation will not receive it.`
+    );
+  });
+}
 function conditionsCell(machine) {
   const conditions = machine.status.conditions ?? [];
   if (!conditions.length) return "-";
@@ -4877,6 +5194,7 @@ async function machineCreateCommand(deps, name, command, options = {}) {
     if (!options.image) throw new Error("Pass --image <reference>.");
     const timeout = waitTimeout(options);
     const env = parseEnv(options.env ?? []);
+    const secrets = createSecrets(options);
     const ports = withDefault(parsePorts(options.port ?? []), options.defaultPort);
     const key = await deps.auth.apiKey();
     const bound = typeof options.volume === "string" ? await resolveVolumeBinding(deps, key, options.volume) : null;
@@ -4899,6 +5217,7 @@ async function machineCreateCommand(deps, name, command, options = {}) {
           command: command.length ? command : void 0,
           ports: ports.length ? ports : void 0,
           env: Object.keys(env).length ? env : void 0,
+          ...Object.keys(secrets).length ? { secrets } : {},
           sleep_after_seconds: options.sleepAfter,
           idle_action: options.idleAction,
           stop_grace_seconds: options.stopGrace,
@@ -5199,6 +5518,10 @@ var ENVIRONMENT = [
     names: ["TONBO_API_ORIGIN"],
     description: "The Management API origin, `https://api.tonbo.dev` when unset. It must be https, or http on a loopback address. `tonbo login` opens the login page on the same origin without its `api.` label."
   },
+  {
+    names: ["TONBO_CELL_API_ORIGIN"],
+    description: "The cell origin `tonbo machine exec` and the file commands call, with `{region}` for the Machine's region; `https://api.{region}.tonbo.sh` when unset. It must be https, or http on a loopback address."
+  },
   {
     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`."
@@ -5540,7 +5863,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`.",
-      "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. 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 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."
     ],
     examples: ["tonbo machine create web --image nginx:1.27 --port 80:public --wait"],
@@ -5565,6 +5888,28 @@ var COMMAND_HELP = {
     examples: ["tonbo machine show web"],
     arguments: NAME("Machine")
   },
+  "tonbo machine secret list": {
+    about: [
+      "Lists a Machine's secret keys, delivery, version and last writer. The values are never returned."
+    ],
+    examples: ["tonbo machine secret list web"],
+    arguments: { name: "the Machine whose secrets to list" }
+  },
+  "tonbo machine secret set": {
+    about: [
+      "Reads the secret from a local file, or standard input with `--from -`, without putting its value in shell history. `env` delivers UTF-8 text as an environment variable; `file` delivers arbitrary bytes under `$TONBO_SECRETS_DIR`. The new value applies at the next activation."
+    ],
+    examples: ["tonbo machine secret set web API_KEY --from ./api-key.txt"],
+    arguments: { name: "the Machine to change", key: "the secret's environment or file name" },
+    defaults: { "--delivery": "env" }
+  },
+  "tonbo machine secret unset": {
+    about: [
+      "Removes a Machine secret whether or not it exists. A running activation keeps its existing value until the next activation."
+    ],
+    examples: ["tonbo machine secret unset web API_KEY"],
+    arguments: { name: "the Machine to change", key: "the secret to remove" }
+  },
   "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.",
@@ -5581,6 +5926,59 @@ var COMMAND_HELP = {
       "--if-match": "the ETag the command reads"
     }
   },
+  "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.",
+      "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."
+    ],
+    examples: [
+      "tonbo machine exec web -- ls -la /app",
+      "tonbo machine exec web --timeout 60 -- npm test"
+    ],
+    arguments: {
+      name: "the Machine's name",
+      command: "the command and its arguments, after `--`"
+    },
+    defaults: { "--timeout": "600", "--cwd": "the image's WorkingDir" }
+  },
+  "tonbo machine file read": {
+    about: [
+      "Prints one regular file of the Machine, waking it when it is asleep. A file is gone when the Machine sleeps, so a read that woke it sees only its image."
+    ],
+    examples: [
+      "tonbo machine file read web /etc/hostname",
+      "tonbo machine file read web /app/out.tar --output out.tar"
+    ],
+    arguments: { name: "the Machine's name", path: "the file's absolute path in the Machine" }
+  },
+  "tonbo machine file write": {
+    about: [
+      "Replaces one file of the Machine atomically with stdin, or with `--from`, at most 64 MiB, creating missing directories; a reader sees the old file or the new one. `--if-match` replaces only the version `tonbo machine file stat` printed, and `--create` only creates. The file lasts until the Machine sleeps."
+    ],
+    examples: ["tonbo machine file write web /app/config.json --from config.json"],
+    arguments: { name: "the Machine's name", path: "the file's absolute path in the Machine" }
+  },
+  "tonbo machine file stat": {
+    about: [
+      "Prints one path's type, size, mode, owner, modification time and ETag, without following a symbolic link."
+    ],
+    examples: ["tonbo machine file stat web /app/config.json"],
+    arguments: { name: "the Machine's name", path: "the absolute path in the Machine" }
+  },
+  "tonbo machine file list": {
+    about: [
+      "Lists one directory of the Machine, not recursively, sorted by name; at most 10,000 entries."
+    ],
+    examples: ["tonbo machine file list web /app"],
+    arguments: { name: "the Machine's name", path: "the directory's absolute path in the Machine" }
+  },
+  "tonbo machine file delete": {
+    about: [
+      "Deletes one file, symbolic link (never its target) or empty directory of the Machine, and a directory with everything in it with `--recursive`. It never deletes `/`, a mount point or Tonbo's own paths."
+    ],
+    examples: ["tonbo machine file delete web /app/tmp --recursive"],
+    arguments: { name: "the Machine's name", path: "the absolute path in the Machine" }
+  },
   "tonbo machine sleep": {
     about: [
       "Puts an awake Machine to sleep now, and says so when it is already asleep or still creating; its next request boots it on its latest spec. With `--wait` the CLI reads the Machine until it is asleep or `--timeout` passes."
@@ -5613,6 +6011,40 @@ var COMMAND_HELP = {
     examples: ["tonbo machine shapes"],
     json: "answer"
   },
+  "tonbo ssh": {
+    about: [
+      "Opens a terminal on the Machine, or runs the command after `--` there, with your system's `ssh`. The CLI keeps one key for this computer in `~/.config/tonbo/ssh`, gets a short-lived certificate for you from the Machine's region whenever the one it holds is about to expire, and trusts Tonbo's host CA, so nothing is installed in the Machine's image. A Machine that is asleep wakes for the login.",
+      "A certificate lasts at most 10 minutes and only has to be valid when you log in: an open session stays open. A session counts as a connection, so the Machine stays awake while you use it, and the connection closes after 60 minutes with nothing typed."
+    ],
+    examples: ["tonbo ssh web", "tonbo ssh web -- uname -a"]
+  },
+  "tonbo ssh config": {
+    about: [
+      "Prints an ssh_config block for every Machine. Append it to `~/.ssh/config` and plain `ssh <name>.<account>@<region>.tonbo.sh`, `scp`, `sftp`, `rsync -e ssh` and VS Code or Cursor Remote-SSH work, with `tonbo ssh refresh` renewing the certificate before each connection that needs it. Port forwarding with `-L` reaches the Machine's own loopback."
+    ],
+    examples: ["tonbo ssh config >> ~/.ssh/config"]
+  },
+  "tonbo ssh host-ca": {
+    about: [
+      "Prints the `@cert-authority` lines that let OpenSSH verify Tonbo's SSH hosts, one per host CA key every region trusts, for a known_hosts file of your own. `tonbo ssh` and `tonbo ssh config` keep their own copy; this is for setups without the CLI."
+    ],
+    examples: ["tonbo ssh host-ca --region eu-test-1 >> ~/.ssh/known_hosts"]
+  },
+  "tonbo ssh certificate issue": {
+    about: [
+      "Signs your own public key into a certificate of the account for SSH to its Machines, for a key the CLI does not keep, such as one in CI. The certificate is valid for at most 10 minutes, and never past the login's token, so ask again before each login; an open session outlives it. Use it with `ssh -i <key> -o CertificateFile=<certificate> <name>.<account>@<region>.tonbo.sh`."
+    ],
+    examples: [
+      "tonbo ssh certificate issue --region eu-test-1 --public-key ~/.ssh/ci.pub > ~/.ssh/ci-cert.pub"
+    ],
+    defaults: { "--ttl": "the API's default; the certificate lasts at most 10 minutes" }
+  },
+  "tonbo ssh refresh": {
+    about: [
+      "Gets a new certificate for the destination's account when the one this computer holds expires within two minutes, and exits 0 once a valid one is held. `ssh` runs it through the `Match exec` line of `tonbo ssh config`; you rarely run it yourself."
+    ],
+    examples: ["tonbo ssh refresh web.acme@eu-test-1.tonbo.sh"]
+  },
   "tonbo volume list": {
     about: [
       "Lists the account's Volumes in every region with each one's state, the Machine bound to it, its size and its live bytes."
@@ -5731,6 +6163,283 @@ function applyHelp(program) {
   return program;
 }
 
+// src/machine-cell.ts
+import { readFile as readFile3, writeFile } from "node:fs/promises";
+import { randomUUID as randomUUID6 } from "node:crypto";
+var EXEC_EXIT_CODES = {
+  timeout: 124,
+  output_limit: 125,
+  killed: 125,
+  lost: 255,
+  refused: 125,
+  command_not_executable: 126,
+  command_not_found: 127
+};
+var SIGNALS = {
+  SIGHUP: 1,
+  SIGINT: 2,
+  SIGQUIT: 3,
+  SIGILL: 4,
+  SIGTRAP: 5,
+  SIGABRT: 6,
+  SIGBUS: 7,
+  SIGFPE: 8,
+  SIGKILL: 9,
+  SIGUSR1: 10,
+  SIGSEGV: 11,
+  SIGUSR2: 12,
+  SIGPIPE: 13,
+  SIGALRM: 14,
+  SIGTERM: 15
+};
+function execExitCode(end) {
+  switch (end.reason) {
+    case "exited":
+      return end.exit_code ?? 0;
+    case "signaled":
+      return 128 + (SIGNALS[end.signal ?? ""] ?? 0);
+    default:
+      return EXEC_EXIT_CODES[end.reason];
+  }
+}
+function execRefusalExitCode(error) {
+  if (error instanceof HttpError) {
+    if (error.code === "command_not_found") return EXEC_EXIT_CODES.command_not_found;
+    if (error.code === "command_not_executable") return EXEC_EXIT_CODES.command_not_executable;
+    if (error.code === "lost") return EXEC_EXIT_CODES.lost;
+  }
+  return EXEC_EXIT_CODES.refused;
+}
+function cellText(value) {
+  if (value === null || value === void 0) return "-";
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : JSON.stringify(value);
+}
+function cellApi(deps) {
+  return deps.cell ?? new CellApi(fetch);
+}
+function writeBytes(deps, stream, bytes2) {
+  if (deps.write) deps.write(stream, bytes2);
+  else (stream === "stdout" ? process.stdout : process.stderr).write(bytes2);
+}
+function exitWith(deps, code) {
+  if (deps.exit) deps.exit(code);
+  else process.exitCode = code;
+}
+async function readAllStdin(deps) {
+  if (deps.readStdin) return deps.readStdin();
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return new Uint8Array(Buffer.concat(chunks));
+}
+async function regionOf(deps, key, name) {
+  const machine = await deps.api.getMachine(key, name);
+  if (machine.kind !== "managed")
+    throw new Error(
+      `${name} is one of your computers; exec and files reach only managed Machines.`
+    );
+  return machine.region;
+}
+function noticeWake(deps, ref, name) {
+  if (!ref?.woke) return;
+  const price = ref.ceiling_usd_micros_per_hour === null ? "an unknown price" : `at most ${usd(ref.ceiling_usd_micros_per_hour)} an hour`;
+  deps.notice(`Woke ${name} (activation ${ref.activation}), ${price} while it stays awake.`);
+}
+function parseEnv2(pairs) {
+  const env = {};
+  for (const pair of pairs) {
+    const at = pair.indexOf("=");
+    if (at <= 0) throw new Error(`--env ${pair} is not KEY=VALUE.`);
+    env[pair.slice(0, at)] = pair.slice(at + 1);
+  }
+  return env;
+}
+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 /`.");
+  const key = await deps.auth.apiKey();
+  const region = await regionOf(deps, key, name);
+  const body = { command };
+  if (options.cwd) body.cwd = options.cwd;
+  if (options.env?.length) body.env = parseEnv2(options.env);
+  if (options.timeout !== void 0) body.timeout_seconds = options.timeout;
+  if (options.expectActivation) body.expect_activation = options.expectActivation;
+  if (options.stdin) body.stdin = Buffer.from(await readAllStdin(deps)).toString("base64");
+  let response;
+  try {
+    response = await cellApi(deps).fetch("execMachineCommand", key, region, {
+      params: { name },
+      headers: {
+        "content-type": "application/json",
+        accept: options.json ? "application/json" : "application/x-ndjson",
+        "idempotency-key": options.idempotencyKey
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    exitWith(deps, execRefusalExitCode(error));
+    throw explainMachineError(error);
+  }
+  if (options.json) {
+    const answer = await response.json();
+    print(deps, true, answer.data, "");
+    exitWith(deps, answer.data.reason ? execExitCode(answer.data) : 0);
+    return;
+  }
+  const decoder = new TextDecoder();
+  let buffered = "";
+  let end = null;
+  const line = (text) => {
+    if (!text.trim()) return;
+    const frame = JSON.parse(text);
+    if (frame.type === "start") noticeWake(deps, frame.machine, name);
+    else if (frame.type === "stdout" || frame.type === "stderr")
+      writeBytes(deps, frame.type, new Uint8Array(Buffer.from(frame.data ?? "", "base64")));
+    else if (frame.type === "end") end = frame;
+  };
+  if (response.headers.get("content-type")?.startsWith("application/json")) {
+    const answer = await response.json();
+    print(deps, true, answer.data, "");
+    return;
+  }
+  const reader = response.body?.getReader();
+  while (reader) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffered += decoder.decode(value, { stream: true });
+    let at;
+    while ((at = buffered.indexOf("\n")) >= 0) {
+      line(buffered.slice(0, at));
+      buffered = buffered.slice(at + 1);
+    }
+  }
+  line(buffered);
+  const ended = end ?? { reason: "lost", exit_code: null, signal: null };
+  if (ended.reason !== "exited" && ended.reason !== "signaled")
+    deps.notice(`The command ended: ${ended.reason}.`);
+  exitWith(deps, execExitCode(ended));
+}
+async function machineFileReadCommand(deps, name, path4, 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: path4 },
+      headers: { range: options.range, "tonbo-expect-activation": options.expectActivation }
+    });
+    const bytes2 = new Uint8Array(await response.arrayBuffer());
+    if (options.output) await writeFile(options.output, bytes2);
+    else writeBytes(deps, "stdout", bytes2);
+  } catch (error) {
+    throw explainMachineError(error);
+  }
+}
+async function machineFileWriteCommand(deps, name, path4, options = {}) {
+  try {
+    const bytes2 = options.from ? new Uint8Array(await readFile3(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: path4 },
+      headers: {
+        "content-type": "application/octet-stream",
+        "if-match": options.ifMatch,
+        "if-none-match": options.create ? "*" : void 0,
+        "tonbo-file-mode": options.mode,
+        "tonbo-expect-activation": options.expectActivation,
+        "idempotency-key": randomUUID6()
+      },
+      body: new Uint8Array(bytes2)
+    });
+    noticeWake(deps, written.machine, name);
+    print(
+      deps,
+      options.json,
+      written,
+      `${written.created ? "Created" : "Replaced"} ${written.path} (${written.size} bytes, ${written.etag}); it lasts until the Machine sleeps.`
+    );
+  } catch (error) {
+    throw explainMachineError(error);
+  }
+}
+async function machineFileStatCommand(deps, name, path4, options = {}) {
+  try {
+    const key = await deps.auth.apiKey();
+    const region = await regionOf(deps, key, name);
+    const stat = await cellApi(deps).json(
+      "statMachineFile",
+      key,
+      region,
+      {
+        params: { name },
+        query: { path: path4 },
+        headers: { "tonbo-expect-activation": options.expectActivation }
+      }
+    );
+    noticeWake(deps, stat.machine, name);
+    print(
+      deps,
+      options.json,
+      stat,
+      fields(
+        ["path", "type", "size", "mode", "uid", "gid", "mtime", "etag", "target", "durability"].map(
+          (field) => [field, cellText(stat[field])]
+        )
+      )
+    );
+  } catch (error) {
+    throw explainMachineError(error);
+  }
+}
+async function machineFileListCommand(deps, name, path4, 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: path4 },
+      headers: { "tonbo-expect-activation": options.expectActivation }
+    });
+    noticeWake(deps, listing.machine, name);
+    print(
+      deps,
+      options.json,
+      listing,
+      table(
+        ["NAME", "TYPE", "SIZE", "MODE", "MODIFIED"],
+        listing.entries.map((entry) => [
+          entry.name ?? `(base64) ${entry.name_b64}`,
+          entry.type,
+          String(entry.size),
+          entry.mode,
+          entry.mtime
+        ])
+      )
+    );
+    if (listing.truncated) deps.notice("The directory has more entries than one listing holds.");
+  } catch (error) {
+    throw explainMachineError(error);
+  }
+}
+async function machineFileDeleteCommand(deps, name, path4, 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: path4, recursive: options.recursive ? "true" : void 0 },
+      headers: {
+        "tonbo-expect-activation": options.expectActivation,
+        "idempotency-key": randomUUID6()
+      }
+    });
+    print(deps, options.json, { path: path4 }, `Deleted ${path4}.`);
+  } catch (error) {
+    throw explainMachineError(error);
+  }
+}
+
 // src/prompt.ts
 import select from "@inquirer/select";
 import { createInterface } from "node:readline/promises";
@@ -5756,9 +6465,240 @@ async function terminalAsk(question) {
   }
 }
 
+// src/ssh.ts
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { chmod as chmod2, mkdir as mkdir3, readFile as readFile4, readdir, rename as rename3, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function sshDirectory(env = process.env) {
+  const config = env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+  return join(config, "tonbo", "ssh");
+}
+var RENEW_BEFORE_MS = 12e4;
+var REQUESTED_TTL_SECONDS = 3600;
+function parseDestination(destination) {
+  const at = destination.lastIndexOf("@");
+  const user = destination.slice(0, at);
+  const host = destination.slice(at + 1).toLowerCase();
+  const dot = user.lastIndexOf(".");
+  if (at <= 0 || dot <= 0 || dot === user.length - 1 || !host.includes(".")) {
+    throw new Error(`${destination} is not a Machine's SSH destination (<name>.<account>@<host>)`);
+  }
+  return { user, host, account: user.slice(dot + 1) };
+}
+function cellOrigin2(host) {
+  return `https://api.${host}`;
+}
+async function ensureKey(directory) {
+  const key = join(directory, "id_ed25519");
+  await mkdir3(directory, { recursive: true, mode: 448 });
+  await chmod2(directory, 448);
+  if (!existsSync(key)) {
+    const made = spawnSync(
+      "ssh-keygen",
+      ["-q", "-t", "ed25519", "-N", "", "-C", "tonbo", "-f", key],
+      {
+        stdio: ["ignore", "ignore", "inherit"]
+      }
+    );
+    if (made.error || made.status !== 0) {
+      throw new Error(
+        "ssh-keygen could not make the key ~/.config/tonbo/ssh/id_ed25519; install OpenSSH's client tools and run the command again"
+      );
+    }
+  }
+  return key;
+}
+async function writeAtomic(path4, data) {
+  const temporary = `${path4}.${process.pid}.tmp`;
+  await writeFile2(temporary, data, { mode: 384 });
+  await rename3(temporary, path4);
+}
+function certificatePath(directory, user) {
+  return join(directory, `${user}-cert.pub`);
+}
+function hostCAPath(directory, host) {
+  if (!/^[a-z0-9][a-z0-9.-]*$/.test(host)) {
+    throw new Error(`${host} is not a Machine's SSH host`);
+  }
+  return join(directory, "host-ca", host);
+}
+async function trustHostCA(directory, host, lines) {
+  const cells = join(directory, "host-ca");
+  await mkdir3(cells, { recursive: true, mode: 448 });
+  await writeAtomic(hostCAPath(directory, host), `${lines.join("\n")}
+`);
+  const trusted = /* @__PURE__ */ new Set();
+  for (const name of (await readdir(cells)).sort()) {
+    if (name.endsWith(".tmp")) {
+      continue;
+    }
+    for (const line of (await readFile4(join(cells, name), "utf8")).split("\n")) {
+      if (line.trim() !== "") {
+        trusted.add(line.trim());
+      }
+    }
+  }
+  await writeAtomic(join(directory, "known_hosts"), `${[...trusted].join("\n")}
+`);
+}
+async function heldUntil(directory, user) {
+  try {
+    const sidecar = JSON.parse(
+      await readFile4(`${certificatePath(directory, user)}.json`, "utf8")
+    );
+    return sidecar.valid_before ? Date.parse(sidecar.valid_before) : 0;
+  } catch {
+    return 0;
+  }
+}
+async function cellRequest(bearer, method, url, body) {
+  for (let attempt = 0; ; attempt++) {
+    const token = await managementBearer(bearer);
+    const response = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+        ...body === void 0 ? {} : { "Content-Type": "application/json" }
+      },
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    if (response.status === 401 && attempt === 0 && isAccountBearer(bearer)) {
+      bearer.invalidate(MANAGEMENT_AUDIENCE);
+      continue;
+    }
+    const answer = await response.json().catch(() => null);
+    if (!response.ok) {
+      throw new Error(
+        `${url} answered ${response.status}${answer?.code ? ` ${answer.code}` : ""}${answer?.detail ? `: ${answer.detail}` : ""}`
+      );
+    }
+    return answer?.data;
+  }
+}
+async function refreshCertificate(bearer, destination, now = Date.now, directory = sshDirectory()) {
+  const key = await ensureKey(directory);
+  const certificate = certificatePath(directory, destination.user);
+  const knownHosts = join(directory, "known_hosts");
+  if (await heldUntil(directory, destination.user) - now() > RENEW_BEFORE_MS && existsSync(hostCAPath(directory, destination.host)) && existsSync(knownHosts)) {
+    return { key, certificate, knownHosts };
+  }
+  const origin = cellOrigin2(destination.host);
+  const publicKey = (await readFile4(`${key}.pub`, "utf8")).trim();
+  const issued = await cellRequest(bearer, "POST", `${origin}/v1/ssh/certificates`, {
+    public_key: publicKey,
+    ttl_seconds: REQUESTED_TTL_SECONDS
+  });
+  if (typeof issued?.certificate !== "string" || typeof issued.valid_before !== "string") {
+    throw new Error(`${origin} answered no certificate`);
+  }
+  await writeAtomic(certificate, `${issued.certificate}
+`);
+  await writeAtomic(
+    `${certificate}.json`,
+    `${JSON.stringify({ valid_before: issued.valid_before })}
+`
+  );
+  const hostCA = await cellRequest(bearer, "GET", `${origin}/v1/ssh/host-ca`);
+  if (!Array.isArray(hostCA?.known_hosts) || hostCA.known_hosts.length === 0) {
+    throw new Error(`${origin} answered no host CA`);
+  }
+  await trustHostCA(directory, destination.host, hostCA.known_hosts);
+  return { key, certificate, knownHosts };
+}
+function sshOptions(paths) {
+  return [
+    "-i",
+    paths.key,
+    "-o",
+    `CertificateFile=${paths.certificate}`,
+    "-o",
+    "IdentitiesOnly=yes",
+    "-o",
+    `UserKnownHostsFile=${paths.knownHosts}`,
+    "-o",
+    "StrictHostKeyChecking=yes"
+  ];
+}
+async function sshCommand(deps, name, command) {
+  let destination;
+  let paths;
+  try {
+    const bearer = await deps.auth.apiKey();
+    const { machine } = await deps.api.getMachineWithEtag(bearer, name);
+    if (machine.kind !== "managed") {
+      throw new Error(`${name} is one of your computers; SSH reaches only Tonbo-run Machines`);
+    }
+    destination = parseDestination(machine.hostnames.ssh);
+    paths = await refreshCertificate(bearer, destination, deps.now);
+  } catch (error) {
+    throw explainMachineError(error);
+  }
+  const target = `${destination.user}@${destination.host}`;
+  const status = await new Promise((resolve, reject) => {
+    const child = spawn("ssh", [...sshOptions(paths), target, ...command], { stdio: "inherit" });
+    child.on(
+      "error",
+      (error) => reject(new Error(`could not run ssh (${error.message}); install an OpenSSH client`))
+    );
+    child.on("exit", (code, signal) => resolve(code ?? (signal ? 255 : 0)));
+  });
+  process.exitCode = status;
+}
+async function sshRefreshCommand(makeDeps, target) {
+  const destination = parseDestination(target);
+  const deps = makeDeps(destination.account);
+  await refreshCertificate(await deps.auth.apiKey(), destination, deps.now);
+}
+function sshConfigText(directory = sshDirectory()) {
+  const home = homedir();
+  const shown = directory.startsWith(home) ? `~${directory.slice(home.length)}` : directory;
+  return [
+    "# Tonbo Machines: append to ~/.ssh/config (tonbo ssh config >> ~/.ssh/config).",
+    "# Then: ssh <name>.<account>@<region>.tonbo.sh, scp, sftp and Remote-SSH work as usual.",
+    `Match host "*.tonbo.sh,tonbo.sh" exec "tonbo ssh refresh %r@%h"`,
+    `  IdentityFile ${shown}/id_ed25519`,
+    `  CertificateFile ${shown}/%r-cert.pub`,
+    "  IdentitiesOnly yes",
+    `  UserKnownHostsFile ${shown}/known_hosts`,
+    "  StrictHostKeyChecking yes",
+    "  ServerAliveInterval 30"
+  ].join("\n");
+}
+async function sshHostCaCommand(deps, options) {
+  const key = await deps.auth.apiKey();
+  const data = await (deps.cell ?? new CellApi(fetch)).json(
+    "getSshHostCa",
+    key,
+    options.region,
+    { params: {} }
+  );
+  print(deps, options.json, data, data.known_hosts.join("\n"));
+}
+async function sshCertificateIssueCommand(deps, options) {
+  const publicKey = (await readFile4(options.publicKey, "utf8")).trim();
+  const key = await deps.auth.apiKey();
+  const data = await (deps.cell ?? new CellApi(fetch)).json(
+    "issueSshCertificate",
+    key,
+    options.region,
+    {
+      params: {},
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        public_key: publicKey,
+        ...options.ttl === void 0 ? {} : { ttl_seconds: options.ttl }
+      })
+    }
+  );
+  print(deps, options.json, data, data.certificate);
+}
+
 // src/app.ts
 var packageVersion = JSON.parse(
-  readFileSync(new URL("../../package.json", import.meta.url), "utf8")
+  readFileSync2(new URL("../../package.json", import.meta.url), "utf8")
 );
 function createDependencies(selection = {}) {
   const api = apiOrigin();
@@ -6132,6 +7072,10 @@ function createProgram(makeDependencies = createDependencies) {
       ).option("--no-database", "bind no database (the default)"),
       false
     ).option(
+      "--secret-env <KEY=FILE>",
+      "read a UTF-8 environment secret from FILE; repeat",
+      repeated
+    ).option("--secret-file <KEY=FILE>", "read binary file secret from FILE; repeat", repeated).option(
       "--idempotency-key <key>",
       "reuse the key of an unconfirmed creation to get the Machine it created"
     ).option("--wait", "wait until the Machine is active, or say why it failed").option("--timeout <seconds>", "how long --wait waits, in seconds", parseWhole),
@@ -6145,6 +7089,29 @@ function createProgram(makeDependencies = createDependencies) {
   ).action(
     async (name, options) => machineShowCommand(dependencies(), name, options)
   );
+  const machineSecret = machine.command("secret").description("manage a Machine's write-only secrets");
+  operationOptions(
+    machineSecret.command("list <name>").description("list secret keys and delivery, never values"),
+    "listMachineSecrets"
+  ).action(
+    async (name, options) => machineSecretListCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    machineSecret.command("set <name> <key>").description(
+      "set a secret from a local file or standard input; applies at the next activation"
+    ).requiredOption("--from <file>", "read the value from FILE, or - for standard input").addOption(
+      new Option("--delivery <mode>", "env or file (binary)").choices(["env", "file"]).default("env")
+    ),
+    "setMachineSecret"
+  ).action(
+    async (name, key, options) => machineSecretSetCommand(dependencies(), name, key, options)
+  );
+  operationOptions(
+    machineSecret.command("unset <name> <key>").description("remove a secret at the next activation"),
+    "unsetMachineSecret"
+  ).action(
+    async (name, key) => machineSecretUnsetCommand(dependencies(), name, key)
+  );
   operationOptions(
     machineSpecOptions(
       machine.command("update <name> [command...]").description(
@@ -6156,6 +7123,59 @@ function createProgram(makeDependencies = createDependencies) {
   ).action(
     async (name, command, options) => machineUpdateCommand(dependencies(), name, command, options)
   );
+  operationOptions(
+    machine.command("exec <name> [command...]").description(
+      "run a command in a Machine, waking it first, and print its output; exits with its status"
+    ).option("--cwd <path>", "the working directory, an absolute path").option(
+      "--env <KEY=VALUE>",
+      "set an environment variable for the command; repeat for several",
+      repeated
+    ).option(
+      "--timeout <seconds>",
+      "kill the command after this many seconds (default 600, at most 3600)",
+      parseWhole
+    ).option("--stdin", "send this process's stdin to the command (at most 1 MiB)").option(
+      "--expect-activation <activation>",
+      "run only in this activation; refuse and wake nothing otherwise"
+    ).option(
+      "--idempotency-key <key>",
+      "a key that makes a repeat answer the first run instead of running again"
+    ),
+    "execMachineCommand"
+  ).action(
+    async (name, command, options) => machineExecCommand(dependencies(), name, command, options)
+  );
+  const file = machine.command("file").description("read, write, stat, list and delete a Machine's files");
+  operationOptions(
+    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, path4, options) => machineFileReadCommand(dependencies(), name, path4, 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, path4, options) => machineFileWriteCommand(dependencies(), name, path4, 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, path4, options) => machineFileStatCommand(dependencies(), name, path4, 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, path4, options) => machineFileListCommand(dependencies(), name, path4, 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, path4, options) => machineFileDeleteCommand(dependencies(), name, path4, options)
+  );
   operationOptions(
     machine.command("sleep <name>").description("put a Machine to sleep now; its next request boots it on its latest spec").option("--if-match <etag>", ifMatchHelp("put to sleep")).option("--wait", "wait until the Machine is asleep").option("--timeout <seconds>", "how long --wait waits, in seconds", parseWhole),
     "sleepMachine"
@@ -6223,6 +7243,31 @@ function createProgram(makeDependencies = createDependencies) {
     ),
     "getUsageToday"
   ).action(async (options) => usageTodayCommand(dependencies(), options));
+  const ssh = program.command("ssh").description("open a terminal on a Machine, or run a command there, over SSH").argument("<machine>", "the Machine's name").argument("[command...]", "a command to run instead of a shell, after --").action(async (name, command) => sshCommand(dependencies(), name, command));
+  ssh.command("config").description(
+    "print the ssh_config block that lets ssh, scp, sftp and Remote-SSH reach every Machine"
+  ).action(() => dependencies().output(sshConfigText()));
+  ssh.command("refresh").argument("<destination>", "a Machine's SSH destination, <name>.<account>@<host>").description(
+    "renew the SSH certificate of <name>.<account>@<host> when it is about to expire (ssh_config's Match exec runs it)"
+  ).action(
+    async (destination) => sshRefreshCommand((account2) => makeDependencies({ account: account2 }), destination)
+  );
+  operationOptions(
+    ssh.command("host-ca").description("print the known_hosts lines that trust Tonbo's SSH hosts").requiredOption("--region <region>", "the region whose cell origin to ask"),
+    "getSshHostCa"
+  ).action(
+    async (options) => sshHostCaCommand(dependencies(), options)
+  );
+  const certificate = ssh.command("certificate").description("SSH certificates of the account for a key of your own");
+  operationOptions(
+    certificate.command("issue").description("sign an SSH public key into a certificate of the account").requiredOption("--region <region>", "the region whose cell origin signs it").requiredOption(
+      "--public-key <file>",
+      "an OpenSSH ssh-ed25519 or ecdsa-sha2-nistp256 public key file"
+    ).option("--ttl <seconds>", "how long to ask for, 300 to 86400", parseWhole),
+    "issueSshCertificate"
+  ).action(
+    async (options) => sshCertificateIssueCommand(dependencies(), options)
+  );
   return applyHelp(program);
 }
 
@@ -6231,5 +7276,5 @@ try {
   await createProgram().parseAsync(process.argv);
 } catch (error) {
   console.error(error instanceof Error ? error.message : error);
-  process.exitCode = 1;
+  if (!process.exitCode) process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "The Tonbo CLI: sign in and manage account resources from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {