@tonbo/cli 0.6.1 → 0.7.0

package/README.md

@@ -50,22 +50,29 @@ Every command other than `login` and `logout` calls one operation of the [Manage
 | `tonbo database show <name>` | `getDatabase` | `GET /v1/databases/{name}` |
 | `tonbo database update <name> (--public \| --private)` | `updateDatabase` | `PATCH /v1/databases/{name}` |
 | `tonbo database delete <name> [--yes]` | `deleteDatabase` | `DELETE /v1/databases/{name}` |
-| `tonbo database usage [--period <YYYY-MM>] [--sort list_value\|name] [--prefix <prefix>] [--limit <n>] [--cursor <c>]` | `listDatabaseUsage` | `GET /v1/usage/databases` |
+| `tonbo database usage [--period <YYYY-MM>] [--sort list_value\|name] [--prefix <prefix>] [--names <a,b>] [--limit <n>] [--cursor <c>]` | `listDatabaseUsage` | `GET /v1/usage/databases` |
 | `tonbo usage show [--period <YYYY-MM>]` | `getUsage` | `GET /v1/usage` |
+| `tonbo machine list [--limit <n>] [--cursor <c>]` | `listMachines` | `GET /v1/machines` |
+| `tonbo machine create <name> --image <reference> [--shape <shape>] [--region <region>] [--port <port[:access]>]… [--default-port <port>] [--env <KEY=VALUE>]… [--sleep-after <seconds>] [--idle-action <action>] [--stop-grace <seconds>] [--idempotency-key <key>] [-- <command>…]` | `createMachine` | `POST /v1/machines` |
+| `tonbo machine show <name>` | `getMachine` | `GET /v1/machines/{name}` |
+| `tonbo machine update <name> [--image <reference>] [--image-command] [--shape <shape>] [--port <port[:access]>]… [--clear-ports] [--default-port <port>] [--env <KEY=VALUE>]… [--unset-env <KEY>]… [--sleep-after <seconds>] [--idle-action <action>] [--stop-grace <seconds>] [--discard-snapshot] [--revision <n>] [-- <command>…]` | `updateMachine` | `PATCH /v1/machines/{name}` |
+| `tonbo machine sleep <name>` | `sleepMachine` | `POST /v1/machines/{name}/sleep` |
+| `tonbo machine delete <name> [--yes]` | `deleteMachine` | `DELETE /v1/machines/{name}` |
+| `tonbo machine shapes` | `listMachineShapes` | `GET /v1/machine-shapes` |
 
 ### Output and errors
 
-Every command prints an aligned table or a list of fields for people. With `--json` it prints the answer's `data` exactly as the API returned it, one JSON value on stdout and nothing else there. A list prints one page; when there is another, the CLI writes `More results: run again with --cursor <cursor>` to stderr, so `--json` output stays the API's `data`. `database usage --json` prints the whole answer, since its `other` row, checkpoint and prices belong with the rows. `--limit` asks for up to that many items (the API's default is 50, its maximum 200).
+Every command prints an aligned table or a list of fields for people. With `--json` it prints the answer's `data` exactly as the API returned it, one JSON value on stdout and nothing else there. A list prints one page; when there is another, the CLI writes `More results: run again with --cursor <cursor>` to stderr, so `--json` output stays the API's `data`. `database usage --json` and `machine shapes --json` print the whole answer, since the usage's `other` row, checkpoint and prices, and the default shape, belong with the rows. `--limit` asks for up to that many items (the API's default is 50, its maximum 200).
 
 A refusal prints the problem's detail, the fields a validation error names, and the request's `X-Request-Id` to stderr, and the command exits with status 1. An invalid or expired key adds `Run tonbo login`.
 
 ### Retried creations
 
-`agent create`, `bucket create` and `database create` send an `Idempotency-Key`, a new UUID unless `--idempotency-key` names one. When a creation is not confirmed (the network failed or the server answered 5xx), the CLI prints its key; retrying with that key and the same arguments returns what the first request created instead of creating a second one. `api-key create` has no idempotency key, because a key's secret is never stored and a replay could not return it; a live key's name is unique, so a blind retry is refused with 409 rather than creating a second key.
+`agent create`, `bucket create`, `database create` and `machine create` send an `Idempotency-Key`, a new UUID unless `--idempotency-key` names one. When a creation is not confirmed (the network failed or the server answered 5xx), the CLI prints its key; retrying with that key and the same arguments returns what the first request created instead of creating a second one. `api-key create` has no idempotency key, because a key's secret is never stored and a replay could not return it; a live key's name is unique, so a blind retry is refused with 409 rather than creating a second key.
 
 ### Destructive commands
 
-`api-key revoke`, `bucket delete` and `database delete` ask before they act when stdin and stderr are a terminal: a revocation is confirmed by typing `yes`, a deletion by typing the bucket's or database's name, as in the console. Without a terminal they refuse unless `--yes` is given.
+`api-key revoke`, `bucket delete`, `database delete` and `machine delete` ask before they act when stdin and stderr are a terminal: a revocation is confirmed by typing `yes`, a deletion by typing the bucket's, database's or Machine's name, as in the console. Without a terminal they refuse unless `--yes` is given.
 
 ## Account
 
@@ -124,6 +131,25 @@ Next: npm i @tonbo/sqlite-ursula
 
 `open("notes")` resolves the database through `GET /v1/databases/notes`. It takes its key from, in order, its `apiKey` option, then `TONBO_API_KEY`, then the `tonbo login` credentials file (`key_sources` in `contracts/cli/credentials-v1.json`). A key narrowed to databases reads the databases it reaches there, so an application can be given a narrowed key.
 
+## Machines
+
+```console
+tonbo machine shapes
+tonbo machine create web --image ghcr.io/acme/web:1.4 --port 8080:public --env MODE=prod
+tonbo machine create worker --image python:3.13 -- python -m worker
+tonbo machine update web --env MODE=staging --sleep-after 300
+tonbo machine sleep web
+tonbo machine delete web
+```
+
+A Machine is a VM booted from a public OCI image with a linux/arm64 variant, in one region, with its own database (`contracts/machines/machine-v2.json`). Machines open by invitation: until a region is open for them, every `tonbo machine` command is refused with `region_unavailable`, and the CLI says that nothing was created or changed.
+
+`machine create` resolves the image to its linux/arm64 digest and reserves the Machine's name and its hostnames: `https://<name>-<account>.<region>.tonbo.sh` for the default port, and `<name>.<account>@<region>.tonbo.sh` for SSH. Without `--shape` it takes the shape `machine shapes` marks as the default. `--port <port>` serves a private port (a member's token or SSH) and `--port <port>:public` an open one, which needs the `machines.public` capability; the first port is served at the hostname unless `--default-port` names another. A command after `--` replaces the image's CMD. The answer is the Machine while it is `creating`; `machine show` reports it `active` when it is ready.
+
+`machine update` changes only what its options name. It reads the Machine and writes the change at the revision it read, or at `--revision`, so a change someone made in between is refused with `revision_mismatch` rather than overwritten. `--env` and `--unset-env` change single variables; `--port` replaces every port, naming a public port again keeps its limits, and the current default port stays the default while it is still listed unless `--default-port` names another. Ports and `--sleep-after` apply at once; image, command, shape and env at the Machine's next boot. `machine sleep` puts an awake Machine to sleep now; its next connection wakes it. `machine delete` deletes the Machine with its disk, database and logs, and its name is free for a new Machine at once.
+
+A refusal of machine-v2's `errors` prints the server's detail and then what to do next, for example `machine shapes` for `shape_unavailable` or a shorter name for `hostname_too_long`.
+
 ## Usage
 
 `usage show` prints the account's rated usage of one calendar month in UTC, the current one unless `--period YYYY-MM` names another: one line per product, region, dimension and model with its quantity and amount, and the total, in US dollars.

