@tonbo/cli 0.18.0 → 0.20.0

package/README.md

@@ -26,7 +26,7 @@ The login file, `login.json`, and the device id it is tied to are shared with [`
 
 ## Commands and the Management API
 
-Every command other than `login` and `logout` is named by one operation of the [Management API](../../contracts/management/openapi-v1.yaml) through its `x-tonbo-cli` and calls that operation, plus reads of the same resource (a `--wait`, the Machine a `name_taken` refusal names, the activations `machine show` reads for the last end, or the Volume a `machine create` or `update --volume` names, read for its id and region); `tonbo machine logs`, once it ships, is the named Streams exception, reading the stream at the Machine's `logs.url`. The command set and the operations tagged with a command are the same set, which `test/commands.test.ts` checks in both directions. The CLI resolves each request from the operation table of the internal package [`@tonbo/cli-core`](../../packages/tonbo-cli-core) (`src/generated/contracts.ts`, which `pnpm --filter @tonbo/cli-core generate:contracts` derives from the contract). `login`, `logout`, `account list` and `account use` are the named exception: they obtain, choose among and discard what the other commands present as their Bearer credential. What a command may do is what your role in the account it acts in allows; the CLI never decides it.
+Every command other than `login` and `logout` is named by one operation of the [Management API](../../contracts/management/openapi-v1.yaml) through its `x-tonbo-cli` and calls that operation, plus reads of the same resource (a `--wait`, the Machine a `name_taken` refusal names, the activations `machine show` reads for the last end, or the Volume a `machine create` or `update --volume` names, read for its id and region); `tonbo machine logs`, once it ships, is the named Streams exception, reading the stream at the Machine's `logs.url`. `tonbo volume move` is the one command that sends another command's operation: it reads the Volume and both Machines and sends the target's `updateMachine` with `move_from` (the `machine create --move-from` of an existing Machine, docs/design/machines-volume-move.md). Apart from it, the command set and the operations tagged with a command are the same set, which `test/commands.test.ts` checks in both directions. The CLI resolves each request from the operation table of the internal package [`@tonbo/cli-core`](../../packages/tonbo-cli-core) (`src/generated/contracts.ts`, which `pnpm --filter @tonbo/cli-core generate:contracts` derives from the contract). `login`, `logout`, `account list` and `account use` are the named exception: they obtain, choose among and discard what the other commands present as their Bearer credential. What a command may do is what your role in the account it acts in allows; the CLI never decides it.
 
 The help lives with the commands: [`src/app.ts`](src/app.ts) defines each command, its arguments and flags with their one-line descriptions, and [`src/help.ts`](src/help.ts) holds the long help, each flag's default, the examples, the shared rules and the environment. [`commands.json`](commands.json) is all of it as `--help` prints it, which the docs' CLI reference renders; `test/commands.test.ts` holds it to the program, and holds every runnable command to its details and example and the environment list to the variables the code reads, so after changing a command run `pnpm --filter @tonbo/cli commands`.
 

package/dist/bin/tonbo.js

@@ -364,6 +364,20 @@ var managementOperations = {
     "idempotencyKey": false,
     "cli": "tonbo usage series"
   },
+  "getVolumeMetrics": {
+    "method": "GET",
+    "path": "/metrics/volumes",
+    "pathParams": [],
+    "query": [
+      "series",
+      "window",
+      "granularity",
+      "from",
+      "to"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo metrics volumes"
+  },
   "getUsageToday": {
     "method": "GET",
     "path": "/usage/today",
@@ -414,6 +428,7 @@ var managementOperations = {
     "pathParams": [],
     "query": [
       "device_id",
+      "project",
       "cursor",
       "limit"
     ],
@@ -2316,6 +2331,10 @@ var ManagementApi = class {
   getUsageSeries(key, query = {}) {
     return this.call("getUsageSeries", key, { query });
   }
+  /** The account's Volume metrics over a window, such as what they stored each day. */
+  getVolumeMetrics(key, query = {}) {
+    return this.call("getVolumeMetrics", key, { query });
+  }
   /** The account's writes of yesterday and today, hourly, per lane. */
   getUsageToday(key) {
     return this.call("getUsageToday", key);
@@ -2363,7 +2382,8 @@ var ManagementApi = class {
         return {
           machine: answer.data,
           location: headers.location,
-          retryAfterSeconds: retryAfterSeconds(headers.retryAfter)
+          retryAfterSeconds: retryAfterSeconds(headers.retryAfter),
+          volumeMove: answer.volume_move ?? null
         };
       } catch (error) {
         if (error instanceof HttpError && error.status < 500)
@@ -2426,6 +2446,13 @@ var ManagementApi = class {
       ifMatch: etag
     });
   }
+  /** An update whose binding names `move_from`: the Machine, and what the
+   * move did, which the answer carries beside it
+   * (docs/design/machines-volume-move.md). */
+  async moveVolume(key, name, etag, change) {
+    const answer = await this.request("updateMachine", key, { params: { name }, body: withoutUndefined(change), ifMatch: etag });
+    return { machine: answer.data, volumeMove: answer.volume_move ?? null };
+  }
   /** With `etag`, only the Machine that ETag names, at that revision, is put
    * to sleep (machine-v2.json `etag.if_match.sleep` is optional). A 202
    * carries the `Retry-After` to read the Machine again after
@@ -2811,7 +2838,8 @@ function accountLogins(login) {
     ...entry,
     account_id,
     kind: entry.kind ?? null,
-    name: entry.name ?? null
+    name: entry.name ?? null,
+    role: entry.role ?? null
   }));
   if (!entries.some((entry) => entry.account_id === login.account_id))
     entries.unshift({
@@ -2820,12 +2848,18 @@ function accountLogins(login) {
       key: login.key,
       expires_at: login.expires_at,
       kind: null,
-      name: null
+      name: null,
+      role: null
     });
   return entries;
 }
 function personalLogin(login) {
-  return accountLogins(login).find((entry) => entry.kind === "user") ?? null;
+  const logins = accountLogins(login);
+  const personal = login.session?.personalAccountId;
+  return (personal ? logins.find((entry) => entry.account_id === personal) : void 0) ?? logins.find((entry) => entry.kind === "user" && !isGuestLogin(entry)) ?? null;
+}
+function isGuestLogin(login) {
+  return login.role === "collaborator";
 }
 async function preparePrivateDirectory(directory) {
   const stat3 = await lstat(directory);
@@ -3379,7 +3413,8 @@ var LoginStore = class {
       key: client.bearer(id),
       expires_at: current.session.expires_at,
       kind: current.accounts?.[id]?.kind ?? (id === current.personal_account_id ? "user" : null),
-      name: current.accounts?.[id]?.name ?? null
+      name: current.accounts?.[id]?.name ?? null,
+      role: current.accounts?.[id]?.role ?? null
     });
     accounts[current.personal_account_id] = entry(current.personal_account_id);
     for (const id of Object.keys(current.accounts ?? {}))
@@ -5264,6 +5299,37 @@ async function usageSeriesCommand(deps, options = {}) {
     );
   print(deps, options.json, series, lines.join("\n"));
 }
+async function metricsVolumesCommand(deps, options = {}) {
+  const metrics = await deps.api.getVolumeMetrics(await deps.auth.apiKey(), {
+    series: "stored_bytes",
+    window: options.window,
+    granularity: options.from || options.to ? "day" : void 0,
+    from: options.from,
+    to: options.to
+  });
+  const points = metrics.total.points;
+  const lines = [
+    `What the Volumes stored from ${metrics.from.slice(0, 10)} to ${metrics.to.slice(0, 10)} (UTC, average per day)`,
+    table(
+      ["DAY", "STORED", ""],
+      points.map((point) => [
+        point.start.slice(0, 10),
+        bytes(point.stored_bytes),
+        point.partial ? "so far" : ""
+      ])
+    )
+  ];
+  const complete = points.filter((point) => !point.partial);
+  if (complete.length > 1) {
+    const change = complete[complete.length - 1].stored_bytes - complete[0].stored_bytes;
+    lines.push(
+      `Change over its complete days: ${change < 0 ? "-" : "+"}${bytes(Math.abs(change))}`
+    );
+  }
+  if (metrics.unavailable_regions.length > 0)
+    lines.push(`Not read: ${metrics.unavailable_regions.join(", ")}`);
+  print(deps, options.json, metrics, lines.join("\n"));
+}
 async function streamActivityCommand(deps, name, options = {}) {
   const activity = await deps.api.getStreamActivity(
     await deps.auth.apiKey(),
@@ -5520,6 +5586,57 @@ async function volumeDeleteCommand(deps, name, options = {}) {
     );
   });
 }
+function movedText(move, volume, target) {
+  return [
+    `Moved Volume ${volume} from ${move.from} to ${target}; it attaches at ${target}'s next boot, and ${move.from} boots without it.`,
+    ...move.replaced ? [
+      `${target}'s Volume ${move.replaced.name} was unbound and kept; bind it again with \`tonbo machine update <machine> --volume ${move.replaced.name}:<path>\`.`
+    ] : []
+  ];
+}
+async function volumeMoveCommand(deps, name, options = {}) {
+  await volumeCommand(deps, async () => {
+    if (!options.to) throw new Error("Pass --to <machine>.");
+    const to = options.to;
+    const key = await deps.auth.apiKey();
+    const volume = await deps.api.getVolume(key, name);
+    const from = volume.machine?.name ?? null;
+    if (from === to && options.path === void 0) {
+      print(
+        deps,
+        options.json,
+        volume,
+        `Volume ${volume.name} is already on ${to}; nothing to move.`
+      );
+      return;
+    }
+    const { machine: target, etag } = await deps.api.getMachineWithEtag(key, to);
+    if (target.kind === "byoc")
+      throw new Error(
+        `${to} is one of your computers; a Volume moves only to a Machine Tonbo runs.`
+      );
+    if (etag === null) throw new Error(`The API answered ${to} without an ETag.`);
+    const binding = { volume: volume.id };
+    let path6 = options.path;
+    if (from !== null && from !== to) {
+      const { machine: source, etag: sourceTag } = await deps.api.getMachineWithEtag(key, from);
+      const held = source.kind === "managed" ? source.volumes?.find((entry) => entry.volume === volume.id) : void 0;
+      path6 ??= held?.path;
+      binding.move_from = from;
+      if (sourceTag !== null) binding.move_from_etag = sourceTag;
+    }
+    if (path6 !== void 0) binding.path = path6;
+    const { machine, volumeMove: move } = await deps.api.moveVolume(key, to, etag, {
+      volumes: [binding]
+    });
+    print(
+      deps,
+      options.json,
+      machine,
+      move ? movedText(move, volume.name, machine.name).join("\n") : `Bound Volume ${volume.name} to ${machine.name}${path6 === void 0 ? " as its whole disk" : ` at ${path6}`}; it attaches at the next boot.`
+    );
+  });
+}
 function parseVolumeSpec(spec) {
   const split = spec.indexOf(":");
   if (split === -1 && spec.length > 0) return { name: spec };
@@ -5564,6 +5681,10 @@ var MACHINE_ERROR_HINTS = {
   root_mode_not_offered: "A Volume as the Machine's whole disk is not offered to this account yet; nothing was created or changed. Mount it at a path instead: --volume <name>:<path>.",
   rebuild_required: "This Machine's Volume is its whole disk, so its image changes only by Rebuild, which keeps /home, /workspace and /root and deletes every other change on the disk. Rebuild is not available yet: keep the image, or create a new Machine with the new image and a new Volume.",
   volume_mode_change: "The Volume cannot move between being the Machine's whole disk and being mounted at a path; nothing was changed. Bind a new Volume in the mode you want.",
+  volume_attached: "The Machine the message names is awake with the Volume attached; nothing was changed. Put it to sleep with `tonbo machine sleep <machine>`, then run the command again.",
+  volume_holder_changed: "The Volume is not on the Machine you named; nothing was changed. `tonbo volume show <volume>` says which Machine has it: name that one, or use `tonbo volume move`.",
+  volume_image_mismatch: "The Volume is a Machine's whole disk, made against one image; it moves only to a Machine on that same image. Nothing was changed.",
+  volume_rebuild_pending: "The Volume's Rebuild has not finished; move it once it has. Nothing was changed.",
   secret_env_conflict: "Use another secret key or remove the non-secret env variable with that name.",
   secret_limit: "Reduce the number or byte size of this Machine's secrets.",
   wake_unavailable: "The wake was refused for now; nothing woke. Wake it again after a while; `tonbo machine show` says why it is blocked."
@@ -6132,12 +6253,22 @@ async function waitForCreate(deps, key, machine, name, firstWait, timeout, json)
 async function machineCreateCommand(deps, name, command, options = {}) {
   await machineCommand(async () => {
     if (!options.image) throw new Error("Pass --image <reference>.");
+    if (options.moveFrom !== void 0 && typeof options.volume !== "string")
+      throw new Error("--move-from names the Machine that holds the --volume: pass --volume too.");
     const timeout = waitTimeout(options);
     const env = parseEnv(options.env ?? []);
     const secrets = createSecrets(options);
     const ports = withDefault(parsePorts(options.port ?? []), options.defaultPort);
     const key = await deps.auth.apiKey();
     const bound = typeof options.volume === "string" ? await resolveVolumeBinding(deps, key, options.volume) : null;
+    if (bound && options.moveFrom !== void 0) {
+      const { etag } = await deps.api.getMachineWithEtag(key, options.moveFrom);
+      bound.binding = {
+        ...bound.binding,
+        move_from: options.moveFrom,
+        ...etag === null ? {} : { move_from_etag: etag }
+      };
+    }
     const database = typeof options.database === "string" ? await deps.api.getDatabase(key, options.database) : null;
     if (database && bound && database.region !== bound.region && !options.region)
       throw new Error(
@@ -6197,7 +6328,11 @@ async function machineCreateCommand(deps, name, command, options = {}) {
       deps,
       options.json,
       machine,
-      [createdText(machine), machineText(machine, await billingUrl(deps))].join("\n")
+      [
+        createdText(machine),
+        ...created.volumeMove ? movedText(created.volumeMove, options.volume, machine.name) : [],
+        machineText(machine, await billingUrl(deps))
+      ].join("\n")
     );
   });
 }
@@ -6903,9 +7038,13 @@ var COMMAND_HELP = {
     about: [
       "Creates a Machine, a VM booted from an image in one region. It has no database of its own: `--database <name>` binds one of the account's databases of its region, which it then reaches at `TONBO_DATABASE_URL`, and a database binds one Machine at a time; its disk can last on a Volume (`--volume <name>` keeps the Machine's whole disk on it, and `--volume <name>:<path>` mounts it at a path instead), and its program can open any other database by URL with a key. The image is a public OCI image with a linux/arm64 variant, from Docker Hub or another public registry (`nginx:1.27`, `ghcr.io/org/app:v1`, or one pinned by digest), or `tonbo.dev/platform`, the platform image. A registry reachable only over IPv6, one named by an IP address, and one that redirects its manifests are refused. The CLI resolves a registry image to its linux/arm64 digest, and the image is pulled before the Machine leaves `creating`.",
       "The Machine is served at `https://<name>-<account>.tonbo.sh` on its default port. `--port <port>` serves a private port, which takes a member's token, and `--port <port>:public` an open one, which needs the `machines.public` capability. A command after `--` replaces the image's CMD. `--secret-env KEY=FILE` and `--secret-file KEY=FILE` read initial secrets from local files and store them with the Machine before its first boot; their values are never returned. The CLI warns on stderr when the Machine has no port, since nothing can wake it then, and when an `--env` key looks secret: env values are readable by every member through the API.",
+      "`--move-from <machine>` takes the `--volume` from the Machine that has it now, in the same write as the create: that Machine's binding is removed (its ETag changes) and it boots without the Volume. It is refused while that Machine is awake with the Volume attached (`volume_attached`: `tonbo machine sleep <machine>` first), or when another Machine has the Volume (`volume_holder_changed`); either way nothing is created or changed. Without it, a Volume another Machine has is refused.",
       "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"],
+    examples: [
+      "tonbo machine create web --image nginx:1.27 --port 80:public --wait",
+      "tonbo machine create agent --image nginx:1.27 --volume data:/workspace --move-from worker"
+    ],
     arguments: {
       name: "the Machine's name, part of its hostname",
       command: "the command that replaces the image's CMD, after `--`"
@@ -7170,6 +7309,15 @@ var COMMAND_HELP = {
     examples: ["tonbo volume show data"],
     arguments: NAME("Volume")
   },
+  "tonbo volume move": {
+    about: [
+      "Moves the Volume to the Machine `--to`, taking it from the Machine that has it now in one write: the Volume is unbound there (that Machine's ETag changes and it boots without it) and bound to `--to`, which may be awake and gets it at its next boot. The CLI reads both Machines' ETags first, so a Machine changed since is refused, never overwritten. Without `--path` the Volume keeps the path it has now, or stays a whole disk; a whole disk moves only to a Machine on the same image.",
+      'The Machine that has it must be asleep: an awake one is refused with `volume_attached`, and nothing changes; `tonbo machine sleep <machine>` first. When `--to` already has another Volume, that one is unbound and kept, and the CLI names it. The REST equivalent is `PATCH /v1/machines/<to>` with `If-Match: <its ETag>` and `{"volumes": [{"volume": "<id>", "path": "<path>", "move_from": "<machine>", "move_from_etag": "<its ETag>"}]}`.'
+    ],
+    examples: ["tonbo volume move data --to agent --path /workspace"],
+    arguments: NAME("Volume"),
+    defaults: { "--path": "the path the Volume has now, or none (a whole disk)" }
+  },
   "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."
@@ -7192,6 +7340,14 @@ var COMMAND_HELP = {
     examples: ["tonbo usage series --days 7 --compare"],
     defaults: { "--days": "30" }
   },
+  "tonbo metrics volumes": {
+    about: [
+      "Prints what the account's Volumes stored, one line per UTC day of the window: the average bytes their files held that day, compressed, summed over every region, which is what they are billed for. Today, and a day not fully rated yet, is marked `so far`. Then the change between the window's first and last complete days.",
+      "Give `--window`, or `--from` and `--to` (at most 92 days); the last 30 days when neither is given."
+    ],
+    examples: ["tonbo metrics volumes --window 7d"],
+    defaults: { "--window": "30d" }
+  },
   "tonbo usage today": {
     about: [
       "Prints the account's write units per UTC hour of yesterday and today, in three columns: databases, streams and other."
@@ -8917,6 +9073,9 @@ function createProgram(makeDependencies = createDependencies) {
       "read a UTF-8 environment secret from FILE; repeat",
       repeated
     ).option("--secret-file <KEY=FILE>", "read binary file secret from FILE; repeat", repeated).option(
+      "--move-from <machine>",
+      "take the --volume from the asleep Machine <machine> that has it, in the same write; that Machine boots without it"
+    ).option(
       "--idempotency-key <key>",
       "reuse the key of an unconfirmed creation to get the Machine it created"
     ).option("--wait", "wait until the Machine is active, or say why it failed").option("--timeout <seconds>", "how long --wait waits, in seconds", parseWhole),
@@ -9118,6 +9277,17 @@ function createProgram(makeDependencies = createDependencies) {
   ).action(
     async (name, options) => volumeShowCommand(dependencies(), name, options)
   );
+  operationOptions(
+    volume.command("move <name>").description(
+      "move a Volume to another Machine of its region, taking it from the asleep Machine that has it in the same write"
+    ).requiredOption("--to <machine>", "the Machine that gets the Volume; it may be awake").option(
+      "--path <path>",
+      "mount it at <path> there; without it, it keeps the path it has now, or stays a whole disk"
+    ),
+    "updateMachine"
+  ).action(
+    async (name, options) => volumeMoveCommand(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"
@@ -9143,6 +9313,13 @@ function createProgram(makeDependencies = createDependencies) {
     ),
     "getUsageToday"
   ).action(async (options) => usageTodayCommand(dependencies(), options));
+  const metrics = program.command("metrics").description("show how the account's resources are used over time");
+  operationOptions(
+    metrics.command("volumes").description("show what the account's Volumes stored, day by day").option("--window <window>", "the last 7d, 30d or 90d, today included").option("--from <day>", "with --to, the first UTC day, as YYYY-MM-DD").option("--to <day>", "with --from, the UTC day the window ends before, as YYYY-MM-DD"),
+    "getVolumeMetrics"
+  ).action(
+    async (options) => metricsVolumesCommand(dependencies(), options)
+  );
   const ssh = program.command("ssh").description("open a terminal on a Machine, or run a command there, over SSH").argument("<machine>", "the Machine's name").argument("[command...]", "a command to run instead of a shell, after --").action(async (name, command) => sshCommand(dependencies(), name, command));
   ssh.command("config").description(
     "print the ssh_config block that lets ssh, scp, sftp and Remote-SSH reach every Machine"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonbo/cli",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "The Tonbo CLI. Compute, disks, databases and streams for AI agents: your agent picks what it needs, sets it up, and knows what it costs, from the command line.",
   "homepage": "https://tonbo.dev",
   "bugs": {