@tonbo/cli 0.10.0 → 0.10.1

package/dist/bin/tonbo.js

@@ -372,6 +372,13 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo member list"
   },
+  "listMemberDevices": {
+    "method": "GET",
+    "path": "/members/devices",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
   "updateMember": {
     "method": "PATCH",
     "path": "/members/{subject}",
@@ -488,6 +495,36 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo usage show"
   },
+  "getUsageSeries": {
+    "method": "GET",
+    "path": "/usage/series",
+    "pathParams": [],
+    "query": [
+      "days",
+      "hours",
+      "month",
+      "compare"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo usage series"
+  },
+  "getUsageToday": {
+    "method": "GET",
+    "path": "/usage/today",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo usage today"
+  },
+  "getSessionsStore": {
+    "method": "GET",
+    "path": "/sessions/store",
+    "pathParams": [],
+    "query": [
+      "capture"
+    ],
+    "idempotencyKey": false
+  },
   "listGitWorkspaces": {
     "method": "GET",
     "path": "/git/workspaces",
@@ -499,12 +536,242 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo workspace list"
   },
+  "listProjectBindings": {
+    "method": "GET",
+    "path": "/projects/bindings",
+    "pathParams": [],
+    "query": [
+      "device_id",
+      "cursor",
+      "limit"
+    ],
+    "idempotencyKey": false
+  },
+  "connectProjectFolder": {
+    "method": "POST",
+    "path": "/projects/connect",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "disconnectProjectFolder": {
+    "method": "DELETE",
+    "path": "/projects/bindings/{binding_id}",
+    "pathParams": [
+      "binding_id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "latestPersonalHandoffResult": {
+    "method": "GET",
+    "path": "/yield/sessions/{sessionId}/latest-result",
+    "pathParams": [
+      "sessionId"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "listHandoffs": {
+    "method": "GET",
+    "path": "/yield/handoffs",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "createPersonalHandoff": {
+    "method": "POST",
+    "path": "/yield/handoffs",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "listHandoffEvents": {
+    "method": "GET",
+    "path": "/yield/handoffs/events",
+    "pathParams": [],
+    "query": [
+      "after",
+      "wait"
+    ],
+    "idempotencyKey": false
+  },
+  "listTeamHandoffs": {
+    "method": "GET",
+    "path": "/yield/handoffs/team",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "showPersonalHandoff": {
+    "method": "GET",
+    "path": "/yield/handoffs/{id}",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "takePersonalHandoff": {
+    "method": "POST",
+    "path": "/yield/handoffs/{id}/take",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "markPersonalHandoffRestored": {
+    "method": "POST",
+    "path": "/yield/handoffs/{id}/restored",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "startPersonalHandoff": {
+    "method": "POST",
+    "path": "/yield/handoffs/{id}/started",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "needHumanPersonalHandoff": {
+    "method": "POST",
+    "path": "/yield/handoffs/{id}/need-human",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "cancelPersonalHandoff": {
+    "method": "POST",
+    "path": "/yield/handoffs/{id}/cancel",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "renewPersonalHandoffSource": {
+    "method": "POST",
+    "path": "/yield/handoffs/{id}/renew-source",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "finishPersonalHandoff": {
+    "method": "POST",
+    "path": "/yield/handoffs/{id}/done",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "pullPersonalHandoff": {
+    "method": "GET",
+    "path": "/yield/handoffs/{id}/result",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "markPersonalHandoffPulled": {
+    "method": "POST",
+    "path": "/yield/handoffs/{id}/pulled",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "renewPersonalHandoffResult": {
+    "method": "POST",
+    "path": "/yield/handoffs/{id}/renew-result",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "listYieldAccounts": {
+    "method": "GET",
+    "path": "/yield/accounts",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "createYieldOrganization": {
+    "method": "POST",
+    "path": "/yield/organizations",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "listYieldInvitations": {
+    "method": "GET",
+    "path": "/yield/invitations",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "createYieldInvitation": {
+    "method": "POST",
+    "path": "/yield/invitations",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "revokeYieldInvitation": {
+    "method": "DELETE",
+    "path": "/yield/invitations/{id}",
+    "pathParams": [
+      "id"
+    ],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "recordYieldMetric": {
+    "method": "POST",
+    "path": "/yield/metrics",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
+  "readYieldTurnExcerpt": {
+    "method": "GET",
+    "path": "/yield/excerpts",
+    "pathParams": [],
+    "query": [
+      "author",
+      "session_id",
+      "turn",
+      "path"
+    ],
+    "idempotencyKey": false
+  },
+  "publishYieldTurnExcerpt": {
+    "method": "POST",
+    "path": "/yield/excerpts",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false
+  },
   "listDatabases": {
     "method": "GET",
     "path": "/databases",
     "pathParams": [],
     "query": [
       "prefix",
+      "include",
       "cursor",
       "limit"
     ],
@@ -549,6 +816,20 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo database delete"
   },
+  "getDatabaseActivity": {
+    "method": "GET",
+    "path": "/databases/{name}/usage",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "granularity",
+      "from",
+      "to"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo database activity"
+  },
   "listDatabaseUsage": {
     "method": "GET",
     "path": "/usage/databases",
@@ -644,12 +925,49 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo machine shapes"
   },
+  "listVolumes": {
+    "method": "GET",
+    "path": "/volumes",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo volume list"
+  },
+  "createVolume": {
+    "method": "POST",
+    "path": "/volumes",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": true,
+    "cli": "tonbo volume create"
+  },
+  "getVolume": {
+    "method": "GET",
+    "path": "/volumes/{name}",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo volume show"
+  },
+  "deleteVolume": {
+    "method": "DELETE",
+    "path": "/volumes/{name}",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo volume delete"
+  },
   "listStreams": {
     "method": "GET",
     "path": "/streams",
     "pathParams": [],
     "query": [
       "prefix",
+      "include",
       "cursor",
       "limit"
     ],
@@ -694,6 +1012,20 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo stream delete"
   },
+  "getStreamActivity": {
+    "method": "GET",
+    "path": "/streams/{name}/usage",
+    "pathParams": [
+      "name"
+    ],
+    "query": [
+      "granularity",
+      "from",
+      "to"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo stream activity"
+  },
   "listStreamUsage": {
     "method": "GET",
     "path": "/usage/streams",
@@ -1196,6 +1528,12 @@ async function assertPrivateRegularFile(filename) {
 var exec = promisify(execFile);
 var DEFAULT_LOGIN_HINT = credentialsContract.reader.login_hint;
 var LOOPBACK_HOST = "127.0.0.1";
+var BrowserUnavailableError = class extends Error {
+};
+function prefersDeviceLogin(env = process.env) {
+  const ssh = Boolean(env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY);
+  return ssh && !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
 function newLoginSecret() {
   return randomBytes(32).toString("base64url");
 }
@@ -1210,13 +1548,17 @@ var AuthClient = class {
   browserOpener;
   hostname;
   loginHint;
-  constructor(credentials, fetcher, loginOrigin2 = "https://tonbo.dev", browserOpener = openBrowser, hostname = loginHostname(), loginHint = DEFAULT_LOGIN_HINT) {
+  entryLine;
+  env;
+  constructor(credentials, fetcher, loginOrigin2 = "https://tonbo.dev", browserOpener = openBrowser, hostname = loginHostname(), loginHint = DEFAULT_LOGIN_HINT, entryLine = "cli", env = process.env) {
     this.credentials = credentials;
     this.fetcher = fetcher;
     this.loginOrigin = loginOrigin2;
     this.browserOpener = browserOpener;
     this.hostname = hostname;
     this.loginHint = loginHint;
+    this.entryLine = entryLine;
+    this.env = env;
   }
   /** The personal key requests are made with: TONBO_API_KEY, or the saved
    * login while it has not expired. */
@@ -1236,12 +1578,16 @@ var AuthClient = class {
    * a free port, then the one-time code is redeemed, with this device's login
    * secret, for the account's login key, which replaces this device's earlier
    * login key there ("CLI on <hostname>" in a personal account, `Yield CLI ·
-   * <8 hex>` in any other). The key joins the file's `accounts`; it becomes
-   * the top level too unless `current` is false (a login made only to publish
-   * into an organization). Answers that account's login.
+   * <8 hex>` in any other). With `device`, in an SSH session without a
+   * display, or when no browser can be opened, the same PKCE challenge goes
+   * to a device-code login instead: the person enters a short code at
+   * /cli/device in any browser and the CLI polls for the key. The key joins
+   * the file's `accounts`; it becomes the top level too unless `current` is
+   * false (a login made only to publish into an organization). Answers that
+   * account's login.
    */
   async login(progress = () => {
-  }, account, { current = true } = {}) {
+  }, account, { current = true, device } = {}) {
     const existing = await this.credentials.load().catch((error) => {
       if (error instanceof UnusableLoginError)
         return null;
@@ -1250,6 +1596,30 @@ var AuthClient = class {
     const loginSecret = existing?.login_secret ?? newLoginSecret();
     const verifier = randomBytes(48).toString("base64url");
     const challenge = createHash("sha256").update(verifier).digest("base64url");
+    const redeemed = device ?? prefersDeviceLogin(this.env) ? await this.deviceLogin(challenge, verifier, loginSecret, account, progress) : await this.browserLogin(challenge, verifier, loginSecret, account, progress).catch((error) => {
+      if (!(error instanceof BrowserUnavailableError))
+        throw error;
+      progress({ status: "failed", step: "browser", reason: error.message });
+      return this.deviceLogin(challenge, verifier, loginSecret, account, progress);
+    });
+    const login = {
+      account_id: redeemed.account_id,
+      key_id: redeemed.api_key.id,
+      key: redeemed.key,
+      expires_at: redeemed.api_key.expires_at,
+      kind: redeemed.account_kind ?? null,
+      name: redeemed.account_name ?? null
+    };
+    progress({ status: "started", step: "credential-store" });
+    const latest = await this.credentials.load().catch(() => existing);
+    await this.credentials.save(withAccountLogin(latest, login, {
+      current,
+      loginSecret: latest?.login_secret ?? loginSecret
+    }));
+    progress({ status: "completed", step: "credential-store" });
+    return login;
+  }
+  async browserLogin(challenge, verifier, loginSecret, account, progress) {
     const state = randomBytes(24).toString("base64url");
     const code = await this.listenForCode(state, (redirectUri) => {
       const authorization = new URL("/cli/login", this.loginOrigin);
@@ -1259,6 +1629,7 @@ var AuthClient = class {
         redirect_uri: redirectUri,
         state,
         hostname: this.hostname,
+        from: this.entryLine,
         ...account ? { account } : {}
       }).toString();
       return authorization.toString();
@@ -1271,34 +1642,85 @@ var AuthClient = class {
       body: JSON.stringify({ code, code_verifier: verifier, login_secret: loginSecret })
     });
     progress({ status: "completed", step: "key-redemption" });
-    const login = {
-      account_id: redeemed.account_id,
-      key_id: redeemed.api_key.id,
-      key: redeemed.key,
-      expires_at: redeemed.api_key.expires_at,
-      kind: redeemed.account_kind ?? null,
-      name: redeemed.account_name ?? null
-    };
-    progress({ status: "started", step: "credential-store" });
-    const latest = await this.credentials.load().catch(() => existing);
-    await this.credentials.save(withAccountLogin(latest, login, {
-      current,
-      loginSecret: latest?.login_secret ?? loginSecret
-    }));
-    progress({ status: "completed", step: "credential-store" });
-    return login;
+    return redeemed;
+  }
+  /**
+   * The device-code login (RFC 8628's shape): the PKCE challenge and the
+   * hostname buy a device code and a user code; the person approves the user
+   * code at /cli/device, seeing the hostname; the CLI polls with the device
+   * code, its verifier and the login secret, all in POST bodies, and the
+   * approved poll answers the key once. A denied or expired code ends it.
+   */
+  async deviceLogin(challenge, verifier, loginSecret, account, progress) {
+    progress({ status: "started", step: "device-code" });
+    const started = await requestJson(this.fetcher, new URL("/api/cli/login/device", this.loginOrigin).toString(), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        hostname: this.hostname
+      })
+    });
+    progress({ status: "completed", step: "device-code" });
+    const page = new URL("/cli/device", this.loginOrigin);
+    const complete = new URL(page);
+    complete.search = new URLSearchParams({
+      code: started.user_code,
+      from: this.entryLine,
+      ...account ? { account } : {}
+    }).toString();
+    progress({
+      status: "device-code",
+      step: "device-authorization",
+      userCode: started.user_code,
+      url: page.toString(),
+      completeUrl: complete.toString(),
+      expiresIn: started.expires_in
+    });
+    progress({ status: "started", step: "device-authorization" });
+    const expired = new Error(`The login code expired. Run \`${this.loginHint}\` again.`);
+    const deadline = Date.now() + started.expires_in * 1e3;
+    let interval = started.interval;
+    for (; ; ) {
+      await new Promise((resolve) => setTimeout(resolve, interval * 1e3));
+      try {
+        const redeemed = await requestJson(this.fetcher, new URL("/api/cli/login/device/token", this.loginOrigin).toString(), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            device_code: started.device_code,
+            code_verifier: verifier,
+            login_secret: loginSecret
+          })
+        });
+        progress({ status: "completed", step: "device-authorization" });
+        return redeemed;
+      } catch (error) {
+        const code = error instanceof HttpError ? error.code : null;
+        if (code === "slow_down")
+          interval += 5;
+        else if (code === "access_denied")
+          throw new Error("The login was not approved (access_denied).");
+        else if (code === "expired_token")
+          throw expired;
+        else if (code !== "authorization_pending" && !transient(error))
+          throw error;
+        if (Date.now() >= deadline)
+          throw expired;
+      }
+    }
   }
   listenForCode(expectedState, authorizationUrl, progress) {
     return new Promise((resolve, reject) => {
       let settled = false;
       const sockets = /* @__PURE__ */ new Set();
       let authorizationStarted = false;
-      const startAuthorization = (browserOpened = true) => {
+      const startAuthorization = () => {
         if (authorizationStarted)
           return;
         authorizationStarted = true;
-        if (browserOpened)
-          progress({ status: "completed", step: "browser" });
+        progress({ status: "completed", step: "browser" });
         progress({ status: "started", step: "browser-authorization" });
       };
       const finish = (result, completedResponseSocket) => {
@@ -1368,18 +1790,17 @@ var AuthClient = class {
         void Promise.resolve().then(() => this.browserOpener(url)).then(() => startAuthorization(), (error) => {
           if (settled || authorizationStarted)
             return;
-          progress({
-            status: "failed",
-            step: "browser",
-            reason: error instanceof Error ? error.message : String(error),
-            callbackPort: port
+          finish({
+            error: new BrowserUnavailableError(error instanceof Error ? error.message : String(error))
           });
-          startAuthorization(false);
         });
       });
     });
   }
 };
+function transient(error) {
+  return error instanceof HttpError ? error.status === 429 || error.status >= 500 : error instanceof TypeError;
+}
 function respond(response, outcome, finished) {
   const page = callbackResponse(outcome);
   if (finished)
@@ -1555,6 +1976,10 @@ var ManagementApi = class {
   deleteDatabase(key, name) {
     return this.call("deleteDatabase", key, { params: { name } });
   }
+  /** A database's writes per hour or day and its size at each step's end. */
+  getDatabaseActivity(key, name, query = {}) {
+    return this.call("getDatabaseActivity", key, { params: { name }, query });
+  }
   /** The whole usage page: its rows, `other`, prices and checkpoint. */
   listDatabaseUsage(key, page, query = {}) {
     return this.page("listDatabaseUsage", key, page, query);
@@ -1579,6 +2004,10 @@ var ManagementApi = class {
   deleteStream(key, name) {
     return this.call("deleteStream", key, { params: { name } });
   }
+  /** A stream's appends per hour or day and its size at each step's end. */
+  getStreamActivity(key, name, query = {}) {
+    return this.call("getStreamActivity", key, { params: { name }, query });
+  }
   /** The whole usage page: its rows, `other`, prices and checkpoint. */
   listStreamUsage(key, page, query = {}) {
     return this.page("listStreamUsage", key, page, query);
@@ -1586,6 +2015,13 @@ var ManagementApi = class {
   getUsage(key, period) {
     return this.call("getUsage", key, { query: { period } });
   }
+  getUsageSeries(key, query = {}) {
+    return this.call("getUsageSeries", key, { query });
+  }
+  /** The account's writes of yesterday and today, hourly, per lane. */
+  getUsageToday(key) {
+    return this.call("getUsageToday", key);
+  }
   listMachines(key, page) {
     return this.page("listMachines", key, page);
   }
@@ -1715,6 +2151,22 @@ var ManagementApi = class {
   listMachineShapes(key) {
     return this.request("listMachineShapes", key, {});
   }
+  /** Every Volume of the account, and the regions that could not be read. */
+  listVolumes(key) {
+    return this.request("listVolumes", key, {});
+  }
+  /** A replay with the same idempotency key answers the Volume the first
+   * request created, so an unconfirmed create names the key to retry with. */
+  createVolume(key, request, idempotencyKey) {
+    return this.call("createVolume", key, { body: request, idempotencyKey }).catch(unconfirmed("Volume creation", idempotencyKey, "the same name, region and size"));
+  }
+  getVolume(key, name) {
+    return this.call("getVolume", key, { params: { name } });
+  }
+  /** The Volume being deleted; refused (409) while it is bound. */
+  deleteVolume(key, name) {
+    return this.call("deleteVolume", key, { params: { name } });
+  }
 };
 var CREATE_ATTEMPTS = 3;
 var CREATE_RETRY_MAX_WAIT_SECONDS = 30;
@@ -1775,7 +2227,7 @@ function when(timestamp, absent = "never") {
 // ../../packages/tonbo-cli-core/dist/src/login.js
 async function loginCommand(deps, options = {}) {
   try {
-    const login = await deps.auth.login((event) => reportLoginProgress(deps.progress, event), options.account, { current: options.current });
+    const login = await deps.auth.login((event) => reportLoginProgress(deps.progress, event), options.account, { current: options.current, device: options.device });
     deps.output(`Logged in to account ${login.name ?? login.account_id}.${login.expires_at ? ` The login expires ${login.expires_at}.` : ""}`);
     return login;
   } catch (error) {
@@ -1804,6 +2256,14 @@ var LOGIN_PROGRESS_MESSAGES = {
     started: "Receiving the CLI key",
     completed: "CLI key received"
   },
+  "device-code": {
+    started: "Requesting a login code",
+    completed: "Login code received"
+  },
+  "device-authorization": {
+    started: "Waiting for approval in a browser",
+    completed: "Login approved"
+  },
   "credential-store": {
     started: "Saving login",
     completed: "Login saved"
@@ -1815,9 +2275,13 @@ function reportLoginProgress(progress, event) {
     return;
   }
   if (event.status === "failed") {
-    const port = event.callbackPort;
-    progress.fail(`Could not open a browser: ${event.reason.replace(/\.$/, "")}.`);
-    progress.note(`Open the URL above in a browser that can reach 127.0.0.1:${port} on this machine. From another computer, forward that port first: \`ssh -L ${port}:127.0.0.1:${port} <this host>\` or your VM's port forwarding both work.`);
+    progress.fail(`Could not open a browser: ${event.reason.replace(/\.$/, "")}. Approve with a code instead.`);
+    return;
+  }
+  if (event.status === "device-code") {
+    const minutes = Math.max(1, Math.round(event.expiresIn / 60));
+    progress.note(`To approve this login, open ${event.url} in any browser and enter the code ${event.userCode}. It expires in ${minutes} minutes.`);
+    progress.note(`Or open ${event.completeUrl}`);
     return;
   }
   const messages = LOGIN_PROGRESS_MESSAGES[event.step];
@@ -2438,8 +2902,8 @@ async function databaseCreateCommand(deps, name, options = {}) {
 }
 function databaseNextStep(name) {
   return [
-    "Next: npm i --save-exact @tonbo/sqlite-ursula@0.11.2",
-    `      open(${JSON.stringify(name)}) from "@tonbo/sqlite-ursula/tonbo"`
+    "Next: npm i --save-exact @tonbo/sdk@1.0.0 @tonbo/sqlite-ursula@0.11.4",
+    `      openDatabase(${JSON.stringify(name)}) from "@tonbo/sdk/database"`
   ].join("\n");
 }
 async function databaseShowCommand(deps, name, options = {}) {
@@ -2523,11 +2987,48 @@ async function databaseUsageCommand(deps, options = {}) {
   );
   printResourceUsage(deps, options.json, usage, "database");
 }
-function streamFields(stream) {
-  return fields([
-    ["Name", stream.name],
-    ["Region", stream.region],
-    ["State", stream.state],
+function stepValue(value) {
+  return value === null ? "" : String(value);
+}
+function printActivity(deps, json, activity, noun) {
+  print(
+    deps,
+    json,
+    activity,
+    [
+      `${noun} ${activity.name} in ${activity.region}, ${activity.granularity === "day" ? "daily" : "hourly"} from ${activity.from} to ${activity.to} (UTC; metered up to ${when(activity.as_of, "not yet metered")}; last write ${when(activity.last_write_at)})`,
+      table(
+        ["START", "WRITE UNITS", "APPENDED", "RECORDS", "READS", "LIVE READS", "LOG", "SNAPSHOT"],
+        activity.points.map((point) => [
+          point.start,
+          stepValue(point.write_units),
+          point.append_bytes === null ? "" : bytes(point.append_bytes),
+          stepValue(point.records),
+          stepValue(point.reads),
+          stepValue(point.live_reads),
+          point.log_bytes === null ? "" : bytes(point.log_bytes),
+          point.snapshot_bytes === null ? "" : bytes(point.snapshot_bytes)
+        ])
+      )
+    ].join("\n")
+  );
+}
+function activityQuery(options) {
+  return { granularity: options.granularity, from: options.from, to: options.to };
+}
+async function databaseActivityCommand(deps, name, options = {}) {
+  const activity = await deps.api.getDatabaseActivity(
+    await deps.auth.apiKey(),
+    name,
+    activityQuery(options)
+  );
+  printActivity(deps, options.json, activity, "Database");
+}
+function streamFields(stream) {
+  return fields([
+    ["Name", stream.name],
+    ["Region", stream.region],
+    ["State", stream.state],
     ["Content type", stream.content_type],
     ["Expires", stream.expires_at ?? "never"],
     ["Read access", readAccess(stream)],
@@ -2636,6 +3137,83 @@ async function streamUsageCommand(deps, options = {}) {
   );
   printResourceUsage(deps, options.json, usage, "stream");
 }
+async function usageSeriesCommand(deps, options = {}) {
+  const series = await deps.api.getUsageSeries(await deps.auth.apiKey(), {
+    days: options.days,
+    hours: options.hours,
+    month: options.month,
+    compare: options.compare ? "previous" : void 0
+  });
+  const at = (start) => series.granularity === "hour" ? start.slice(0, 16).replace("T", " ") : start.slice(0, 10);
+  const month = series.month_to_date;
+  const lines = [
+    `Spend from ${at(series.start)} to ${at(series.end)} (UTC, ${series.currency.toUpperCase()})`,
+    table(
+      [
+        series.granularity === "hour" ? "HOUR" : "DAY",
+        "LIST",
+        "ALLOWANCE",
+        "CREDIT",
+        "UNPAID",
+        "CHARGED"
+      ],
+      series.points.map((point) => [
+        at(point.start),
+        usd(point.list_micros),
+        usd(point.allowance_micros),
+        usd(point.credit_micros),
+        usd(point.outstanding_micros),
+        usd(point.charged_micros)
+      ])
+    ),
+    `Total: ${usd(series.totals.list_micros)} at list price, ${usd(series.totals.charged_micros)} charged beyond the allowance`
+  ];
+  if (series.previous) {
+    const before = series.previous.totals.list_micros;
+    const change = before ? ` (${series.totals.list_micros >= before ? "+" : ""}${Math.round((series.totals.list_micros - before) / before * 100)}%)` : "";
+    lines.push(
+      `Before: ${usd(before)} at list price from ${at(series.previous.start)} to ${at(series.previous.end)}${change}`
+    );
+  }
+  lines.push(
+    `${month.month} so far: ${usd(month.list_micros)} at list price, ${usd(month.allowance_micros)} of the ${usd(month.allowance_granted_micros)} allowance used, ${usd(month.charged_micros)} charged`
+  );
+  if (month.projection)
+    lines.push(
+      `At the rate of its ${month.projection.basis_days} complete days: ${usd(month.projection.list_micros)} at list price, ${usd(month.projection.charged_micros)} charged`
+    );
+  print(deps, options.json, series, lines.join("\n"));
+}
+async function streamActivityCommand(deps, name, options = {}) {
+  const activity = await deps.api.getStreamActivity(
+    await deps.auth.apiKey(),
+    name,
+    activityQuery(options)
+  );
+  printActivity(deps, options.json, activity, "Stream");
+}
+async function usageTodayCommand(deps, options = {}) {
+  const today = await deps.api.getUsageToday(await deps.auth.apiKey());
+  const { databases, streams, other } = today.series;
+  print(
+    deps,
+    options.json,
+    today,
+    [
+      `Write units per hour of yesterday and today (UTC; metered up to ${when(today.as_of, "not yet metered")})`,
+      table(
+        ["HOUR", "DATABASES", "STREAMS", "OTHER"],
+        databases.map((point, index) => [
+          point.start,
+          stepValue(point.write_units),
+          stepValue(streams[index]?.write_units ?? null),
+          stepValue(other[index]?.write_units ?? null)
+        ])
+      )
+    ].join("\n")
+  );
+  noticeUnavailable(deps, today.unavailable_regions, "usage");
+}
 async function usageShowCommand(deps, options = {}) {
   const usage = await deps.api.getUsage(await deps.auth.apiKey(), options.period);
   print(
@@ -2660,8 +3238,143 @@ async function usageShowCommand(deps, options = {}) {
   );
 }
 
+// src/help.ts
+import { Help } from "commander";
+
 // src/machine.ts
+import { randomUUID as randomUUID4 } from "node:crypto";
+
+// src/volume.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
+var VOLUME_DURABILITY_LINK = "https://tonbo.dev/docs/machines/guarantees/data#volume";
+var VOLUME_ERROR_HINTS = {
+  payment_required: "Add credit at <billing>, then create the Volume again.",
+  region_not_offered: "Volumes are not offered to this account in that region yet; nothing was created. Name a region where they are offered.",
+  region_unavailable: "A region cannot be reached right now; nothing was created or changed. Try again shortly."
+};
+async function explainVolumeError(deps, error) {
+  if (!(error instanceof HttpError) || error.code === null) return error;
+  const hint = VOLUME_ERROR_HINTS[error.code];
+  if (!hint) return explainMachineError(error);
+  const text = hint.includes("<billing>") ? hint.replaceAll("<billing>", await billingUrl(deps)) : hint;
+  return new HttpError(`${error.message}
+${text}`, error.status, error.body, error.requestId);
+}
+async function volumeCommand(deps, run) {
+  try {
+    return await run();
+  } catch (error) {
+    throw await explainVolumeError(deps, error);
+  }
+}
+function boundText(volume) {
+  if (!volume.machine) return "none";
+  return `${volume.machine.name}${volume.state === "attached" ? " (attached)" : ""}`;
+}
+function volumeFields(volume) {
+  return fields([
+    ["Name", volume.name],
+    ["ID", volume.id],
+    ["Region", volume.region],
+    ["State", volume.state],
+    ["Machine", boundText(volume)],
+    ["Size", `${volume.size_gib} GiB`],
+    ["Live bytes", `${bytes(volume.live_bytes)} (billed)`],
+    ["Last commit", volume.last_commit_at ?? "none yet"],
+    ["Durability", VOLUME_DURABILITY_LINK],
+    ["Created", volume.created_at]
+  ]);
+}
+function parseSizeGib(value) {
+  const match = /^([0-9]+)(?:\s*gi?b?)?$/i.exec(value.trim());
+  if (!match) throw new Error(`--size ${value}: give a whole number of GiB, such as 20.`);
+  return Number(match[1]);
+}
+async function volumeListCommand(deps, options = {}) {
+  await volumeCommand(deps, async () => {
+    const list = await deps.api.listVolumes(await deps.auth.apiKey());
+    print(
+      deps,
+      options.json,
+      list.data,
+      list.data.length ? table(
+        ["NAME", "REGION", "STATE", "MACHINE", "SIZE", "LIVE BYTES"],
+        list.data.map((volume) => [
+          volume.name,
+          volume.region,
+          volume.state,
+          volume.machine?.name ?? "-",
+          `${volume.size_gib} GiB`,
+          bytes(volume.live_bytes)
+        ])
+      ) : "No Volumes."
+    );
+    if (list.unavailable_regions.length)
+      deps.notice(
+        `Could not read the Volumes in ${list.unavailable_regions.join(", ")}; they are missing from this list.`
+      );
+  });
+}
+async function volumeShowCommand(deps, name, options = {}) {
+  await volumeCommand(deps, async () => {
+    const volume = await deps.api.getVolume(await deps.auth.apiKey(), name);
+    print(deps, options.json, volume, volumeFields(volume));
+  });
+}
+async function volumeCreateCommand(deps, name, options = {}) {
+  await volumeCommand(deps, async () => {
+    if (options.size === void 0) throw new Error("Pass --size <GiB>.");
+    const sizeGib = parseSizeGib(options.size);
+    const key = await deps.auth.apiKey();
+    const region = options.region ?? (await deps.api.listRegions(key)).find((entry) => entry.default)?.id;
+    if (!region) throw new Error("The account has no default region: pass --region.");
+    const volume = await deps.api.createVolume(
+      key,
+      { name, region, size_gib: sizeGib },
+      options.idempotencyKey ?? randomUUID3()
+    );
+    print(
+      deps,
+      options.json,
+      volume,
+      [
+        `Created Volume ${volume.name} in ${volume.region} (${volume.size_gib} GiB; billed by live bytes, not size).`,
+        `Mount it on a Machine of ${volume.region} with \`tonbo machine update <machine> --volume ${volume.name}:/data\`; it attaches at the Machine's next boot.`,
+        volumeFields(volume)
+      ].join("\n")
+    );
+  });
+}
+async function volumeDeleteCommand(deps, name, options = {}) {
+  await volumeCommand(deps, async () => {
+    const key = await deps.auth.apiKey();
+    await confirm(
+      deps,
+      options.yes,
+      `delete Volume ${name}`,
+      () => Promise.resolve(
+        `Delete Volume ${name} and every byte on it? There are no Volume snapshots or backups, so this cannot be undone. Type the Volume's name to confirm:`
+      ),
+      name
+    );
+    const volume = await deps.api.deleteVolume(key, name);
+    print(
+      deps,
+      options.json,
+      volume,
+      `Volume ${volume.name} is being deleted; its name is free for a new Volume.`
+    );
+  });
+}
+async function resolveVolumeBinding(deps, key, spec) {
+  const split = spec.indexOf(":");
+  if (split < 1 || split === spec.length - 1)
+    throw new Error(`--volume ${spec}: give <name>:<path>, such as data:/data.`);
+  const volume = await deps.api.getVolume(key, spec.slice(0, split));
+  return { binding: { volume: volume.id, path: spec.slice(split + 1) }, region: volume.region };
+}
+
+// src/machine.ts
 var MACHINE_ERROR_HINTS = {
   region_not_offered: "Machines are not offered in that region yet; nothing was created or changed. Name a region where they are offered.",
   region_unavailable: "That region cannot be reached right now; nothing was created or changed. Try again shortly.",
@@ -2670,7 +3383,6 @@ var MACHINE_ERROR_HINTS = {
   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`).",
-  image_not_offered: "Only the platform image runs until image pulls ship: create or update the Machine with `--image tonbo.dev/platform`.",
   shape_not_offered: "`tonbo machine shapes` lists the shapes a Machine may name now.",
   port_reserved: "Serve the application on another port.",
   precondition_required: "The API needs the Machine's ETag for this change; `tonbo machine show` prints it, and the command sends the ETag it reads unless --if-match names one.",
@@ -2678,11 +3390,13 @@ var MACHINE_ERROR_HINTS = {
   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.",
   database_limit_reached: "Each Machine counts one database: delete a Machine or a database (`tonbo database list`) first.",
+  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.",
   idempotency_conflict: "That idempotency key belongs to another request: leave out --idempotency-key to create a new Machine.",
   create_rate_limited: "Too many Machines were created in the last hour; try again later.",
   image_pulling: "The Machine's image is still being pulled; the request was not run. Try again shortly; `tonbo machine show` reports the image's state.",
   image_failed: "The Machine's image could not be pulled; `tonbo machine show` says why. Fix the image, then name it again with `tonbo machine update --image`.",
-  machine_kind_mismatch: "That Machine is one of your computers: `tonbo machine show` and `tonbo machine delete` serve it, and nothing else does."
+  machine_kind_mismatch: "That Machine is one of your computers: `tonbo machine show` and `tonbo machine delete` serve it, and nothing else does.",
+  volumes_not_offered: "Volumes are not offered to this account in the Machine's region yet; nothing was created or changed."
 };
 var MACHINE_IMAGE_FAILURE_HINTS = {
   image_unavailable: "The registry no longer serves that image publicly, or served other bytes for it: publish it again, or use another image",
@@ -2691,9 +3405,9 @@ var MACHINE_IMAGE_FAILURE_HINTS = {
   image_unsupported: "Rebuild the image without the entry the message names"
 };
 var MACHINE_CREATION_FAILURE_HINTS = {
-  database_creation_failed: "The Machine's database could not be created; the message names the stream and the code. If the code is payment_required, add credit to the account first; then delete the Machine and create it again.",
+  database_creation_failed: "The Machine's database could not be created; the message names the stream and the code. If the code is payment_required, add credit at <billing> first; then delete the Machine and create it again.",
   database_limit_reached: "Each Machine counts one database: delete a Machine or a database (`tonbo database list`), then delete this Machine and create it again.",
-  payment_required: "The account's credit is exhausted: add credit to the account, then delete the Machine and create it again.",
+  payment_required: "The account's credit is exhausted: add credit at <billing>, then delete the Machine and create it again.",
   ...Object.fromEntries(
     Object.entries(MACHINE_IMAGE_FAILURE_HINTS).map(([code, hint]) => [
       code,
@@ -2701,10 +3415,10 @@ var MACHINE_CREATION_FAILURE_HINTS = {
     ])
   )
 };
-function creationFailureText(machine) {
+function creationFailureText(machine, billing) {
   const { failure } = machine;
   if (!failure) return { reason: "", hint: "" };
-  const hint = MACHINE_CREATION_FAILURE_HINTS[failure.code];
+  const hint = MACHINE_CREATION_FAILURE_HINTS[failure.code]?.replaceAll("<billing>", billing);
   return { reason: ` (${failure.code}: ${failure.message})`, hint: hint ? `
 ${hint}` : "" };
 }
@@ -2719,6 +3433,18 @@ function explainMachineError(error) {
   return new HttpError(`${error.message}
 ${hint}`, error.status, error.body, error.requestId);
 }
+var BILLING_URL = "https://tonbo.dev/{account}/billing";
+var BILLING_FALLBACK_URL = "https://tonbo.dev/billing";
+async function billingUrl(deps) {
+  if (process.env.TONBO_API_KEY?.trim()) return BILLING_FALLBACK_URL;
+  try {
+    const login = await deps.credentials.load();
+    const name = login ? accountLogins(login).find((entry) => entry.account_id === login.account_id)?.name : null;
+    return name ? BILLING_URL.replace("{account}", encodeURIComponent(name)) : BILLING_FALLBACK_URL;
+  } catch {
+    return BILLING_FALLBACK_URL;
+  }
+}
 async function machineCommand(run) {
   try {
     return await run();
@@ -2774,18 +3500,18 @@ function activationFields(machine) {
   return fields2;
 }
 var MACHINE_WAKE_BLOCKED_HINTS = {
-  payment_required: "The account's credit does not cover a wake: add credit, and the next request wakes it.",
-  standing: "The account's Streams standing is not solvent: settle the account, and the next request wakes it.",
+  payment_required: "The account's credit does not cover a wake: add credit at <billing>, and the next request wakes it.",
+  standing: "The account's Streams standing is not solvent: settle the account at <billing>, and the next request wakes it.",
   meter_lag: "Tonbo could not confirm the account's usage in time; the next request tries again.",
   crash_backoff: "Its recent wakes failed; see `tonbo machine activations <name>`.",
   capacity: "No host had room for its shape; the next request tries again.",
   region_closed: "Machines are closed in its region for now; the next request after they reopen wakes it."
 };
-function conditionText(name, condition) {
+function conditionText(name, condition, billing) {
   switch (condition.type) {
     case "wake_blocked": {
       const retry = condition.retry_at ? `, retry after ${condition.retry_at}` : "";
-      const hint = MACHINE_WAKE_BLOCKED_HINTS[condition.reason]?.replaceAll("<name>", name);
+      const hint = MACHINE_WAKE_BLOCKED_HINTS[condition.reason]?.replaceAll("<name>", name).replaceAll("<billing>", billing);
       return `wake blocked (${condition.reason.replaceAll("_", " ")}) since ${condition.since}${retry}.${hint ? ` ${hint}` : ""}`;
     }
     case "creation_delayed":
@@ -2794,14 +3520,16 @@ function conditionText(name, condition) {
       return `its host is unreachable since ${condition.since}`;
     case "egress_blocked":
       return `outbound access blocked for the ${condition.scope} since ${condition.since}${condition.until ? ` until ${condition.until}` : ""}`;
+    case "volume_purged":
+      return `its Volume ${condition.volume} was purged (${condition.reason.replaceAll("_", " ")}) since ${condition.since}; its data is gone and it boots without it. Bind another with \`tonbo machine update ${name} --volume <volume>:<path>\`, or none with \`--no-volume\`.`;
     default:
       return JSON.stringify(condition);
   }
 }
-function conditionFields(machine) {
+function conditionFields(machine, billing) {
   return (machine.status.conditions ?? []).map((condition) => [
     "Condition",
-    conditionText(machine.name, condition)
+    conditionText(machine.name, condition, billing)
   ]);
 }
 function endText(end) {
@@ -2841,7 +3569,7 @@ function imageFailureFields(machine) {
     ...next ? [["Next step", next]] : []
   ];
 }
-function machineFields(machine, etag = null, lastEnd = null) {
+function machineFields(machine, billing, etag = null, lastEnd = null) {
   return fields([
     ["Name", machine.name],
     ["ID", machine.id],
@@ -2850,7 +3578,7 @@ function machineFields(machine, etag = null, lastEnd = null) {
     ["Power", powerText(machine)],
     ...activationFields(machine),
     ...lastEnd ? [["Last end", endText(lastEnd)]] : [],
-    ...conditionFields(machine),
+    ...conditionFields(machine, billing),
     ["Sleeps", sleepText(machine)],
     ["Shape", machine.shape],
     ["Image", imageText(machine)],
@@ -2863,6 +3591,7 @@ function machineFields(machine, etag = null, lastEnd = null) {
     ["SSH", `${machine.hostnames.ssh} (not served yet)`],
     ["Env", Object.keys(machine.env).sort().join(", ") || "none"],
     ["Stop grace", `${machine.stop_grace_seconds} s`],
+    ["Volume", volumeText(machine)],
     ["Database", `${machine.database.name} (${machine.database.url})`],
     ["Logs", machine.logs.url],
     ["Durability", DURABILITY_LINK],
@@ -2873,8 +3602,12 @@ function machineFields(machine, etag = null, lastEnd = null) {
     ["Updated", machine.updated_at]
   ]);
 }
-function machineText(machine, etag = null, lastEnd = null) {
-  return [machineFields(machine, etag, lastEnd), ...privatePortLines(machine)].join("\n");
+function volumeText(machine) {
+  const binding = machine.volumes?.[0];
+  return binding ? `${binding.volume} at ${binding.path}` : "none";
+}
+function machineText(machine, billing, etag = null, lastEnd = null) {
+  return [machineFields(machine, billing, etag, lastEnd), ...privatePortLines(machine)].join("\n");
 }
 function keyStateText(machine) {
   const state = machine.byoc.key_state;
@@ -2899,8 +3632,8 @@ function deviceFields(machine) {
     ["Updated", machine.updated_at]
   ]);
 }
-function anyMachineText(machine, etag = null, lastEnd = null) {
-  return machine.kind === "byoc" ? deviceFields(machine) : machineText(machine, etag, lastEnd);
+function anyMachineText(machine, billing, etag = null, lastEnd = null) {
+  return machine.kind === "byoc" ? deviceFields(machine) : machineText(machine, billing, etag, lastEnd);
 }
 function parsePorts(specs) {
   const accesses = machinePortAccess;
@@ -3064,9 +3797,10 @@ async function waitForCreate(deps, key, machine, name, firstWait, timeout, json)
     timeout,
     (read) => read.state !== "creating"
   );
+  const billing = await billingUrl(deps);
   if (!settled) {
     const known = last ?? machine;
-    print(deps, json, known, machineFields(known));
+    print(deps, json, known, machineFields(known, billing));
     throw new Error(
       `Machine ${machine.name} is still creating after ${waited} s; nothing was undone. \`tonbo machine show ${machine.name}\` reports it active when it is ready.`
     );
@@ -3079,14 +3813,14 @@ async function waitForCreate(deps, key, machine, name, firstWait, timeout, json)
       settled,
       [
         `Created ${settled.name} in ${settled.region} (active after ${waited} s${pulled}).`,
-        machineText(settled)
+        machineText(settled, billing)
       ].join("\n")
     );
     return;
   }
-  print(deps, json, settled, machineFields(settled));
+  print(deps, json, settled, machineFields(settled, billing));
   if (settled.state === "failed") {
-    const { reason, hint } = creationFailureText(settled);
+    const { reason, hint } = creationFailureText(settled, billing);
     throw new Error(
       `Machine ${settled.name} failed to be created${reason}; delete it with \`tonbo machine delete ${settled.name}\` and create it again.${hint}`
     );
@@ -3100,6 +3834,8 @@ async function machineCreateCommand(deps, name, command, options = {}) {
     const env = parseEnv(options.env ?? []);
     const ports = withDefault(parsePorts(options.port ?? []), options.defaultPort);
     const key = await deps.auth.apiKey();
+    const bound = typeof options.volume === "string" ? await resolveVolumeBinding(deps, key, options.volume) : null;
+    const region = options.region ?? bound?.region;
     const shape = options.shape ?? (await deps.api.listMachineShapes(key)).default;
     let created;
     try {
@@ -3109,15 +3845,16 @@ async function machineCreateCommand(deps, name, command, options = {}) {
           name,
           image: options.image,
           shape,
-          region: options.region,
+          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
+          stop_grace_seconds: options.stopGrace,
+          ...bound ? { volumes: [bound.binding] } : {}
         },
-        options.idempotencyKey ?? randomUUID3()
+        options.idempotencyKey ?? randomUUID4()
       );
     } catch (error) {
       if (error instanceof HttpError && error.code === "name_taken")
@@ -3127,8 +3864,9 @@ async function machineCreateCommand(deps, name, command, options = {}) {
     const { machine } = created;
     specWarnings(deps, machine.ports, Object.keys(env));
     if (machine.state === "failed") {
-      print(deps, options.json, machine, machineFields(machine));
-      const { reason, hint } = creationFailureText(machine);
+      const billing = await billingUrl(deps);
+      print(deps, options.json, machine, machineFields(machine, billing));
+      const { reason, hint } = creationFailureText(machine, billing);
       throw new Error(
         `Machine ${machine.name} failed to be created${reason}; delete it with \`tonbo machine delete ${machine.name}\` and create it again.${hint}`
       );
@@ -3143,7 +3881,12 @@ async function machineCreateCommand(deps, name, command, options = {}) {
         timeout,
         options.json
       );
-    print(deps, options.json, machine, [createdText(machine), machineText(machine)].join("\n"));
+    print(
+      deps,
+      options.json,
+      machine,
+      [createdText(machine), machineText(machine, await billingUrl(deps))].join("\n")
+    );
   });
 }
 async function machineShowCommand(deps, name, options = {}) {
@@ -3151,7 +3894,12 @@ async function machineShowCommand(deps, name, options = {}) {
     const key = await deps.auth.apiKey();
     const { machine, etag } = await deps.api.getMachineWithEtag(key, name);
     const lastEnd = options.json || machine.kind === "byoc" || machine.state !== "active" ? null : await lastActivationEnd(deps, key, machine.name);
-    print(deps, options.json, machine, anyMachineText(machine, etag, lastEnd));
+    print(
+      deps,
+      options.json,
+      machine,
+      anyMachineText(machine, await billingUrl(deps), etag, lastEnd)
+    );
   });
 }
 async function lastActivationEnd(deps, key, name) {
@@ -3194,7 +3942,7 @@ function appliesText(name, change) {
   const lines = [];
   if (change.ports !== void 0 || change.sleep_after_seconds !== void 0)
     lines.push("Ports and sleep-after apply now.");
-  const later = [change.image, change.command, change.shape, change.env].some(
+  const later = [change.image, change.command, change.shape, change.env, change.volumes].some(
     (field) => field !== void 0
   );
   if (later) {
@@ -3242,6 +3990,9 @@ async function machineUpdateCommand(deps, name, command, options = {}) {
       for (const variable of options.unsetEnv ?? []) delete env[variable];
       change.env = env;
     }
+    if (options.volume === false) change.volumes = [];
+    else if (typeof options.volume === "string")
+      change.volumes = [(await resolveVolumeBinding(deps, key, options.volume)).binding];
     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.");
@@ -3254,7 +4005,7 @@ async function machineUpdateCommand(deps, name, command, options = {}) {
       [
         `Updated Machine ${machine.name} to revision ${machine.revision}.`,
         ...appliesText(machine.name, change),
-        machineText(machine)
+        machineText(machine, await billingUrl(deps))
       ].join("\n")
     );
   });
@@ -3374,6 +4125,528 @@ async function machineShapesCommand(deps, options = {}) {
   });
 }
 
+// src/help.ts
+var ENVIRONMENT = [
+  {
+    names: ["TONBO_API_KEY"],
+    description: "A personal key (`tbo_\u2026`) every command uses instead of the saved login, for non-interactive use such as CI. `tonbo logout` acts only on the saved login."
+  },
+  {
+    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: ["XDG_CONFIG_HOME"],
+    description: "Where the login file lives: `$XDG_CONFIG_HOME/tonbo/credentials.json` when it is set and not empty, else `$HOME/.config/tonbo/credentials.json`."
+  },
+  {
+    names: ["SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY"],
+    description: "Any of them marks an SSH session: without `DISPLAY` or `WAYLAND_DISPLAY` too, `tonbo login` approves with a device code instead of opening a browser here."
+  },
+  {
+    names: ["DISPLAY", "WAYLAND_DISPLAY"],
+    description: "Outside macOS and Windows, `tonbo login` opens the browser with `xdg-open`, which needs a graphical session; with neither set it approves with a device code."
+  }
+];
+var TOPICS = [
+  {
+    id: "output",
+    title: "Output and --json",
+    text: [
+      "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. Notices, next steps and warnings go to stderr. A command that prints the whole answer instead, because the fields beside `data` belong with the rows, says so."
+    ]
+  },
+  {
+    id: "pagination",
+    title: "Lists and pages",
+    text: [
+      "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`; run the same command with that `--cursor` for the next page. `--limit` asks for up to that many items, 1 to 200; the API answers 50 when it is not given, and a page may hold fewer."
+    ]
+  },
+  {
+    id: "exit-status",
+    title: "Exit status",
+    text: [
+      "0 when the command did what it says, and for `--help` and `--version`.",
+      "1 on any failure: the API refused the request, an argument or flag is wrong, a destructive command was not confirmed, or a `--wait` ended without the state it waited for (a failure, or its `--timeout`). A refusal prints the problem's detail, the fields a validation error names and the request's `X-Request-Id` to stderr; an invalid or expired key adds `Run tonbo login`."
+    ]
+  },
+  {
+    id: "credentials",
+    title: "Keys and the login file",
+    text: [
+      "Every command but `login` and `logout` sends a personal key as its Bearer credential: `TONBO_API_KEY` when it is set, else the key `tonbo login` saved. What a command may do is what that key's member may do in the account, as narrowed by the key; the CLI never decides it.",
+      "The login is saved at `${XDG_CONFIG_HOME:-$HOME/.config}/tonbo/credentials.json`, which `yield` shares: either CLI's `login` signs both in, and either `logout` signs both out. The CLI replaces the file atomically with owner-only permissions and refuses a symlink or a file other users can read. A file an earlier release wrote is never migrated; run `tonbo login`."
+    ]
+  },
+  {
+    id: "retries",
+    title: "Retried creations",
+    text: [
+      "`agent create`, `bucket create`, `database create`, `stream create`, `machine create` and `volume 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; run the command again with that key and the same arguments, and it returns what the first request created instead of creating a second one. A key reused with other arguments is refused with `idempotency_conflict`.",
+      "`api-key create` takes no idempotency key, because a key's secret is never stored and a replay could not return it; a live key's name is unique, so a blind retry is refused with 409 rather than creating a second key. Every other command reads, or sets a resource to the state it names, so running it again does no more than the first run did; a repeated delete or revoke may be refused because the first one already removed it."
+    ]
+  },
+  {
+    id: "confirmations",
+    title: "Destructive commands",
+    text: [
+      "`api-key revoke`, `bucket delete`, `database delete`, `stream delete`, `machine delete` and `volume delete` ask before they act when stdin and stderr are a terminal: a revocation is confirmed by typing `yes`, a deletion by typing the resource's name, as in the console. Without a terminal they refuse unless `--yes` is given."
+    ]
+  }
+];
+var LIMIT_DEFAULT = "50, the API's default";
+var PERIOD_DEFAULT = "the current month";
+var DATA_REGION_DEFAULT = "the region `tonbo region list` marks as the database default";
+var ACTIVITY_DEFAULTS = {
+  "--granularity": "hour",
+  "--from": "24 hours (or 30 days for `day`) before --to",
+  "--to": "the end of the current hour (or day)"
+};
+var USAGE_DEFAULTS = {
+  "--period": PERIOD_DEFAULT,
+  "--sort": "list_value",
+  "--limit": LIMIT_DEFAULT
+};
+var EXPIRY_DEFAULTS = { "--expires-at": "never", "--expires-in": "never" };
+var NAME = (noun) => ({ name: `the ${noun}'s name` });
+var COMMAND_HELP = {
+  "tonbo login": {
+    about: [
+      "Prints the login URL and opens the browser at `https://tonbo.dev/cli/login`, where you pick the account and approve a personal API key named `CLI on <hostname>`. The browser returns a one-time code to a local callback on `127.0.0.1`, and the CLI redeems it with its PKCE verifier for the key.",
+      "The key acts as you, with your role in that account. It expires after six months and replaces the key an earlier login on the same computer created; there is no refresh, so an expired or revoked key asks you to run `tonbo login` again. `tonbo` acts in the account of the last login: log in again to switch. The login file keeps one key per account of this computer beside it, for `yield`; a key in an account other than your personal one is named `Yield CLI \xB7 <8 hex>` instead of after the host.",
+      "When the browser is on another computer, the login uses a device code instead: with `--device`, in an SSH session without a display, or when no browser can be opened here. The CLI prints a short code and `https://tonbo.dev/cli/device`; open it in any browser where you are signed in, enter the code, check the computer name it shows, pick the account and approve. The CLI polls and saves the same key. The code works once and expires after ten minutes."
+    ],
+    examples: ["tonbo login", "tonbo login --device"],
+    defaults: { "--account": "your personal account" }
+  },
+  "tonbo logout": {
+    about: [
+      "Revokes every account's key in the login file, each with its own credential, and removes the file, which signs `yield` out too. A key that is already revoked or expired is skipped. If another revocation fails, the file is still removed, and the CLI prints the key's id and exits 1, so you can revoke it under API keys in the console. `TONBO_API_KEY` is never touched."
+    ],
+    examples: ["tonbo logout"]
+  },
+  "tonbo account show": {
+    about: [
+      "Prints the account you are logged in to: its id, name and kind, your member subject and role in it, and its limits."
+    ],
+    examples: ["tonbo account show --json"]
+  },
+  "tonbo region list": {
+    about: [
+      "Shows each region new resources can be created in, with its data-plane origin, and marks the default region for new databases and streams."
+    ],
+    examples: ["tonbo region list"]
+  },
+  "tonbo workspace list": {
+    about: [
+      "Lists the account's git workspaces, the default first: each one's id, name, whether it is the default, its region and where it is served (`<git origin>/<ws_hex>`, the prefix of every repository URL in it). Every account has a default workspace from its creation. Listing needs only a role on the account and admits nothing; every git token is still admitted when it is minted."
+    ],
+    examples: ["tonbo workspace list"],
+    defaults: { "--limit": LIMIT_DEFAULT }
+  },
+  "tonbo member list": {
+    about: ["Lists the account's people and Agents with their kind, subject, name and role."],
+    examples: ["tonbo member list --limit 20"],
+    defaults: { "--limit": LIMIT_DEFAULT }
+  },
+  "tonbo member update": {
+    about: [
+      "Gives a member another role (`owner`, `admin` or `member`; only an owner grants `owner`), renames an Agent with `--name`, or both at once. Give at least one of them.",
+      "`<member>` is a member subject: a person's user id, or `agent.<agent id>` for an Agent. An Agent's bare id or its name works too: the CLI looks it up in `tonbo member list` and uses it only when exactly one member matches."
+    ],
+    examples: ["tonbo member update pi-live --role admin"],
+    arguments: { member: "a member subject, or an Agent's id or name" }
+  },
+  "tonbo agent create": {
+    about: [
+      "Creates an Agent identity with a role. Every Agent has a home region, chosen when it is created and never changed. Without `--region`, Tonbo uses the only region that accepts new Agents; when several do, an interactive `agent create` asks which one, and a request without `--region` from a script, or with `--json`, is refused.",
+      "Create a key for the Agent with `tonbo api-key create --member <name>`."
+    ],
+    examples: ["tonbo agent create my-agent"],
+    arguments: NAME("Agent"),
+    defaults: {
+      "--role": "member",
+      "--region": "the only region that accepts new Agents",
+      "--idempotency-key": "a new UUID"
+    }
+  },
+  "tonbo api-key list": {
+    about: [
+      "Shows your keys, or every key of the account for an owner or admin, with the last four characters of each secret, whether it is read-only, what it reaches of buckets, databases and streams, and when it expires and was last used."
+    ],
+    examples: ["tonbo api-key list"],
+    defaults: { "--limit": LIMIT_DEFAULT }
+  },
+  "tonbo api-key create": {
+    about: [
+      "Creates a personal key for you, or with `--member` a key of an Agent (its subject, id or name; owners and admins only). `--read-only`, and either `--bucket` or any of `--database`, `--database-prefix`, `--stream` and `--stream-prefix` (repeat each for several), narrow the key for its whole life; a key narrowed to databases and streams reaches both, and `api-key list` and `api-key show` print what each key reaches.",
+      "The secret is printed once, in this answer only, with a warning on stderr: store it then, because no command can show it again. Without `--json` the answer also carries a ready-to-paste `TONBO_API_KEY=<secret>` line for your application's environment, and stderr notes that `TONBO_API_KEY` in your own shell overrides your `tonbo login`, for this CLI too. stderr never carries the secret."
+    ],
+    examples: [
+      "tonbo api-key create ci-reader --member pi-live --read-only --database-prefix run- --expires-in 6_months"
+    ],
+    arguments: { name: "the key's name, unique among the account's live keys" },
+    defaults: { "--member": "yourself", "--expires-in": "never" }
+  },
+  "tonbo api-key show": {
+    about: ["Prints one key's fields, as `api-key list` does; never its secret."],
+    examples: ["tonbo api-key show 70000000-0000-4000-8000-000000000007"],
+    arguments: { "key-id": "the key's id, as `tonbo api-key list` prints it" }
+  },
+  "tonbo api-key revoke": {
+    about: [
+      "Revokes the key and every token minted from it. At a terminal it asks you to type `yes` first."
+    ],
+    examples: ["tonbo api-key revoke 70000000-0000-4000-8000-000000000007 --yes"],
+    arguments: { "key-id": "the key's id, as `tonbo api-key list` prints it" }
+  },
+  "tonbo bucket list": {
+    about: [
+      "Prints each bucket's region, state, read access and URL; a stream in it lives at `{url}/{stream}`."
+    ],
+    examples: ["tonbo bucket list"],
+    defaults: { "--limit": LIMIT_DEFAULT }
+  },
+  "tonbo bucket create": {
+    about: ["Creates a bucket in `--region` and prints its fields with its URL."],
+    examples: ["tonbo bucket create events"],
+    arguments: NAME("bucket"),
+    defaults: { "--region": "the account's default region", "--idempotency-key": "a new UUID" }
+  },
+  "tonbo bucket show": {
+    about: ["Prints the bucket's region, state, read access and URL."],
+    examples: ["tonbo bucket show events"],
+    arguments: NAME("bucket")
+  },
+  "tonbo bucket update": {
+    about: [
+      "Publishes the bucket for anonymous reads with `--public`, or takes it private with `--private`."
+    ],
+    examples: ["tonbo bucket update events --public"],
+    arguments: NAME("bucket")
+  },
+  "tonbo bucket delete": {
+    about: [
+      "Deletes the bucket and every stream in it; the bucket's name is never used again. At a terminal it asks you to type the bucket's name first."
+    ],
+    examples: ["tonbo bucket delete events --yes"],
+    arguments: NAME("bucket")
+  },
+  "tonbo database list": {
+    about: [
+      "Lists the account's databases in every region with their kind, region, state, read access, last write, stored size and URL. A region that cannot be read is named on stderr, and its sizes show as unknown."
+    ],
+    examples: ["tonbo database list --prefix run-"],
+    defaults: { "--limit": LIMIT_DEFAULT }
+  },
+  "tonbo database create": {
+    about: [
+      'Creates a database in `--region` and prints its fields with its URL. Without `--json` it then writes the next step to stderr: the packages to install and `openDatabase("<name>")` from `@tonbo/sdk/database`, which opens the database by name with your key.',
+      "`--expires-at` (an RFC 3339 time, at least 60 seconds after the creation) or `--expires-in` (`90s` or more, such as `30m`, `24h` or `7d`, counted from now) gives the database an expiry fixed for its life: once it passes, Tonbo deletes the database within a minute, as `database delete` would, and its name is free again. `--expires-in` is counted from when the command runs, so it never goes with `--idempotency-key`: an unconfirmed creation with an expiry prints its key and the absolute time it sent, and the retry passes that time with `--expires-at`. A Machine's database never expires."
+    ],
+    examples: ["tonbo database create scratch --expires-in 24h"],
+    arguments: { name: "the database's name, unique among the account's databases" },
+    defaults: {
+      "--region": DATA_REGION_DEFAULT,
+      ...EXPIRY_DEFAULTS,
+      "--idempotency-key": "a new UUID"
+    }
+  },
+  "tonbo database show": {
+    about: [
+      "Prints the database's kind, region, state, read access, URL, expiry, incarnation, last write, stored size, and when and by whom it was created."
+    ],
+    examples: ["tonbo database show notes"],
+    arguments: NAME("database")
+  },
+  "tonbo database update": {
+    about: [
+      "Publishes the database for anonymous reads with `--public`, or takes it private with `--private`. Owners and admins only."
+    ],
+    examples: ["tonbo database update notes --public"],
+    arguments: NAME("database")
+  },
+  "tonbo database delete": {
+    about: [
+      "Deletes the database and everything in it; its name is free again. At a terminal it asks you to type the database's name first."
+    ],
+    examples: ["tonbo database delete scratch --yes"],
+    arguments: NAME("database")
+  },
+  "tonbo database activity": {
+    about: [
+      "Prints one row per UTC hour or day of the window: the write units, bytes appended, records, successful reads and live (long-poll or SSE) reads of that step, and the log and snapshot size at its end. A step that has not started, or a size before the meter's first sample, is empty. The window is at most 31 days."
+    ],
+    examples: ["tonbo database activity notes --granularity day"],
+    arguments: NAME("database"),
+    defaults: ACTIVITY_DEFAULTS
+  },
+  "tonbo database usage": {
+    about: [
+      "Prints each database's usage of one calendar month in UTC at list price, before the monthly allowance and credit: its write units, log and snapshot GiB-months and list value, then the account's other metered usage (its streams and everything else). The charges after allowance and credit are in `tonbo usage show`."
+    ],
+    examples: ["tonbo database usage --period 2026-10 --sort name"],
+    defaults: USAGE_DEFAULTS,
+    json: "answer"
+  },
+  "tonbo stream list": {
+    about: [
+      "Lists the account's raw durable streams in every region with their region, state, content type, read access, last write, stored size and URL. A region that cannot be read is named on stderr."
+    ],
+    examples: ["tonbo stream list --prefix run-"],
+    defaults: { "--limit": LIMIT_DEFAULT }
+  },
+  "tonbo stream create": {
+    about: [
+      "Creates a raw durable stream in `--region` with the content type every append must send (one lowercase `type/subtype` without parameters), and prints its fields with its URL on the region's Streams origin. Without `--json` it then writes the next step to stderr: append with `POST` to the URL and read with `GET` from `?offset=-1`, with any Durable Streams client.",
+      "A stream and a database may share a name: each kind has its own names, limit and usage. `--expires-at` and `--expires-in` give the stream an expiry fixed for its life, by the same rules as `database create`'s: once it passes, Tonbo deletes the stream within a minute and its name is free again. A key narrowed to streams (`api-key create --stream` or `--stream-prefix`) reaches only those streams."
+    ],
+    examples: ["tonbo stream create events --content-type application/json"],
+    arguments: { name: "the stream's name, unique among the account's streams" },
+    defaults: {
+      "--region": DATA_REGION_DEFAULT,
+      "--content-type": "application/octet-stream",
+      ...EXPIRY_DEFAULTS,
+      "--idempotency-key": "a new UUID"
+    }
+  },
+  "tonbo stream show": {
+    about: [
+      "Prints the stream's region, state, content type, expiry, read access, URL, incarnation, last write, stored size, and when and by whom it was created."
+    ],
+    examples: ["tonbo stream show events"],
+    arguments: NAME("stream")
+  },
+  "tonbo stream update": {
+    about: [
+      "Publishes the stream for anonymous reads with `--public`, or takes it private with `--private`. Owners and admins only."
+    ],
+    examples: ["tonbo stream update events --private"],
+    arguments: NAME("stream")
+  },
+  "tonbo stream delete": {
+    about: [
+      "Deletes the stream and everything in it; its name is free again. At a terminal it asks you to type the stream's name first."
+    ],
+    examples: ["tonbo stream delete run-42 --yes"],
+    arguments: NAME("stream")
+  },
+  "tonbo stream activity": {
+    about: [
+      "Prints one row per UTC hour or day of the window: the write units, bytes appended, records, successful reads and live (long-poll or SSE) reads of that step, and the log and snapshot size at its end. A step that has not started, or a size before the meter's first sample, is empty. The window is at most 31 days."
+    ],
+    examples: ["tonbo stream activity events --from 2026-11-01T00:00:00Z"],
+    arguments: NAME("stream"),
+    defaults: ACTIVITY_DEFAULTS
+  },
+  "tonbo stream usage": {
+    about: [
+      "Prints each stream's usage of one calendar month in UTC at list price, before the monthly allowance and credit, then the account's other metered usage (its databases and everything else). The charges after allowance and credit are in `tonbo usage show`."
+    ],
+    examples: ["tonbo stream usage --names events,run-42"],
+    defaults: USAGE_DEFAULTS,
+    json: "answer"
+  },
+  "tonbo machine list": {
+    about: [
+      "Lists the account's Machines in every region with their region, state, power, shape, image, HTTPS hostname and conditions. In a personal account it also lists your own computers, which `yield login` registers, in a second table with their system, agent harnesses, when they last reported and the state of their login key. An organization lists Machines only."
+    ],
+    examples: ["tonbo machine list"],
+    defaults: { "--limit": LIMIT_DEFAULT }
+  },
+  "tonbo machine create": {
+    about: [
+      "Creates a Machine, a VM booted from an image in one region with its own database. The image is a public OCI image with a linux/arm64 variant, from Docker Hub or another public registry (`nginx:1.27`, `ghcr.io/org/app:v1`, or one pinned by digest), or `tonbo.dev/platform`, the platform image. A registry reachable only over IPv6, one named by an IP address, and one that redirects its manifests are refused. The CLI resolves a registry image to its linux/arm64 digest, and the image is pulled before the Machine leaves `creating`.",
+      "The Machine is served at `https://<name>-<account>.tonbo.sh` on its default port. `--port <port>` serves a private port, which takes a member's token, and `--port <port>:public` an open one, which needs the `machines.public` capability. A command after `--` replaces the image's CMD. The CLI warns on stderr when the Machine has no port, since nothing can wake it then, and when an `--env` key looks secret: env values are readable by every member through the API.",
+      "The answer is the Machine while it is `creating`. With `--wait` the CLI reads it until it is `active` or `failed`, or `--timeout` passes: a failure prints what to do and exits 1, and a timeout says it is still creating and undoes nothing. A creation the network or a 5xx answer did not confirm is sent at most three times with the same idempotency key, each retry after its `Retry-After` (at most 30 s) or a short backoff; a `name_taken` refusal says which Machine holds the name and how old it is, in case it is yours from a lost reply. In a region not open for Machines the creation is refused with `region_not_offered`, and nothing is created."
+    ],
+    examples: ["tonbo machine create web --image nginx:1.27 --port 80:public --wait"],
+    arguments: {
+      name: "the Machine's name, part of its hostname",
+      command: "the command that replaces the image's CMD, after `--`"
+    },
+    defaults: {
+      "--shape": "the shape `tonbo machine shapes` marks as the default",
+      "--default-port": "the first --port",
+      "--region": "the --volume's region, else the account's default region",
+      "--idempotency-key": "a new UUID",
+      "--timeout": String(DEFAULT_WAIT_SECONDS)
+    }
+  },
+  "tonbo machine show": {
+    about: [
+      "Prints the Machine's state and what it means (an `active` Machine that is asleep boots on its first request), its hostnames, image and whether it is pulled, the live activation and conditions with what to do about each, when it sleeps, its database and logs URLs, a link to what its disk keeps, its ETag and who created it. For an `active` Machine it also reads the newest activations and prints how the last one ended. When the live activation runs an older revision than the Machine's, it says which changes already apply and that the rest apply after `tonbo machine sleep <name>`.",
+      "When the default port is private, it prints the `curl` call that reaches it with a personal key. For one of your computers it prints its system, harnesses, hostname and device id, which only you see."
+    ],
+    examples: ["tonbo machine show web"],
+    arguments: NAME("Machine")
+  },
+  "tonbo machine update": {
+    about: [
+      "Changes only what its options name. It reads the Machine and sends the ETag it read, or `--if-match`'s, so a change someone made in between is refused with `precondition_failed` rather than overwritten; a Machine whose creation failed is refused with `machine_failed`. `--env` and `--unset-env` change single variables; `--port` replaces every port, and the current default port stays the default while it is still listed.",
+      "Ports and `--sleep-after` apply at once. The image, command, shape and env apply at the next boot, and the command says how to apply them now: `tonbo machine sleep`, after which the next request boots the new spec. Naming the same tag again resolves its digest again."
+    ],
+    examples: ["tonbo machine update web --env MODE=staging --sleep-after 300"],
+    arguments: {
+      name: "the Machine's name",
+      command: "the command that replaces the Machine's command at the next boot, after `--`"
+    },
+    defaults: {
+      "--default-port": "the current default while --port still lists it, else the first --port",
+      "--if-match": "the ETag the command reads"
+    }
+  },
+  "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."
+    ],
+    examples: ["tonbo machine sleep web --wait"],
+    arguments: NAME("Machine"),
+    defaults: { "--timeout": String(DEFAULT_WAIT_SECONDS) }
+  },
+  "tonbo machine delete": {
+    about: [
+      "Deletes the Machine with its disk, database and logs; its name is free for a new Machine at once. At a terminal it asks you to type the Machine's name first, and sends the ETag it read then.",
+      "For one of your computers it forgets the computer: it leaves the list at once, and its name is free once the forget completes. Forgetting does not revoke the computer's key, so a computer whose key is still active registers again at its next start; run `yield logout` on it, or `tonbo api-key revoke`, first."
+    ],
+    examples: ["tonbo machine delete web --yes"],
+    arguments: NAME("Machine"),
+    defaults: { "--if-match": "the ETag read when asking for confirmation" }
+  },
+  "tonbo machine activations": {
+    about: [
+      "Lists the Machine's activations, newest first: the wake, what woke it, the spec revision and shape it ran, when it started and how it ended (its state, a reason such as `idle_early`, `workload_exited` with the exit code, or a refusal such as `payment_required`), or `live`."
+    ],
+    examples: ["tonbo machine activations web --limit 10"],
+    arguments: NAME("Machine"),
+    defaults: { "--limit": LIMIT_DEFAULT }
+  },
+  "tonbo machine shapes": {
+    about: [
+      "Lists the shapes a Machine may have, each with its vCPUs, memory, scratch disk, whether it is offered and can suspend, and its list price for an hour at full use, and marks the default."
+    ],
+    examples: ["tonbo machine shapes"],
+    json: "answer"
+  },
+  "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."
+    ],
+    examples: ["tonbo volume list"]
+  },
+  "tonbo volume create": {
+    about: [
+      "Creates a Volume of `--size` GiB in one region. It is billed by its live bytes, not its size. Mount it on a Machine of the same region with `tonbo machine update <machine> --volume <name>:<path>`; it attaches at the Machine's next boot."
+    ],
+    examples: ["tonbo volume create data --size 20"],
+    arguments: NAME("Volume"),
+    defaults: { "--region": "the account's default region", "--idempotency-key": "a new UUID" }
+  },
+  "tonbo volume show": {
+    about: [
+      "Prints the Volume's region, state, the Machine it is bound to, its size, live bytes, last commit and a link to what it keeps."
+    ],
+    examples: ["tonbo volume show data"],
+    arguments: NAME("Volume")
+  },
+  "tonbo volume delete": {
+    about: [
+      "Deletes the Volume and every byte on it; there are no Volume snapshots or backups. It is refused while a Machine has it. At a terminal it asks you to type the Volume's name first."
+    ],
+    examples: ["tonbo volume delete data --yes"],
+    arguments: NAME("Volume")
+  },
+  "tonbo usage show": {
+    about: [
+      "Prints the account's rated usage of one calendar month in UTC: one line per product, region, dimension and model with its quantity and amount, and the total, in US dollars."
+    ],
+    examples: ["tonbo usage show --period 2026-10"],
+    defaults: { "--period": PERIOD_DEFAULT }
+  },
+  "tonbo usage series": {
+    about: [
+      "Prints the account's spend one line per UTC day of the window, or one line per hour with `--hours`: at list price, what the monthly allowance and the credit balance paid, what is still unpaid, and what it cost beyond the allowance. Then the window's total, the month so far with its allowance and, after three complete days, the month at their run rate. Give at most one of `--days`, `--hours` and `--month`.",
+      "`--compare` adds the window before, of the same length, and the change."
+    ],
+    examples: ["tonbo usage series --days 7 --compare"],
+    defaults: { "--days": "30" }
+  },
+  "tonbo usage today": {
+    about: [
+      "Prints the account's write units per UTC hour of yesterday and today, in three columns: databases, streams and other."
+    ],
+    examples: ["tonbo usage today --json"]
+  }
+};
+var WIDTH = 80;
+function wrap(text, indent) {
+  const lines = [];
+  let line = "";
+  for (const word of text.split(/\s+/)) {
+    if (line && indent.length + line.length + 1 + word.length > WIDTH) {
+      lines.push(`${indent}${line}`);
+      line = word;
+    } else line = line ? `${line} ${word}` : word;
+  }
+  if (line) lines.push(`${indent}${line}`);
+  return lines.join("\n");
+}
+var paragraphs = (texts) => texts.map((text) => wrap(text, "  ")).join("\n\n");
+function commandHelpText(help) {
+  return [
+    "",
+    "Details:",
+    paragraphs(help.about),
+    "",
+    help.examples.length === 1 ? "Example:" : "Examples:",
+    help.examples.map((example) => `  $ ${example}`).join("\n")
+  ].join("\n");
+}
+function programHelpText() {
+  return [
+    ...TOPICS.flatMap((topic) => ["", `${topic.title}:`, paragraphs(topic.text)]),
+    "",
+    "Environment:",
+    ENVIRONMENT.map(
+      (variable) => `  ${variable.names.join(", ")}
+${wrap(variable.description, "      ")}`
+    ).join("\n")
+  ].join("\n");
+}
+function optionDescription(option) {
+  const text = Help.prototype.optionDescription.call(this, option);
+  return option.defaultValue === void 0 && option.defaultValueDescription ? `${text} (default: ${option.defaultValueDescription})` : text;
+}
+function applyHelp(program) {
+  const named = /* @__PURE__ */ new Set();
+  const walk = (command, words) => {
+    const path2 = words.join(" ");
+    command.configureHelp({ ...command.configureHelp(), optionDescription });
+    const help = COMMAND_HELP[path2];
+    if (help) {
+      named.add(path2);
+      for (const [name, text] of Object.entries(help.arguments ?? {})) {
+        const argument = command.registeredArguments.find((entry) => entry.name() === name);
+        if (!argument) throw new Error(`${path2} has no argument ${name}`);
+        argument.description = text;
+      }
+      for (const [flag, text] of Object.entries(help.defaults ?? {})) {
+        const option = command.options.find((entry) => entry.long === flag);
+        if (!option) throw new Error(`${path2} has no option ${flag}`);
+        option.defaultValueDescription = text;
+      }
+      command.addHelpText("after", commandHelpText(help));
+    }
+    for (const child of command.commands) walk(child, [...words, child.name()]);
+  };
+  walk(program, [program.name()]);
+  for (const path2 of Object.keys(COMMAND_HELP))
+    if (!named.has(path2)) throw new Error(`The help of ${path2} names no command`);
+  program.addHelpText("after", programHelpText());
+  return program;
+}
+
 // src/prompt.ts
 import select from "@inquirer/select";
 import { createInterface } from "node:readline/promises";
@@ -3434,7 +4707,7 @@ function operationOptions(command, operationId) {
     command.option("--cursor <cursor>", "continue from the cursor a previous page printed");
   return command.option("--json", "print the API data as JSON");
 }
-var ifMatchHelp = (action) => `${action} only the Machine at the ETag \`tonbo machine show\` printed (with or without its quotes); the ETag the command reads, if it reads one, by default`;
+var ifMatchHelp = (action) => `${action} only the Machine at the ETag \`tonbo machine show\` printed (with or without its quotes)`;
 var repeated = (value, previous = []) => [...previous, value];
 var roleOption = (description) => new Option("--role <role>", description).choices(accountRoles);
 function machineSpecOptions(command, update) {
@@ -3445,7 +4718,7 @@ function machineSpecOptions(command, update) {
     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" : ""}`,
+    "the port served at the Machine's hostname without a port prefix",
     parseWhole
   ).option(
     "--env <KEY=VALUE>",
@@ -3463,6 +4736,9 @@ function machineSpecOptions(command, update) {
     "--stop-grace <seconds>",
     "the seconds between SIGTERM and SIGKILL on a planned stop",
     parseWhole
+  ).option(
+    "--volume <name:path>",
+    `mount the Volume <name> (see tonbo volume list) at <path>; a Machine has at most one, of its own region${update ? "; applies at the next boot" : ""}`
   );
 }
 function parseExpiresIn(value) {
@@ -3481,7 +4757,10 @@ function parseUsageSort(value) {
 }
 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) => {
+  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").option(
+    "--device",
+    "approve with a code in a browser on any computer, as over SSH without a display"
+  ).action(async (options) => {
     await loginCommand(dependencies(), options);
   });
   program.command("logout").description("revoke this computer's key and remove the saved login").action(async () => logoutCommand(dependencies()));
@@ -3516,7 +4795,7 @@ function createProgram(dependencies = createDependencies) {
     async (subject, options) => memberUpdateCommand(dependencies(), subject, options)
   );
   operationOptions(
-    program.command("agent").description("manage the Agents of your account").command("create <name>").description("create an agent").addOption(roleOption("the Agent's role; member by default")).option(
+    program.command("agent").description("manage the Agents of your account").command("create <name>").description("create an agent").addOption(roleOption("the Agent's role")).option(
       "--region <region>",
       "permanent home region (see tonbo region list); required once several regions accept new agents"
     ).option(
@@ -3535,10 +4814,7 @@ function createProgram(dependencies = createDependencies) {
     async (options) => apiKeyListCommand(dependencies(), options)
   );
   operationOptions(
-    apiKey.command("create <name>").description("create a key and print its secret, once").option(
-      "--member <member>",
-      "an Agent (subject, id or name) to create the key for; yourself by default"
-    ).option("--read-only", "narrow the key to read-only actions, for its whole life").option(
+    apiKey.command("create <name>").description("create a key and print its secret, once").option("--member <member>", "an Agent (subject, id or name) to create the key for").option("--read-only", "narrow the key to read-only actions, for its whole life").option(
       "--bucket <name>",
       "narrow the key to this bucket, for its whole life; repeat for several",
       repeated
@@ -3559,9 +4835,7 @@ function createProgram(dependencies = createDependencies) {
       "narrow the key to the raw streams whose name starts with this, for its whole life; repeat for several; never with --bucket",
       repeated
     ).addOption(
-      new Option("--expires-in <period>", "when the key expires; never by default").choices(
-        apiKeyExpirations
-      )
+      new Option("--expires-in <period>", "when the key expires").choices(apiKeyExpirations)
     ),
     "createApiKey"
   ).action(
@@ -3581,10 +4855,7 @@ function createProgram(dependencies = createDependencies) {
     async (options) => bucketListCommand(dependencies(), options)
   );
   operationOptions(
-    bucket.command("create <name>").description("create a bucket").option(
-      "--region <region>",
-      "the bucket's region (see tonbo region list); the account's default region by default"
-    ).option(
+    bucket.command("create <name>").description("create a bucket").option("--region <region>", "the bucket's region (see tonbo region list)").option(
       "--idempotency-key <key>",
       "reuse the key of an unconfirmed creation to get the bucket it created"
     ),
@@ -3615,18 +4886,15 @@ function createProgram(dependencies = createDependencies) {
     async (options) => databaseListCommand(dependencies(), options)
   );
   operationOptions(
-    database.command("create <name>").description("create a database; its region is fixed for its life").option(
-      "--region <region>",
-      "the database's region (see tonbo region list); the database default region by default"
-    ).addOption(
+    database.command("create <name>").description("create a database; its region is fixed for its life").option("--region <region>", "the database's region (see tonbo region list)").addOption(
       new Option(
         "--expires-at <time>",
-        "delete the database after this RFC 3339 time, at least 60 seconds after its creation, such as 2026-11-01T00:00:00Z; never by default"
+        "delete the database after this RFC 3339 time, at least 60 seconds after its creation, such as 2026-11-01T00:00:00Z"
       ).conflicts("expiresIn")
     ).addOption(
       new Option(
         "--expires-in <duration>",
-        "delete the database this long after its creation, at least 90s: such as 90s, 30m, 24h or 7d; never by default; never with --idempotency-key"
+        "delete the database this long after its creation, at least 90s: such as 90s, 30m, 24h or 7d; never with --idempotency-key"
       ).argParser(parseExpiresIn).conflicts("expiresAt")
     ).option(
       "--idempotency-key <key>",
@@ -3655,10 +4923,15 @@ function createProgram(dependencies = createDependencies) {
     async (name, options) => databaseDeleteCommand(dependencies(), name, options)
   );
   operationOptions(
-    database.command("usage").description("each database's usage of one month at list price, before allowance and credit").option(
-      "--period <month>",
-      "the calendar month in UTC, as YYYY-MM; the current one by default"
-    ).option("--sort <order>", "list_value (highest first, the default) or name", parseUsageSort).option("--prefix <prefix>", "only databases whose name starts with this").option("--names <names>", "only these databases, up to 100 names, comma-separated"),
+    database.command("activity <name>").description("show a database's writes per hour or day and its size at each step's end").addOption(
+      new Option("--granularity <step>", "one row per UTC hour or day").choices(["hour", "day"])
+    ).option("--from <time>", "the window's start, an RFC 3339 time on a UTC hour (or day)").option("--to <time>", "the window's end, exclusive, at most 31 days after --from"),
+    "getDatabaseActivity"
+  ).action(
+    async (name, options) => databaseActivityCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    database.command("usage").description("each database's usage of one month at list price, before allowance and credit").option("--period <month>", "the calendar month in UTC, as YYYY-MM").option("--sort <order>", "list_value (highest first) or name", parseUsageSort).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)
@@ -3671,21 +4944,18 @@ function createProgram(dependencies = createDependencies) {
     async (options) => streamListCommand(dependencies(), options)
   );
   operationOptions(
-    stream.command("create <name>").description("create a stream; its region and content type are fixed for its life").option(
-      "--region <region>",
-      "the stream's region (see tonbo region list); the database default region by default"
-    ).option(
+    stream.command("create <name>").description("create a stream; its region and content type are fixed for its life").option("--region <region>", "the stream's region (see tonbo region list)").option(
       "--content-type <type>",
-      "the media type every append sends, such as application/json; application/octet-stream by default"
+      "the media type every append sends, such as application/json"
     ).addOption(
       new Option(
         "--expires-at <time>",
-        "delete the stream after this RFC 3339 time, at least 60 seconds after its creation, such as 2026-11-01T00:00:00Z; never by default"
+        "delete the stream after this RFC 3339 time, at least 60 seconds after its creation, such as 2026-11-01T00:00:00Z"
       ).conflicts("expiresIn")
     ).addOption(
       new Option(
         "--expires-in <duration>",
-        "delete the stream this long after its creation, at least 90s: such as 90s, 30m, 24h or 7d; never by default; never with --idempotency-key"
+        "delete the stream this long after its creation, at least 90s: such as 90s, 30m, 24h or 7d; never with --idempotency-key"
       ).argParser(parseExpiresIn).conflicts("expiresAt")
     ).option(
       "--idempotency-key <key>",
@@ -3714,10 +4984,15 @@ function createProgram(dependencies = createDependencies) {
     async (name, options) => streamDeleteCommand(dependencies(), name, options)
   );
   operationOptions(
-    stream.command("usage").description("each stream's usage of one month at list price, before allowance and credit").option(
-      "--period <month>",
-      "the calendar month in UTC, as YYYY-MM; the current one by default"
-    ).option("--sort <order>", "list_value (highest first, the default) or name", parseUsageSort).option("--prefix <prefix>", "only streams whose name starts with this").option("--names <names>", "only these streams, up to 100 names, comma-separated"),
+    stream.command("activity <name>").description("show a stream's writes per hour or day and its size at each step's end").addOption(
+      new Option("--granularity <step>", "one row per UTC hour or day").choices(["hour", "day"])
+    ).option("--from <time>", "the window's start, an RFC 3339 time on a UTC hour (or day)").option("--to <time>", "the window's end, exclusive, at most 31 days after --from"),
+    "getStreamActivity"
+  ).action(
+    async (name, options) => streamActivityCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    stream.command("usage").description("each stream's usage of one month at list price, before allowance and credit").option("--period <month>", "the calendar month in UTC, as YYYY-MM").option("--sort <order>", "list_value (highest first) or name", parseUsageSort).option("--prefix <prefix>", "only streams whose name starts with this").option("--names <names>", "only these streams, up to 100 names, comma-separated"),
     "listStreamUsage"
   ).action(
     async (options) => streamUsageCommand(dependencies(), options)
@@ -3735,20 +5010,13 @@ function createProgram(dependencies = createDependencies) {
         "create a Machine from an image; [command...] after -- replaces the image's CMD"
       ).requiredOption(
         "--image <reference>",
-        "the image the Machine boots: tonbo.dev/platform, or a public linux/arm64 OCI image once registry images are offered"
-      ).option(
-        "--region <region>",
-        "the Machine's region, fixed for its life; the account's default region by default"
-      ),
+        "the image the Machine boots: a public OCI image with a linux/arm64 variant (nginx:1.27, ghcr.io/org/app@sha256:...), or tonbo.dev/platform"
+      ).option("--region <region>", "the Machine's region, fixed for its life"),
       false
     ).option(
       "--idempotency-key <key>",
       "reuse the key of an unconfirmed creation to get the Machine it created"
-    ).option("--wait", "wait until the Machine is active, or say why it failed").option(
-      "--timeout <seconds>",
-      `how long --wait waits; ${DEFAULT_WAIT_SECONDS} by default`,
-      parseWhole
-    ),
+    ).option("--wait", "wait until the Machine is active, or say why it failed").option("--timeout <seconds>", "how long --wait waits, in seconds", parseWhole),
     "createMachine"
   ).action(
     async (name, command, options) => machineCreateCommand(dependencies(), name, command, options)
@@ -3763,7 +5031,7 @@ function createProgram(dependencies = createDependencies) {
     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, named as for create; 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("--if-match <etag>", ifMatchHelp("change")).option("--discard-snapshot", "apply a change that discards the Machine's snapshot"),
+      ).option("--image <reference>", "a new image, named as for create; 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("--if-match <etag>", ifMatchHelp("change")).option("--discard-snapshot", "apply a change that discards the Machine's snapshot").option("--no-volume", "remove the Machine's Volume at the next boot; the Volume is kept"),
       true
     ),
     "updateMachine"
@@ -3771,11 +5039,7 @@ function createProgram(dependencies = createDependencies) {
     async (name, command, options) => machineUpdateCommand(dependencies(), name, command, 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; ${DEFAULT_WAIT_SECONDS} by default`,
-      parseWhole
-    ),
+    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"
   ).action(
     async (name, options) => machineSleepCommand(dependencies(), name, options)
@@ -3798,16 +5062,52 @@ function createProgram(dependencies = createDependencies) {
     machine.command("shapes").description("list the shapes a Machine may have"),
     "listMachineShapes"
   ).action(async (options) => machineShapesCommand(dependencies(), options));
+  const volume = program.command("volume").description("the account's Volumes: durable disks a Machine of the same region mounts");
   operationOptions(
-    program.command("usage").description("the account's rated usage").command("show").description("show one month's rated usage").option(
-      "--period <month>",
-      "the calendar month in UTC, as YYYY-MM; the current one by default"
+    volume.command("list").description("list the Volumes in every region"),
+    "listVolumes"
+  ).action(async (options) => volumeListCommand(dependencies(), options));
+  operationOptions(
+    volume.command("create <name>").description("create a Volume; billed by its live bytes, not its size").requiredOption("--size <GiB>", "the Volume's size in GiB, 1 to 100, fixed for its life").option("--region <region>", "the Volume's region, fixed for its life").option(
+      "--idempotency-key <key>",
+      "reuse the key of an unconfirmed creation to get the Volume it created"
     ),
+    "createVolume"
+  ).action(
+    async (name, options) => volumeCreateCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    volume.command("show <name>").description("show a Volume, the Machine it is bound to and its live bytes"),
+    "getVolume"
+  ).action(
+    async (name, options) => volumeShowCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    volume.command("delete <name>").description("delete a Volume and its data; refused while a Machine has it").option("--yes", "delete without asking; required when stdin is not a terminal"),
+    "deleteVolume"
+  ).action(
+    async (name, options) => volumeDeleteCommand(dependencies(), name, options)
+  );
+  const usage = program.command("usage").description("the account's rated usage");
+  operationOptions(
+    usage.command("show").description("show one month's rated usage").option("--period <month>", "the calendar month in UTC, as YYYY-MM"),
     "getUsage"
   ).action(
     async (options) => usageShowCommand(dependencies(), options)
   );
-  return program;
+  operationOptions(
+    usage.command("series").description("show the account's spend day by day, or hour by hour").option("--days <count>", "the last 1 to 92 UTC days, today included", parseWhole).option("--hours <count>", "the last 1 to 48 hours, one line per hour", parseWhole).option("--month <month>", "one calendar month in UTC, as YYYY-MM").option("--compare", "also show the window before, and the change"),
+    "getUsageSeries"
+  ).action(
+    async (options) => usageSeriesCommand(dependencies(), options)
+  );
+  operationOptions(
+    usage.command("today").description(
+      "show the account's write units per hour of yesterday and today, by databases, streams and other"
+    ),
+    "getUsageToday"
+  ).action(async (options) => usageTodayCommand(dependencies(), options));
+  return applyHelp(program);
 }
 
 // src/main.ts