package/dist/bin/tonbo.js

@@ -544,11 +544,79 @@ var managementOperations = {
       "period",
       "sort",
       "prefix",
+      "names",
       "cursor",
       "limit"
     ],
     "idempotencyKey": false,
     "cli": "tonbo database usage"
+  },
+  "listMachines": {
+    "method": "GET",
+    "path": "/machines",
+    "pathParams": [],
+    "query": [
+      "cursor",
+      "limit"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo machine list"
+  },
+  "createMachine": {
+    "method": "POST",
+    "path": "/machines",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": true,
+    "cli": "tonbo machine create"
+  },
+  "getMachine": {
+    "method": "GET",
+    "path": "/machines/{name}",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo machine show"
+  },
+  "updateMachine": {
+    "method": "PATCH",
+    "path": "/machines/{name}",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo machine update"
+  },
+  "deleteMachine": {
+    "method": "DELETE",
+    "path": "/machines/{name}",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo machine delete"
+  },
+  "sleepMachine": {
+    "method": "POST",
+    "path": "/machines/{name}/sleep",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo machine sleep"
+  },
+  "listMachineShapes": {
+    "method": "GET",
+    "path": "/machine-shapes",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo machine shapes"
   }
 };
 var accountRoles = [
@@ -706,6 +774,14 @@ var credentialsContract = {
     ]
   }
 };
