@tonbo/cli 0.13.0 → 0.14.0

package/dist/bin/tonbo.js

@@ -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,101 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo machine shapes"
   },
+  "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",
@@ -3141,6 +3247,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)));
@@ -4415,7 +4588,7 @@ 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.",
@@ -4617,7 +4790,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,11 +4881,7 @@ 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(
@@ -5199,6 +5368,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`."
@@ -5581,6 +5754,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 +5839,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 +5991,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,6 +6293,237 @@ 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")
@@ -6156,6 +6924,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 +7044,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 +7077,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.0",
   "description": "The Tonbo CLI: sign in and manage account resources from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {