@tonbo/cli 0.6.0 → 0.7.0

package/dist/bin/tonbo.js

@@ -8,7 +8,7 @@ import { readFileSync } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { execFile } from "node:child_process";
-import os from "node:os";
+import os2 from "node:os";
 import { promisify } from "node:util";
 
 // ../../packages/tonbo-cli-core/dist/src/callback-page.js
@@ -177,178 +177,11 @@ async function requestJson(fetcher, url, init = {}) {
   throw new HttpError(requestId ? `${message} (request ${requestId})` : message, response.status, body, requestId);
 }
 
-// ../../packages/tonbo-cli-core/dist/src/auth.js
-var exec = promisify(execFile);
-var DEFAULT_LOGIN_HINT = "tonbo login";
-var LOOPBACK_HOST = "127.0.0.1";
-function loginHostname(hostname = os.hostname()) {
-  const cleaned = hostname.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 64);
-  return cleaned || "computer";
-}
-var AuthClient = class {
-  credentials;
-  fetcher;
-  loginOrigin;
-  browserOpener;
-  hostname;
-  loginHint;
-  constructor(credentials, fetcher, loginOrigin2 = "https://tonbo.dev", browserOpener = openBrowser, hostname = loginHostname(), loginHint = DEFAULT_LOGIN_HINT) {
-    this.credentials = credentials;
-    this.fetcher = fetcher;
-    this.loginOrigin = loginOrigin2;
-    this.browserOpener = browserOpener;
-    this.hostname = hostname;
-    this.loginHint = loginHint;
-  }
-  /** The personal key requests are made with: TONBO_API_KEY, or the saved
-   * login while it has not expired. */
-  async apiKey() {
-    const injected = process.env.TONBO_API_KEY?.trim();
-    if (injected)
-      return injected;
-    const login = await this.credentials.load();
-    if (!login)
-      throw new Error(`Not logged in. Run \`${this.loginHint}\`.`);
-    if (login.expires_at && Date.parse(login.expires_at) <= Date.now())
-      throw new Error(`Your Tonbo login has expired. Run \`${this.loginHint}\`.`);
-    return login.key;
-  }
-  /**
-   * The browser handoff of /cli/login: PKCE S256 with a loopback redirect on
-   * a free port, then the one-time code is redeemed for a personal key named
-   * "CLI on <hostname>", which replaces that host's earlier login key.
-   */
-  async login(progress = () => {
-  }, account) {
-    const verifier = randomBytes(48).toString("base64url");
-    const challenge = createHash("sha256").update(verifier).digest("base64url");
-    const state = randomBytes(24).toString("base64url");
-    const code = await this.listenForCode(state, (redirectUri) => {
-      const authorization = new URL("/cli/login", this.loginOrigin);
-      authorization.search = new URLSearchParams({
-        code_challenge: challenge,
-        code_challenge_method: "S256",
-        redirect_uri: redirectUri,
-        state,
-        hostname: this.hostname,
-        ...account ? { account } : {}
-      }).toString();
-      return this.browserOpener(authorization.toString());
-    }, progress);
-    progress({ status: "started", step: "key-redemption" });
-    const redeemed = await requestJson(this.fetcher, new URL("/api/cli/login/token", this.loginOrigin).toString(), {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ code, code_verifier: verifier })
-    });
-    progress({ status: "completed", step: "key-redemption" });
-    const login = {
-      version: 1,
-      account_id: redeemed.account_id,
-      key_id: redeemed.api_key.id,
-      key: redeemed.key,
-      expires_at: redeemed.api_key.expires_at
-    };
-    progress({ status: "started", step: "credential-store" });
-    await this.credentials.save(login);
-    progress({ status: "completed", step: "credential-store" });
-    return login;
-  }
-  listenForCode(expectedState, ready, progress) {
-    return new Promise((resolve, reject) => {
-      let settled = false;
-      const sockets = /* @__PURE__ */ new Set();
-      let authorizationStarted = false;
-      const startAuthorization = () => {
-        if (authorizationStarted)
-          return;
-        authorizationStarted = true;
-        progress({ status: "completed", step: "browser" });
-        progress({ status: "started", step: "browser-authorization" });
-      };
-      const finish = (result, completedResponseSocket) => {
-        if (settled)
-          return;
-        settled = true;
-        clearTimeout(timeout);
-        const complete = (closeError) => {
-          if (closeError)
-            reject(closeError);
-          else if ("code" in result) {
-            progress({ status: "completed", step: "callback-close" });
-            resolve(result.code);
-          } else
-            reject(result.error);
-        };
-        if ("code" in result)
-          progress({ status: "started", step: "callback-close" });
-        if (!server.listening) {
-          complete();
-          return;
-        }
-        server.close(complete);
-        for (const socket of sockets) {
-          if (socket !== completedResponseSocket)
-            socket.destroy();
-        }
-        server.closeIdleConnections();
-      };
-      const timeout = setTimeout(() => {
-        finish({ error: new Error("Timed out waiting for browser login.") });
-      }, 5 * 60 * 1e3);
-      const server = createServer((request, response) => {
-        const url = new URL(request.url ?? "/", `http://${LOOPBACK_HOST}`);
-        if (url.pathname !== "/callback" || url.searchParams.get("state") !== expectedState) {
-          respond(response, "invalid");
-          return;
-        }
-        const denied = url.searchParams.get("error");
-        if (denied) {
-          const responseSocket2 = response.socket;
-          respond(response, "denied", () => finish({ error: new Error(`The login was not approved (${denied}).`) }, responseSocket2));
-          return;
-        }
-        const code = url.searchParams.get("code");
-        if (!code) {
-          respond(response, "invalid");
-          return;
-        }
-        startAuthorization();
-        progress({ status: "completed", step: "browser-authorization" });
-        const responseSocket = response.socket;
-        respond(response, "complete", () => finish({ code }, responseSocket));
-      });
-      server.on("connection", (socket) => {
-        sockets.add(socket);
-        socket.once("close", () => sockets.delete(socket));
-      });
-      server.once("error", (error) => finish({ error }));
-      progress({ status: "started", step: "callback-server" });
-      server.listen(0, LOOPBACK_HOST, () => {
-        const { port } = server.address();
-        progress({ status: "completed", step: "callback-server" });
-        progress({ status: "started", step: "browser" });
-        void ready(`http://${LOOPBACK_HOST}:${port}/callback`).then(startAuthorization).catch((error) => finish({
-          error: error instanceof Error ? error : new Error("Could not open the login browser.")
-        }));
-      });
-    });
-  }
-};
-function respond(response, outcome, finished) {
-  const page = callbackResponse(outcome);
-  if (finished)
-    response.once("finish", finished);
-  response.writeHead(page.status, { ...page.headers, connection: "close" });
-  response.end(page.body);
-}
-async function openBrowser(url) {
-  if (process.platform === "darwin")
-    return void await exec("open", [url]);
-  if (process.platform === "win32")
-    return void await exec("rundll32", ["url.dll,FileProtocolHandler", url]);
-  return void await exec("xdg-open", [url]);
-}
+// ../../packages/tonbo-cli-core/dist/src/credentials.js
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 
 // ../../packages/tonbo-cli-core/dist/src/generated/contracts.js
 var agentNameContract = {
@@ -711,25 +544,538 @@ 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 = [
+  "owner",
+  "admin",
+  "member"
+];
+var apiKeyExpirations = [
+  "15_days",
+  "1_month",
+  "6_months",
+  "1_year",
+  "never"
+];
+var credentialsContract = {
+  "version": 1,
+  "description": "The login `tonbo login` (and `yield login`) saves: a personal key of one account. @tonbo/cli-core writes and reads it; other readers, such as @tonbo/sqlite-ursula/tonbo, follow `reader`.",
+  "path": {
+    "description": "`${XDG_CONFIG_HOME}/tonbo/credentials.json` when XDG_CONFIG_HOME is set and not empty, else `${HOME}/.config/tonbo/credentials.json`.",
+    "base_env": "XDG_CONFIG_HOME",
+    "fallback_base": [
+      "$HOME",
+      ".config"
+    ],
+    "relative": [
+      "tonbo",
+      "credentials.json"
+    ]
+  },
+  "permissions": {
+    "description": "POSIX only; a reader on Windows skips the mode checks.",
+    "directory_mode": "0700",
+    "file_mode": "0600",
+    "writer": "The writer creates the directory 0700, writes a temporary file 0600 beside the target, syncs it and renames it over the target, so a crash never leaves a partial key. It refuses to replace or remove a symlink or anything that is not a regular file."
+  },
+  "key_sources": {
+    "description": "Where a client takes its key, first match wins. A library takes an explicit option first; the CLIs have none.",
+    "order": [
+      "option",
+      "env",
+      "file"
+    ],
+    "env": "TONBO_API_KEY"
+  },
+  "reader": {
+    "missing": "No file is not logged in: ask the person to run `tonbo login`.",
+    "refuse_symlink": true,
+    "refuse_non_regular_file": true,
+    "refuse_mode_bits": "0077",
+    "refused": "A symlink, a non-regular file, or a file any group or other permission bit is set on is an error and is never read; do not fall back to another source.",
+    "unknown_version": "A `version` other than `current_version`, or content that does not match `schema`, is unusable: ask the person to run `tonbo login`. It is never migrated.",
+    "expired": "A login whose `expires_at` is at or before now is expired: ask the person to run `tonbo login`. `expires_at: null` never expires.",
+    "login_hint": "tonbo login"
+  },
+  "current_version": 1,
+  "schema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://tonbo.dev/contracts/cli/credentials-v1.json",
+    "title": "Tonbo CLI login",
+    "type": "object",
+    "required": [
+      "version",
+      "account_id",
+      "key_id",
+      "key",
+      "expires_at"
+    ],
+    "additionalProperties": true,
+    "properties": {
+      "version": {
+        "const": 1
+      },
+      "account_id": {
+        "type": "string",
+        "minLength": 1,
+        "description": "The account the key belongs to (a UUID)."
+      },
+      "key_id": {
+        "type": "string",
+        "minLength": 1,
+        "description": "The key's id, its `client_id` at the exchange (a UUID)."
+      },
+      "key": {
+        "type": "string",
+        "pattern": "^tbo_",
+        "description": "The personal key's secret (contracts/iam/access-token-v1.json `personal_key`)."
+      },
+      "expires_at": {
+        "type": [
+          "string",
+          "null"
+        ],
+        "format": "date-time",
+        "description": "When the key expires, ISO 8601; null for a key that never expires."
+      }
+    }
+  },
+  "examples": {
+    "usable": [
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": "2027-04-24T00:00:00.000Z"
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null
+      }
+    ],
+    "unusable": [
+      {
+        "access_token": "access",
+        "refresh_token": "refresh",
+        "token_type": "bearer"
+      },
+      {
+        "version": 2,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "not-a-personal-key",
+        "expires_at": null
+      },
+      {
+        "version": 1,
+        "account_id": "",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": null
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret",
+        "expires_at": "not a date"
+      },
+      {
+        "version": 1,
+        "account_id": "10000000-0000-4000-8000-000000000001",
+        "key_id": "20000000-0000-4000-8000-000000000002",
+        "key": "tbo_secret"
+      }
+    ]
+  }
+};
+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);
+var FILE_MODE = Number.parseInt(credentialsContract.permissions.file_mode, 8);
+var REFUSED_MODE_BITS = Number.parseInt(credentialsContract.reader.refuse_mode_bits, 8);
+function defaultCredentialsPath(env = process.env) {
+  const rule = credentialsContract.path;
+  const base = env[rule.base_env] || path.join(...rule.fallback_base.map((part) => part === "$HOME" ? os.homedir() : part));
+  return path.join(base, ...rule.relative);
+}
+function isExpiredLogin(login, now = Date.now()) {
+  return login.expires_at !== null && Date.parse(login.expires_at) <= now;
+}
+var UnusableLoginError = class extends Error {
+};
+var FileCredentialStore = class {
+  filename;
+  loginHint;
+  constructor(filename = defaultCredentialsPath(), loginHint = credentialsContract.reader.login_hint) {
+    this.filename = filename;
+    this.loginHint = loginHint;
+  }
+  async load() {
+    let parsed;
+    try {
+      await assertPrivateRegularFile(this.filename);
+      parsed = JSON.parse(await readFile(this.filename, "utf8"));
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return null;
+      throw new Error(`Could not read Tonbo credentials at ${this.filename}.`, { cause: error });
+    }
+    if (!isStoredLogin(parsed))
+      throw new UnusableLoginError(`The saved login at ${this.filename} is not usable by this CLI. Run \`${this.loginHint}\`.`);
+    return parsed;
+  }
+  async save(login) {
+    if (!isStoredLogin(login))
+      throw new Error("Refusing to store a malformed Tonbo login.");
+    const directory = path.dirname(this.filename);
+    await mkdir(directory, { mode: DIRECTORY_MODE, recursive: true });
+    await preparePrivateDirectory(directory);
+    await assertExistingDestinationIsSafe(this.filename);
+    const temporary = path.join(directory, `.${path.basename(this.filename)}.${process.pid}.${randomUUID()}.tmp`);
+    let handle = null;
+    try {
+      handle = await open(temporary, "wx", FILE_MODE);
+      await handle.writeFile(`${JSON.stringify(login, null, 2)}
+`, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      if (process.platform !== "win32")
+        await chmod(temporary, FILE_MODE);
+      await rename(temporary, this.filename);
+    } catch (error) {
+      await handle?.close().catch(() => void 0);
+      await rm(temporary, { force: true }).catch(() => void 0);
+      throw new Error(`Could not store Tonbo credentials at ${this.filename}.`, { cause: error });
+    }
+  }
+  async remove() {
+    await assertExistingDestinationIsSafe(this.filename);
+    await rm(this.filename, { force: true });
+  }
+};
+var RULE_KEYWORDS = /* @__PURE__ */ new Set(["const", "type", "minLength", "pattern", "format", "description"]);
+function matchesRule(value, rule) {
+  if (Object.keys(rule).some((keyword) => !RULE_KEYWORDS.has(keyword)))
+    return false;
+  if ("const" in rule)
+    return value === rule.const;
+  const types = typeof rule.type === "string" ? [rule.type] : rule.type ?? [];
+  if (value === null)
+    return types.includes("null");
+  if (typeof value !== "string" || !types.includes("string"))
+    return false;
+  if (rule.minLength !== void 0 && value.length < rule.minLength)
+    return false;
+  if (rule.pattern !== void 0 && !new RegExp(rule.pattern, "u").test(value))
+    return false;
+  if (rule.format === "date-time" && Number.isNaN(Date.parse(value)))
+    return false;
+  return true;
+}
+function isStoredLogin(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const login = value;
+  const schema = credentialsContract.schema;
+  if (login.version !== credentialsContract.current_version)
+    return false;
+  if (!schema.required.every((name) => Object.hasOwn(login, name)))
+    return false;
+  const properties = schema.properties;
+  return Object.entries(properties).every(([name, rule]) => !Object.hasOwn(login, name) || matchesRule(login[name], rule));
+}
+async function preparePrivateDirectory(directory) {
+  const stat = await lstat(directory);
+  if (stat.isSymbolicLink() || !stat.isDirectory())
+    throw new Error("Tonbo config directory must be a real directory.");
+  if (process.platform !== "win32")
+    await chmod(directory, DIRECTORY_MODE);
+}
+async function assertExistingDestinationIsSafe(filename) {
+  try {
+    const stat = await lstat(filename);
+    if (stat.isSymbolicLink() || !stat.isFile())
+      throw new Error("Tonbo credential path must be a regular file.");
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+}
+async function assertPrivateRegularFile(filename) {
+  const stat = await lstat(filename);
+  if (stat.isSymbolicLink() || !stat.isFile())
+    throw new Error("Tonbo credential path must be a regular file.");
+  if (process.platform !== "win32" && (stat.mode & REFUSED_MODE_BITS) !== 0)
+    throw new Error(`Tonbo credential file must have mode ${credentialsContract.permissions.file_mode}.`);
+}
+
+// ../../packages/tonbo-cli-core/dist/src/auth.js
+var exec = promisify(execFile);
+var DEFAULT_LOGIN_HINT = credentialsContract.reader.login_hint;
+var LOOPBACK_HOST = "127.0.0.1";
+function loginHostname(hostname = os2.hostname()) {
+  const cleaned = hostname.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 64);
+  return cleaned || "computer";
+}
+var AuthClient = class {
+  credentials;
+  fetcher;
+  loginOrigin;
+  browserOpener;
+  hostname;
+  loginHint;
+  constructor(credentials, fetcher, loginOrigin2 = "https://tonbo.dev", browserOpener = openBrowser, hostname = loginHostname(), loginHint = DEFAULT_LOGIN_HINT) {
+    this.credentials = credentials;
+    this.fetcher = fetcher;
+    this.loginOrigin = loginOrigin2;
+    this.browserOpener = browserOpener;
+    this.hostname = hostname;
+    this.loginHint = loginHint;
+  }
+  /** The personal key requests are made with: TONBO_API_KEY, or the saved
+   * login while it has not expired. */
+  async apiKey() {
+    const injected = process.env.TONBO_API_KEY?.trim();
+    if (injected)
+      return injected;
+    const login = await this.credentials.load();
+    if (!login)
+      throw new Error(`Not logged in. Run \`${this.loginHint}\`.`);
+    if (isExpiredLogin(login))
+      throw new Error(`Your Tonbo login has expired. Run \`${this.loginHint}\`.`);
+    return login.key;
+  }
+  /**
+   * The browser handoff of /cli/login: PKCE S256 with a loopback redirect on
+   * a free port, then the one-time code is redeemed for a personal key named
+   * "CLI on <hostname>", which replaces that host's earlier login key.
+   */
+  async login(progress = () => {
+  }, account) {
+    const verifier = randomBytes(48).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    const state = randomBytes(24).toString("base64url");
+    const code = await this.listenForCode(state, (redirectUri) => {
+      const authorization = new URL("/cli/login", this.loginOrigin);
+      authorization.search = new URLSearchParams({
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        redirect_uri: redirectUri,
+        state,
+        hostname: this.hostname,
+        ...account ? { account } : {}
+      }).toString();
+      return this.browserOpener(authorization.toString());
+    }, progress);
+    progress({ status: "started", step: "key-redemption" });
+    const redeemed = await requestJson(this.fetcher, new URL("/api/cli/login/token", this.loginOrigin).toString(), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ code, code_verifier: verifier })
+    });
+    progress({ status: "completed", step: "key-redemption" });
+    const login = {
+      version: 1,
+      account_id: redeemed.account_id,
+      key_id: redeemed.api_key.id,
+      key: redeemed.key,
+      expires_at: redeemed.api_key.expires_at
+    };
+    progress({ status: "started", step: "credential-store" });
+    await this.credentials.save(login);
+    progress({ status: "completed", step: "credential-store" });
+    return login;
+  }
+  listenForCode(expectedState, ready, progress) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const sockets = /* @__PURE__ */ new Set();
+      let authorizationStarted = false;
+      const startAuthorization = () => {
+        if (authorizationStarted)
+          return;
+        authorizationStarted = true;
+        progress({ status: "completed", step: "browser" });
+        progress({ status: "started", step: "browser-authorization" });
+      };
+      const finish = (result, completedResponseSocket) => {
+        if (settled)
+          return;
+        settled = true;
+        clearTimeout(timeout);
+        const complete = (closeError) => {
+          if (closeError)
+            reject(closeError);
+          else if ("code" in result) {
+            progress({ status: "completed", step: "callback-close" });
+            resolve(result.code);
+          } else
+            reject(result.error);
+        };
+        if ("code" in result)
+          progress({ status: "started", step: "callback-close" });
+        if (!server.listening) {
+          complete();
+          return;
+        }
+        server.close(complete);
+        for (const socket of sockets) {
+          if (socket !== completedResponseSocket)
+            socket.destroy();
+        }
+        server.closeIdleConnections();
+      };
+      const timeout = setTimeout(() => {
+        finish({ error: new Error("Timed out waiting for browser login.") });
+      }, 5 * 60 * 1e3);
+      const server = createServer((request, response) => {
+        const url = new URL(request.url ?? "/", `http://${LOOPBACK_HOST}`);
+        if (url.pathname !== "/callback" || url.searchParams.get("state") !== expectedState) {
+          respond(response, "invalid");
+          return;
+        }
+        const denied = url.searchParams.get("error");
+        if (denied) {
+          const responseSocket2 = response.socket;
+          respond(response, "denied", () => finish({ error: new Error(`The login was not approved (${denied}).`) }, responseSocket2));
+          return;
+        }
+        const code = url.searchParams.get("code");
+        if (!code) {
+          respond(response, "invalid");
+          return;
+        }
+        startAuthorization();
+        progress({ status: "completed", step: "browser-authorization" });
+        const responseSocket = response.socket;
+        respond(response, "complete", () => finish({ code }, responseSocket));
+      });
+      server.on("connection", (socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+      });
+      server.once("error", (error) => finish({ error }));
+      progress({ status: "started", step: "callback-server" });
+      server.listen(0, LOOPBACK_HOST, () => {
+        const { port } = server.address();
+        progress({ status: "completed", step: "callback-server" });
+        progress({ status: "started", step: "browser" });
+        void ready(`http://${LOOPBACK_HOST}:${port}/callback`).then(startAuthorization).catch((error) => finish({
+          error: error instanceof Error ? error : new Error("Could not open the login browser.")
+        }));
+      });
+    });
   }
 };
-var accountRoles = [
-  "owner",
-  "admin",
-  "member"
-];
-var apiKeyExpirations = [
-  "15_days",
-  "1_month",
-  "6_months",
-  "1_year",
-  "never"
-];
+function respond(response, outcome, finished) {
+  const page = callbackResponse(outcome);
+  if (finished)
+    response.once("finish", finished);
+  response.writeHead(page.status, { ...page.headers, connection: "close" });
+  response.end(page.body);
+}
+async function openBrowser(url) {
+  if (process.platform === "darwin")
+    return void await exec("open", [url]);
+  if (process.platform === "win32")
+    return void await exec("rundll32", ["url.dll,FileProtocolHandler", url]);
+  return void await exec("xdg-open", [url]);
+}
 
 // ../../packages/tonbo-cli-core/dist/src/api.js
 var DEFAULT_API_ORIGIN = "https://api.tonbo.dev";
@@ -751,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];
@@ -774,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 {
@@ -871,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));
@@ -883,99 +1269,6 @@ function unconfirmed(what, idempotencyKey, same) {
   };
 }
 
-// ../../packages/tonbo-cli-core/dist/src/credentials.js
-import { randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
-import os2 from "node:os";
-import path from "node:path";
-function defaultConfigDirectory() {
-  const base = process.env.XDG_CONFIG_HOME || path.join(os2.homedir(), ".config");
-  return path.join(base, "tonbo");
-}
-var UnusableLoginError = class extends Error {
-};
-var FileCredentialStore = class {
-  filename;
-  loginHint;
-  constructor(filename = path.join(defaultConfigDirectory(), "credentials.json"), loginHint = DEFAULT_LOGIN_HINT) {
-    this.filename = filename;
-    this.loginHint = loginHint;
-  }
-  async load() {
-    let parsed;
-    try {
-      await assertPrivateRegularFile(this.filename);
-      parsed = JSON.parse(await readFile(this.filename, "utf8"));
-    } catch (error) {
-      if (error.code === "ENOENT")
-        return null;
-      throw new Error(`Could not read Tonbo credentials at ${this.filename}.`, { cause: error });
-    }
-    if (!isStoredLogin(parsed))
-      throw new UnusableLoginError(`The saved login at ${this.filename} is not usable by this CLI. Run \`${this.loginHint}\`.`);
-    return parsed;
-  }
-  async save(login) {
-    if (!isStoredLogin(login))
-      throw new Error("Refusing to store a malformed Tonbo login.");
-    const directory = path.dirname(this.filename);
-    await mkdir(directory, { mode: 448, recursive: true });
-    await preparePrivateDirectory(directory);
-    await assertExistingDestinationIsSafe(this.filename);
-    const temporary = path.join(directory, `.${path.basename(this.filename)}.${process.pid}.${randomUUID()}.tmp`);
-    let handle = null;
-    try {
-      handle = await open(temporary, "wx", 384);
-      await handle.writeFile(`${JSON.stringify(login, null, 2)}
-`, "utf8");
-      await handle.sync();
-      await handle.close();
-      handle = null;
-      if (process.platform !== "win32")
-        await chmod(temporary, 384);
-      await rename(temporary, this.filename);
-    } catch (error) {
-      await handle?.close().catch(() => void 0);
-      await rm(temporary, { force: true }).catch(() => void 0);
-      throw new Error(`Could not store Tonbo credentials at ${this.filename}.`, { cause: error });
-    }
-  }
-  async remove() {
-    await assertExistingDestinationIsSafe(this.filename);
-    await rm(this.filename, { force: true });
-  }
-};
-function isStoredLogin(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value))
-    return false;
-  const login = value;
-  return login.version === 1 && typeof login.account_id === "string" && login.account_id.length > 0 && typeof login.key_id === "string" && login.key_id.length > 0 && typeof login.key === "string" && login.key.startsWith("tbo_") && (login.expires_at === null || typeof login.expires_at === "string" && !Number.isNaN(Date.parse(login.expires_at)));
-}
-async function preparePrivateDirectory(directory) {
-  const stat = await lstat(directory);
-  if (stat.isSymbolicLink() || !stat.isDirectory())
-    throw new Error("Tonbo config directory must be a real directory.");
-  if (process.platform !== "win32")
-    await chmod(directory, 448);
-}
-async function assertExistingDestinationIsSafe(filename) {
-  try {
-    const stat = await lstat(filename);
-    if (stat.isSymbolicLink() || !stat.isFile())
-      throw new Error("Tonbo credential path must be a regular file.");
-  } catch (error) {
-    if (error.code !== "ENOENT")
-      throw error;
-  }
-}
-async function assertPrivateRegularFile(filename) {
-  const stat = await lstat(filename);
-  if (stat.isSymbolicLink() || !stat.isFile())
-    throw new Error("Tonbo credential path must be a regular file.");
-  if (process.platform !== "win32" && (stat.mode & 63) !== 0)
-    throw new Error("Tonbo credential file must have mode 0600.");
-}
-
 // ../../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)));