+var machineIdleActions = [
+  "suspend",
+  "release"
+];
+var machinePortAccess = [
+  "private",
+  "public"
+];
 
 // ../../packages/tonbo-cli-core/dist/src/credentials.js
 var DIRECTORY_MODE = Number.parseInt(credentialsContract.permissions.directory_mode, 8);
@@ -1021,7 +1097,7 @@ var ManagementApi = class {
   page(operationId, key, { limit, cursor } = {}, query = {}) {
     return this.request(operationId, key, { query: { ...query, limit, cursor } });
   }
-  async request(operationId, key, { params = {}, query = {}, body, idempotencyKey }) {
+  async request(operationId, key, { params = {}, query = {}, body, idempotencyKey, ifMatch }) {
     const operation = managementOperations[operationId];
     const path2 = operation.path.replace(/\{([^}]+)\}/g, (_, name) => {
       const value = params[name];
@@ -1044,6 +1120,8 @@ var ManagementApi = class {
       headers["content-type"] = "application/json";
     if (idempotencyKey)
       headers["idempotency-key"] = idempotencyKey;
+    if (ifMatch)
+      headers["if-match"] = ifMatch;
     const queryString = search.toString();
     const url = `${this.apiOrigin}${managementApiBasePath}${path2}${queryString ? `?${queryString}` : ""}`;
     try {
@@ -1141,6 +1219,44 @@ var ManagementApi = class {
   getUsage(key, period) {
     return this.call("getUsage", key, { query: { period } });
   }
+  listMachines(key, page) {
+    return this.page("listMachines", key, page);
+  }
+  /** A replay with the same idempotency key returns the Machine the first
+   * request created. */
+  createMachine(key, request, idempotencyKey) {
+    return this.call("createMachine", key, {
+      body: withoutUndefined(request),
+      idempotencyKey
+    }).catch(unconfirmed("Machine creation", idempotencyKey, "the same arguments"));
+  }
+  getMachine(key, name) {
+    return this.call("getMachine", key, { params: { name } });
+  }
+  /** Written only at `revision` (machine-v2 requires If-Match, the Machine's
+   * ETag); a stale one is refused with `revision_mismatch`. */
+  updateMachine(key, name, revision, change) {
+    return this.call("updateMachine", key, {
+      params: { name },
+      body: withoutUndefined(change),
+      ifMatch: `"${revision}"`
+    });
+  }
+  sleepMachine(key, name) {
+    return this.call("sleepMachine", key, { params: { name } });
+  }
+  /** The Machine being deleted, or null when the API answered 204: the
+   * name's create never reached its region, and only the name was released. */
+  async deleteMachine(key, name) {
+    const answer = await this.request("deleteMachine", key, {
+      params: { name }
+    });
+    return answer?.data ?? null;
+  }
+  /** The whole answer: the shapes and the default one. */
+  listMachineShapes(key) {
+    return this.request("listMachineShapes", key, {});
+  }
 };
 function withoutUndefined(value) {
   return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0));
@@ -1819,7 +1935,7 @@ async function databaseUsageCommand(deps, options = {}) {
   const usage = await deps.api.listDatabaseUsage(
     await deps.auth.apiKey(),
     { limit: options.limit, cursor: options.cursor },
-    { period: options.period, sort: options.sort, prefix: options.prefix }
+    { period: options.period, sort: options.sort, prefix: options.prefix, names: options.names }
   );
   if (options.json) deps.output(JSON.stringify(usage));
   else
@@ -1877,6 +1993,283 @@ async function usageShowCommand(deps, options = {}) {
   );
 }
 
+// src/machine.ts
+import { randomUUID as randomUUID3 } from "node:crypto";
+var MACHINE_ERROR_HINTS = {
+  region_unavailable: "Machines are not open there yet, or that region cannot be reached from here; nothing was created or changed.",
+  name_taken: "Choose another name; `tonbo machine list` shows the account's Machines.",
+  hostname_taken: "The hostname <name>-<account> is held by another Machine or account; choose another name.",
+  hostname_too_long: "<name>-<account> must fit one hostname label; choose a shorter name.",
+  account_name_unclaimed: "Claim a Tonbo ID for the account on the console's Profile page, then run the command again.",
+  image_platform_unsupported: "Machines run linux/arm64: publish the image for that platform (for example `docker buildx build --platform linux/arm64`).",
+  shape_unavailable: "`tonbo machine shapes` lists the shapes a Machine may name now.",
+  port_reserved: "Serve the application on another port.",
+  revision_mismatch: "The Machine changed since it was read; `tonbo machine show` it and run the update again.",
+  snapshot_would_be_discarded: "Pass --discard-snapshot to apply the change at the next boot, which then starts fresh.",
+  database_limit_reached: "Each Machine counts one database: delete a Machine or a database (`tonbo database list`) 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."
+};
+function explainMachineError(error) {
+  if (!(error instanceof HttpError) || error.code === null) return error;
+  const hint = MACHINE_ERROR_HINTS[error.code];
+  if (!hint) return error;
+  return new HttpError(`${error.message}
+${hint}`, error.status, error.body, error.requestId);
+}
+async function machineCommand(run) {
+  try {
+    return await run();
+  } catch (error) {
+    throw explainMachineError(error);
+  }
+}
+function portText(port) {
+  return `${port.port} ${port.access}${port.default ? " (default)" : ""}`;
+}
+function machinePortsText(machine) {
+  return machine.ports.length ? machine.ports.map(portText).join(", ") : "none";
+}
+function idleActionText(machine) {
+  const { action, reason } = machine.status.sleep;
+  if (action === machine.idle_action) return action;
+  return `${action} (${machine.idle_action} requested; ${reason.replaceAll("_", " ")})`;
+}
+function machineState(machine) {
+  return machine.failure ? `${machine.state}: ${machine.failure.code}: ${machine.failure.message}` : machine.state;
+}
+function machineFields(machine) {
+  return fields([
+    ["Name", machine.name],
+    ["ID", machine.id],
+    ["Region", machine.region],
+    ["State", machineState(machine)],
+    ["Power", machine.status.power],
+    ["Shape", machine.shape],
+    ["Image", `${machine.image.reference} (${machine.image.digest})`],
+    ["Command", machine.command ? machine.command.join(" ") : "the image's own"],
+    ["Ports", machinePortsText(machine)],
+    ["HTTPS", machine.hostnames.https],
+    ["SSH", machine.hostnames.ssh],
+    ["Env", Object.keys(machine.env).sort().join(", ") || "none"],
+    ["Sleep after", `${machine.sleep_after_seconds}s without a connection`],
+    ["Idle action", idleActionText(machine)],
+    ["Stop grace", `${machine.stop_grace_seconds}s`],
+    ["Database", machine.database.name],
+    ["Revision", String(machine.revision)],
+    ["Created", machine.created_at],
+    ["Updated", machine.updated_at]
+  ]);
+}
+function parsePorts(specs, current) {
+  const accesses = machinePortAccess;
+  return specs.map((spec) => {
+    const match = /^([0-9]{1,5})(?::([a-z]+))?$/.exec(spec);
+    const access = match?.[2] ?? "private";
+    if (!match || !accesses.includes(access))
+      throw new Error(
+        `--port ${spec}: give <port> or <port>:<access>, access ${accesses.join(" or ")}.`
+      );
+    const port = Number(match[1]);
+    const before = current.find((entry) => entry.port === port && entry.access === access);
+    return {
+      port,
+      access,
+      default: false,
+      ...before?.public_limits === void 0 ? {} : { public_limits: before.public_limits }
+    };
+  });
+}
+function withDefault(ports, defaultPort) {
+  if (ports.length === 0) {
+    if (defaultPort !== void 0) throw new Error("--default-port needs a port to choose.");
+    return ports;
+  }
+  const chosen = defaultPort ?? ports[0].port;
+  if (!ports.some((entry) => entry.port === chosen))
+    throw new Error(`--default-port ${chosen} is not one of the Machine's ports.`);
+  return ports.map((entry) => ({ ...entry, default: entry.port === chosen }));
+}
+function parseEnv(pairs) {
+  const env = {};
+  for (const pair of pairs) {
+    const split = pair.indexOf("=");
+    if (split < 1) throw new Error(`--env ${pair}: give KEY=VALUE.`);
+    env[pair.slice(0, split)] = pair.slice(split + 1);
+  }
+  return env;
+}
+async function machineListCommand(deps, options = {}) {
+  await machineCommand(async () => {
+    const page = await deps.api.listMachines(await deps.auth.apiKey(), {
+      limit: options.limit,
+      cursor: options.cursor
+    });
+    printPage(
+      deps,
+      options.json,
+      page,
+      (machines) => machines.length ? table(
+        ["NAME", "REGION", "STATE", "POWER", "SHAPE", "IMAGE", "HTTPS"],
+        machines.map((machine) => [
+          machine.name,
+          machine.region,
+          machine.state,
+          machine.status.power,
+          machine.shape,
+          machine.image.reference,
+          machine.hostnames.https
+        ])
+      ) : "No Machines."
+    );
+    if (page.unavailable_regions.length)
+      deps.notice(
+        `Could not read the Machines in ${page.unavailable_regions.join(", ")}; they are missing from this list.`
+      );
+  });
+}
+async function machineCreateCommand(deps, name, command, options = {}) {
+  await machineCommand(async () => {
+    if (!options.image) throw new Error("Pass --image <reference>.");
+    const env = parseEnv(options.env ?? []);
+    const ports = withDefault(parsePorts(options.port ?? [], []), options.defaultPort);
+    const key = await deps.auth.apiKey();
+    const shape = options.shape ?? (await deps.api.listMachineShapes(key)).default;
+    const machine = await deps.api.createMachine(
+      key,
+      {
+        name,
+        image: options.image,
+        shape,
+        region: options.region,
+        command: command.length ? command : void 0,
+        ports: ports.length ? ports : void 0,
+        env: Object.keys(env).length ? env : void 0,
+        sleep_after_seconds: options.sleepAfter,
+        idle_action: options.idleAction,
+        stop_grace_seconds: options.stopGrace
+      },
+      options.idempotencyKey ?? randomUUID3()
+    );
+    print(
+      deps,
+      options.json,
+      machine,
+      [
+        machine.state === "active" ? `Created Machine ${machine.name}.` : `Machine ${machine.name} is being created; \`tonbo machine show ${machine.name}\` reports it active when it is ready.`,
+        machineFields(machine)
+      ].join("\n")
+    );
+  });
+}
+async function machineShowCommand(deps, name, options = {}) {
+  await machineCommand(async () => {
+    const machine = await deps.api.getMachine(await deps.auth.apiKey(), name);
+    print(deps, options.json, machine, machineFields(machine));
+  });
+}
+async function machineUpdateCommand(deps, name, command, options = {}) {
+  await machineCommand(async () => {
+    if (command.length && options.imageCommand)
+      throw new Error("Give a command or --image-command, not both.");
+    if (options.clearPorts && (options.port?.length || options.defaultPort !== void 0))
+      throw new Error("Give --port or --clear-ports, not both.");
+    const key = await deps.auth.apiKey();
+    const current = await deps.api.getMachine(key, name);
+    const change = {
+      image: options.image,
+      shape: options.shape,
+      command: options.imageCommand ? null : command.length ? command : void 0,
+      sleep_after_seconds: options.sleepAfter,
+      idle_action: options.idleAction,
+      stop_grace_seconds: options.stopGrace
+    };
+    if (options.clearPorts) change.ports = [];
+    else if (options.port?.length) {
+      const ports = parsePorts(options.port, current.ports);
+      const kept = current.ports.find((entry) => entry.default)?.port;
+      const defaultPort = options.defaultPort ?? (ports.some((entry) => entry.port === kept) ? kept : void 0);
+      change.ports = withDefault(ports, defaultPort);
+    } else if (options.defaultPort !== void 0)
+      change.ports = withDefault(current.ports, options.defaultPort);
+    if (options.env?.length || options.unsetEnv?.length) {
+      const env = { ...current.env, ...parseEnv(options.env ?? []) };
+      for (const variable of options.unsetEnv ?? []) delete env[variable];
+      change.env = env;
+    }
+    if (options.discardSnapshot) change.discard_snapshot = true;
+    if (Object.values(change).every((value) => value === void 0))
+      throw new Error("Nothing to change: pass at least one option or a command.");
+    const machine = await deps.api.updateMachine(
+      key,
+      name,
+      options.revision ?? current.revision,
+      change
+    );
+    print(
+      deps,
+      options.json,
+      machine,
+      [
+        `Updated Machine ${machine.name} to revision ${machine.revision}. Ports and sleep-after apply now; image, command, shape and env at its next boot.`,
+        machineFields(machine)
+      ].join("\n")
+    );
+  });
+}
+async function machineSleepCommand(deps, name, options = {}) {
+  await machineCommand(async () => {
+    const machine = await deps.api.sleepMachine(await deps.auth.apiKey(), name);
+    print(
+      deps,
+      options.json,
+      machine,
+      `Machine ${machine.name} is going to sleep (${machine.status.sleep.action}); its next connection wakes it.`
+    );
+  });
+}
+async function machineDeleteCommand(deps, name, options = {}) {
+  await machineCommand(async () => {
+    await confirm(
+      deps,
+      options.yes,
+      `delete Machine ${name}`,
+      () => Promise.resolve(
+        `Delete Machine ${name} with its disk, database and logs? This cannot be undone. Type the Machine's name to confirm:`
+      ),
+      name
+    );
+    const machine = await deps.api.deleteMachine(await deps.auth.apiKey(), name);
+    print(
+      deps,
+      options.json,
+      machine,
+      machine ? `Machine ${machine.name} is being deleted; its name is free for a new Machine.` : `Released the name ${name}; no Machine had been created under it.`
+    );
+  });
+}
+async function machineShapesCommand(deps, options = {}) {
+  await machineCommand(async () => {
+    const shapes = await deps.api.listMachineShapes(await deps.auth.apiKey());
+    print(
+      deps,
+      options.json,
+      shapes,
+      table(
+        ["SHAPE", "VCPUS", "MEMORY", "SCRATCH", "OFFERED", "SUSPENDABLE"],
+        shapes.data.map((shape) => [
+          shape.shape === shapes.default ? `${shape.shape} (default)` : shape.shape,
+          String(shape.vcpus),
+          `${shape.memory_gib} GiB`,
+          `${shape.scratch_gib} GiB`,
+          shape.offered ? "yes" : "no",
+          shape.suspendable ? "yes" : "no"
+        ])
+      )
+    );
+  });
+}
+
 // src/prompt.ts
 import select from "@inquirer/select";
 import { createInterface } from "node:readline/promises";
@@ -1925,6 +2318,10 @@ function parseLimit(value) {
   if (!/^[1-9][0-9]*$/.test(value)) throw new InvalidArgumentError("Not a positive integer.");
   return Number(value);
 }
+function parseWhole(value) {
+  if (!/^[0-9]+$/.test(value)) throw new InvalidArgumentError("Not a whole number.");
+  return Number(value);
+}
 function operationOptions(command, operationId) {
   const query = managementOperations[operationId].query;
   if (query.includes("limit"))
@@ -1935,6 +2332,34 @@ function operationOptions(command, operationId) {
 }
 var repeated = (value, previous = []) => [...previous, value];
 var roleOption = (description) => new Option("--role <role>", description).choices(accountRoles);
+function machineSpecOptions(command, update) {
+  const later = update ? "; applies at the next boot" : "";
+  return command.option("--shape <shape>", `the Machine's size (see tonbo machine shapes)${later}`).option(
+    "--port <port[:access]>",
+    `a port the Machine serves, private (the default) or public; repeat for several${update ? "; replaces every port" : ""}`,
+    repeated
+  ).option(
+    "--default-port <port>",
+    `the port served at the Machine's hostname without a port prefix; the first --port by default${update ? ", or the current default while --port still lists it" : ""}`,
+    parseWhole
+  ).option(
+    "--env <KEY=VALUE>",
+    `a non-secret environment variable; repeat for several${later}`,
+    repeated
+  ).option(
+    "--sleep-after <seconds>",
+    "how long the Machine stays awake without a connection",
+    parseWhole
+  ).addOption(
+    new Option("--idle-action <action>", "what sleeping does to the Machine").choices(
+      machineIdleActions
+    )
+  ).option(
+    "--stop-grace <seconds>",
+    "the seconds between SIGTERM and SIGKILL on a planned stop",
+    parseWhole
+  );
+}
 function createProgram(dependencies = createDependencies) {
   const program = new Command().name("tonbo").description("Sign in to Tonbo and manage account resources.").version(packageVersion.version);
   program.command("login").description("sign in through the browser and save a personal key for this computer").option("--account <name>", "the account to log in to; defaults to your personal account").action(async (options) => loginCommand(dependencies(), options));
@@ -2098,11 +2523,72 @@ function createProgram(dependencies = createDependencies) {
           throw new InvalidArgumentError(error.message);
         }
       }
-    ).option("--prefix <prefix>", "only databases whose name starts with this"),
+    ).option("--prefix <prefix>", "only databases whose name starts with this").option("--names <names>", "only these databases, up to 100 names, comma-separated"),
     "listDatabaseUsage"
   ).action(
     async (options) => databaseUsageCommand(dependencies(), options)
   );
+  const machine = program.command("machine").description("the account's Machines");
+  operationOptions(
+    machine.command("list").description("list the Machines in every region"),
+    "listMachines"
+  ).action(
+    async (options) => machineListCommand(dependencies(), options)
+  );
+  operationOptions(
+    machineSpecOptions(
+      machine.command("create <name> [command...]").description(
+        "create a Machine from a public linux/arm64 image; [command...] after -- replaces the image's CMD"
+      ).requiredOption("--image <reference>", "the public OCI image the Machine boots").option(
+        "--region <region>",
+        "the Machine's region, fixed for its life; the account's default region by default"
+      ),
+      false
+    ).option(
+      "--idempotency-key <key>",
+      "reuse the key of an unconfirmed creation to get the Machine it created"
+    ),
+    "createMachine"
+  ).action(
+    async (name, command, options) => machineCreateCommand(dependencies(), name, command, options)
+  );
+  operationOptions(
+    machine.command("show <name>").description("show a Machine, its hostnames and its state"),
+    "getMachine"
+  ).action(
+    async (name, options) => machineShowCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    machineSpecOptions(
+      machine.command("update <name> [command...]").description(
+        "change a Machine; [command...] after -- replaces its command at the next boot"
+      ).option("--image <reference>", "a new image; applies at the next boot").option("--image-command", "run the image's own CMD again at the next boot").option("--unset-env <KEY>", "remove an environment variable; repeat for several", repeated).option("--clear-ports", "remove every port").option(
+        "--revision <revision>",
+        "write only if the Machine is still at this revision (tonbo machine show); the revision it reads by default",
+        parseWhole
+      ).option("--discard-snapshot", "apply a change that discards the Machine's snapshot"),
+      true
+    ),
+    "updateMachine"
+  ).action(
+    async (name, command, options) => machineUpdateCommand(dependencies(), name, command, options)
+  );
+  operationOptions(
+    machine.command("sleep <name>").description("put a Machine to sleep now"),
+    "sleepMachine"
+  ).action(
+    async (name, options) => machineSleepCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    machine.command("delete <name>").description("delete a Machine with its disk, database and logs").option("--yes", "delete without asking; required when stdin is not a terminal"),
+    "deleteMachine"
+  ).action(
+    async (name, options) => machineDeleteCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    machine.command("shapes").description("list the shapes a Machine may have"),
+    "listMachineShapes"
+  ).action(async (options) => machineShapesCommand(dependencies(), options));
   operationOptions(
     program.command("usage").description("the account's rated usage").command("show").description("show one month's rated usage").option(
       "--period <month>",

package/package.json

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