@@ -1402,12 +1695,20 @@ async function apiKeyCreateCommand(deps, name, options = {}) {
       "",
       `  ${created.key}`,
       "",
+      "For your application's environment (.env or secret store):",
+      "",
+      `  TONBO_API_KEY=${created.key}`,
+      "",
       apiKeyFields(created)
     ].join("\n")
   );
   deps.notice(
     "This is the only time the key's secret is shown: store it now. Anyone holding it acts as its member."
   );
+  if (!options.json)
+    deps.notice(
+      "Do not set TONBO_API_KEY in your own shell: it overrides your `tonbo login`, for this CLI too."
+    );
 }
 async function apiKeyShowCommand(deps, keyId, options = {}) {
   const apiKey = await deps.api.getApiKey(await deps.auth.apiKey(), keyId);
@@ -1582,6 +1883,13 @@ async function databaseCreateCommand(deps, name, options = {}) {
       databaseFields(database)
     ].join("\n")
   );
+  if (!options.json) deps.notice(databaseNextStep(database.name));
+}
+function databaseNextStep(name) {
+  return [
+    "Next: npm i @tonbo/sqlite-ursula",
+    `      open(${JSON.stringify(name)}) from "@tonbo/sqlite-ursula/tonbo"`
+  ].join("\n");
 }
 async function databaseShowCommand(deps, name, options = {}) {
   const database = await deps.api.getDatabase(await deps.auth.apiKey(), name);
@@ -1627,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
@@ -1685,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";
@@ -1733,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"))
@@ -1743,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));
@@ -1906,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>",