@tonbo/cli 0.7.0 → 0.7.1

package/README.md

@@ -37,7 +37,7 @@ Every command other than `login` and `logout` calls one operation of the [Manage
 | `tonbo member update <member> [--role <role>] [--name <name>]` | `updateMember` | `PATCH /v1/members/{subject}` |
 | `tonbo agent create <name> [--role <role>] [--region <region>] [--idempotency-key <key>]` | `createAgent` | `POST /v1/agents` |
 | `tonbo api-key list [--limit <n>] [--cursor <c>]` | `listApiKeys` | `GET /v1/api-keys` |
-| `tonbo api-key create <name> [--member <member>] [--read-only] [--bucket <name>]… [--database <name>]… [--database-prefix <prefix>]… [--expires-in <period>]` | `createApiKey` | `POST /v1/api-keys` |
+| `tonbo api-key create <name> [--member <member>] [--read-only] [--bucket <name>]… [--database <name>]… [--database-prefix <prefix>]… [--stream <name>]… [--stream-prefix <prefix>]… [--expires-in <period>]` | `createApiKey` | `POST /v1/api-keys` |
 | `tonbo api-key show <key-id>` | `getApiKey` | `GET /v1/api-keys/{key_id}` |
 | `tonbo api-key revoke <key-id> [--yes]` | `revokeApiKey` | `DELETE /v1/api-keys/{key_id}` |
 | `tonbo bucket list [--limit <n>] [--cursor <c>]` | `listBuckets` | `GET /v1/buckets` |
@@ -46,11 +46,17 @@ Every command other than `login` and `logout` calls one operation of the [Manage
 | `tonbo bucket update <name> (--public \| --private)` | `updateBucket` | `PATCH /v1/buckets/{name}` |
 | `tonbo bucket delete <name> [--yes]` | `deleteBucket` | `DELETE /v1/buckets/{name}` |
 | `tonbo database list [--prefix <prefix>] [--limit <n>] [--cursor <c>]` | `listDatabases` | `GET /v1/databases` |
-| `tonbo database create <name> [--region <region>] [--idempotency-key <key>]` | `createDatabase` | `POST /v1/databases` |
+| `tonbo database create <name> [--region <region>] [--expires-at <time> \| --expires-in <duration>] [--idempotency-key <key>]` | `createDatabase` | `POST /v1/databases` |
 | `tonbo database show <name>` | `getDatabase` | `GET /v1/databases/{name}` |
 | `tonbo database update <name> (--public \| --private)` | `updateDatabase` | `PATCH /v1/databases/{name}` |
 | `tonbo database delete <name> [--yes]` | `deleteDatabase` | `DELETE /v1/databases/{name}` |
 | `tonbo database usage [--period <YYYY-MM>] [--sort list_value\|name] [--prefix <prefix>] [--names <a,b>] [--limit <n>] [--cursor <c>]` | `listDatabaseUsage` | `GET /v1/usage/databases` |
+| `tonbo stream list [--prefix <prefix>] [--limit <n>] [--cursor <c>]` | `listStreams` | `GET /v1/streams` |
+| `tonbo stream create <name> [--region <region>] [--content-type <type>] [--expires-at <time> \| --expires-in <duration>] [--idempotency-key <key>]` | `createStream` | `POST /v1/streams` |
+| `tonbo stream show <name>` | `getStream` | `GET /v1/streams/{name}` |
+| `tonbo stream update <name> (--public \| --private)` | `updateStream` | `PATCH /v1/streams/{name}` |
+| `tonbo stream delete <name> [--yes]` | `deleteStream` | `DELETE /v1/streams/{name}` |
+| `tonbo stream usage [--period <YYYY-MM>] [--sort list_value\|name] [--prefix <prefix>] [--names <a,b>] [--limit <n>] [--cursor <c>]` | `listStreamUsage` | `GET /v1/usage/streams` |
 | `tonbo usage show [--period <YYYY-MM>]` | `getUsage` | `GET /v1/usage` |
 | `tonbo machine list [--limit <n>] [--cursor <c>]` | `listMachines` | `GET /v1/machines` |
 | `tonbo machine create <name> --image <reference> [--shape <shape>] [--region <region>] [--port <port[:access]>]… [--default-port <port>] [--env <KEY=VALUE>]… [--sleep-after <seconds>] [--idle-action <action>] [--stop-grace <seconds>] [--idempotency-key <key>] [-- <command>…]` | `createMachine` | `POST /v1/machines` |
@@ -62,17 +68,17 @@ Every command other than `login` and `logout` calls one operation of the [Manage
 
 ### Output and errors
 
-Every command prints an aligned table or a list of fields for people. With `--json` it prints the answer's `data` exactly as the API returned it, one JSON value on stdout and nothing else there. A list prints one page; when there is another, the CLI writes `More results: run again with --cursor <cursor>` to stderr, so `--json` output stays the API's `data`. `database usage --json` and `machine shapes --json` print the whole answer, since the usage's `other` row, checkpoint and prices, and the default shape, belong with the rows. `--limit` asks for up to that many items (the API's default is 50, its maximum 200).
+Every command prints an aligned table or a list of fields for people. With `--json` it prints the answer's `data` exactly as the API returned it, one JSON value on stdout and nothing else there. A list prints one page; when there is another, the CLI writes `More results: run again with --cursor <cursor>` to stderr, so `--json` output stays the API's `data`. `database usage --json`, `stream usage --json` and `machine shapes --json` print the whole answer, since the usage's `other` row, checkpoint and prices, and the default shape, belong with the rows. `--limit` asks for up to that many items (the API's default is 50, its maximum 200).
 
 A refusal prints the problem's detail, the fields a validation error names, and the request's `X-Request-Id` to stderr, and the command exits with status 1. An invalid or expired key adds `Run tonbo login`.
 
 ### Retried creations
 
-`agent create`, `bucket create`, `database create` and `machine create` send an `Idempotency-Key`, a new UUID unless `--idempotency-key` names one. When a creation is not confirmed (the network failed or the server answered 5xx), the CLI prints its key; retrying with that key and the same arguments returns what the first request created instead of creating a second one. `api-key create` has no idempotency key, because a key's secret is never stored and a replay could not return it; a live key's name is unique, so a blind retry is refused with 409 rather than creating a second key.
+`agent create`, `bucket create`, `database create`, `stream create` and `machine create` send an `Idempotency-Key`, a new UUID unless `--idempotency-key` names one. When a creation is not confirmed (the network failed or the server answered 5xx), the CLI prints its key; retrying with that key and the same arguments returns what the first request created instead of creating a second one. `api-key create` has no idempotency key, because a key's secret is never stored and a replay could not return it; a live key's name is unique, so a blind retry is refused with 409 rather than creating a second key.
 
 ### Destructive commands
 
-`api-key revoke`, `bucket delete`, `database delete` and `machine delete` ask before they act when stdin and stderr are a terminal: a revocation is confirmed by typing `yes`, a deletion by typing the bucket's, database's or Machine's name, as in the console. Without a terminal they refuse unless `--yes` is given.
+`api-key revoke`, `bucket delete`, `database delete`, `stream delete` and `machine delete` ask before they act when stdin and stderr are a terminal: a revocation is confirmed by typing `yes`, a deletion by typing the bucket's, database's, stream's or Machine's name, as in the console. Without a terminal they refuse unless `--yes` is given.
 
 ## Account
 
@@ -103,7 +109,7 @@ tonbo api-key create ci-reader --member pi-live --read-only --bucket events --ex
 tonbo api-key revoke 70000000-0000-4000-8000-000000000007
 ```
 
-`api-key list` shows your keys, or every key of the account for an owner or admin, with the last four characters of each secret. `api-key create` 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 `--database` and `--database-prefix` (repeat each for several), narrow the key for its whole life; `--expires-in` is one of `15_days`, `1_month`, `6_months`, `1_year` or `never` (the default). The secret is printed once, in that 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 on stdout, beside the secret, for your application's environment (a `.env` file or a secret store), and stderr notes that `TONBO_API_KEY` in your own shell overrides your `tonbo login`, for this CLI too. stderr never carries the secret, and `--json` prints only the answer. `api-key show` prints one key, and `api-key revoke` revokes it and every token minted from it.
+`api-key list` shows your keys, or every key of the account for an owner or admin, with the last four characters of each secret. `api-key create` 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 of each; `--expires-in` is one of `15_days`, `1_month`, `6_months`, `1_year` or `never` (the default). The secret is printed once, in that 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 on stdout, beside the secret, for your application's environment (a `.env` file or a secret store), and stderr notes that `TONBO_API_KEY` in your own shell overrides your `tonbo login`, for this CLI too. stderr never carries the secret, and `--json` prints only the answer. `api-key show` prints one key, and `api-key revoke` revokes it and every token minted from it.
 
 ## Buckets
 
@@ -119,32 +125,46 @@ tonbo bucket delete events
 
 ```console
 tonbo database create notes
+tonbo database create scratch --expires-in 24h
 tonbo database show notes
 ```
 
-`database create` creates a database in `--region`, or in the default region, and prints its fields with its URL. Without `--json` it then writes the next step to stderr, opening the database by name from code:
+`database create` creates a database in `--region`, or in the default region, and prints its fields with its URL. `--expires-at` and `--expires-in` give it an expiry fixed for its life, by the same rules as `stream create`'s: once it passes, Tonbo deletes the database within a minute, as `database delete` would, and its name is free again; `database show` prints it, and without either the database never expires. A Machine's database never expires. Without `--json` it then writes the next step to stderr, opening the database by name from code:
 
 ```text
-Next: npm i @tonbo/sqlite-ursula
+Next: npm i @tonbo/sqlite-ursula@0.11.2
       open("notes") from "@tonbo/sqlite-ursula/tonbo"
 ```
 
 `open("notes")` resolves the database through `GET /v1/databases/notes`. It takes its key from, in order, its `apiKey` option, then `TONBO_API_KEY`, then the `tonbo login` credentials file (`key_sources` in `contracts/cli/credentials-v1.json`). A key narrowed to databases reads the databases it reaches there, so an application can be given a narrowed key.
 
+## Streams
+
+```console
+tonbo stream create events --content-type application/json
+tonbo stream create run-42 --content-type application/json --expires-in 24h
+tonbo stream show events
+tonbo api-key create run-reader --read-only --stream-prefix run-
+```
+
+`stream create` creates a raw durable stream in `--region`, or in the default region, with the content type every append must send (`--content-type`, `application/octet-stream` by default; one lowercase `type/subtype` without parameters), and prints its fields with its URL on the region's Streams origin. A stream and a database may share a name; each kind has its own names, limit and usage (`stream usage`, whose `other` holds the account's databases and everything else, as `database usage`'s holds its streams). 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. `--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 stream an expiry fixed for its life: once it passes, Tonbo deletes the stream within a minute, as `stream delete` would, and its name is free again; `stream show` prints it, and without either the stream never expires. `--expires-in` is counted from when the command runs, so it never goes with `--idempotency-key`: an unconfirmed creation with an expiry prints a retry hint naming its key and the absolute time it sent, and the retry passes that time with `--expires-at` (the same for `database create`). A key narrowed to streams (`api-key create --stream` or `--stream-prefix`) reaches only those streams; a key narrowed to buckets, or by name to databases alone, reaches no stream.
+
 ## Machines
 
 ```console
 tonbo machine shapes
-tonbo machine create web --image ghcr.io/acme/web:1.4 --port 8080:public --env MODE=prod
-tonbo machine create worker --image python:3.13 -- python -m worker
+tonbo machine create web --image tonbo.dev/platform --port 8080:public --env MODE=prod
+tonbo machine create worker --image tonbo.dev/platform -- sh -c 'while true; do date; sleep 60; done'
 tonbo machine update web --env MODE=staging --sleep-after 300
 tonbo machine sleep web
 tonbo machine delete web
 ```
 
-A Machine is a VM booted from a public OCI image with a linux/arm64 variant, in one region, with its own database (`contracts/machines/machine-v2.json`). Machines open by invitation: until a region is open for them, every `tonbo machine` command is refused with `region_unavailable`, and the CLI says that nothing was created or changed.
+A Machine is a VM booted from an image, in one region, with its own database (`contracts/machines/machine-v2.json`). Machines open by invitation: until a region is open for them, every `tonbo machine` command is refused with `region_unavailable`, and the CLI says that nothing was created or changed.
+
+The image is `tonbo.dev/platform`, the platform image each node release ships, or, once registry images are offered, a public OCI image with a linux/arm64 variant. Until then any other reference is refused with `image_not_offered`, before anything is created or changed; `machine show` prints the platform image as `tonbo.dev/platform (platform image)`.
 
-`machine create` resolves the image to its linux/arm64 digest and reserves the Machine's name and its hostnames: `https://<name>-<account>.<region>.tonbo.sh` for the default port, and `<name>.<account>@<region>.tonbo.sh` for SSH. Without `--shape` it takes the shape `machine shapes` marks as the default. `--port <port>` serves a private port (a member's token or SSH) and `--port <port>:public` an open one, which needs the `machines.public` capability; the first port is served at the hostname unless `--default-port` names another. A command after `--` replaces the image's CMD. The answer is the Machine while it is `creating`; `machine show` reports it `active` when it is ready.
+`machine create` resolves a registry image to its linux/arm64 digest (the platform image resolves to none) and reserves the Machine's name and its hostnames: `https://<name>-<account>.<region>.tonbo.sh` for the default port, and `<name>.<account>@<region>.tonbo.sh` for SSH. Without `--shape` it takes the shape `machine shapes` marks as the default. `--port <port>` serves a private port (a member's token or SSH) and `--port <port>:public` an open one, which needs the `machines.public` capability; the first port is served at the hostname unless `--default-port` names another. A command after `--` replaces the image's CMD. The answer is the Machine while it is `creating`; `machine show` reports it `active` when it is ready.
 
 `machine update` changes only what its options name. It reads the Machine and writes the change at the revision it read, or at `--revision`, so a change someone made in between is refused with `revision_mismatch` rather than overwritten. `--env` and `--unset-env` change single variables; `--port` replaces every port, naming a public port again keeps its limits, and the current default port stays the default while it is still listed unless `--default-port` names another. Ports and `--sleep-after` apply at once; image, command, shape and env at the Machine's next boot. `machine sleep` puts an awake Machine to sleep now; its next connection wakes it. `machine delete` deletes the Machine with its disk, database and logs, and its name is free for a new Machine at once.
 

package/dist/bin/tonbo.js

@@ -617,6 +617,71 @@ var managementOperations = {
     "query": [],
     "idempotencyKey": false,
     "cli": "tonbo machine shapes"
+  },
+  "listStreams": {
+    "method": "GET",
+    "path": "/streams",
+    "pathParams": [],
+    "query": [
+      "prefix",
+      "cursor",
+      "limit"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo stream list"
+  },
+  "createStream": {
+    "method": "POST",
+    "path": "/streams",
+    "pathParams": [],
+    "query": [],
+    "idempotencyKey": true,
+    "cli": "tonbo stream create"
+  },
+  "getStream": {
+    "method": "GET",
+    "path": "/streams/{name}",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo stream show"
+  },
+  "updateStream": {
+    "method": "PATCH",
+    "path": "/streams/{name}",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo stream update"
+  },
+  "deleteStream": {
+    "method": "DELETE",
+    "path": "/streams/{name}",
+    "pathParams": [
+      "name"
+    ],
+    "query": [],
+    "idempotencyKey": false,
+    "cli": "tonbo stream delete"
+  },
+  "listStreamUsage": {
+    "method": "GET",
+    "path": "/usage/streams",
+    "pathParams": [],
+    "query": [
+      "period",
+      "sort",
+      "prefix",
+      "names",
+      "cursor",
+      "limit"
+    ],
+    "idempotencyKey": false,
+    "cli": "tonbo stream usage"
   }
 };
 var accountRoles = [
@@ -1201,7 +1266,7 @@ var ManagementApi = class {
     return this.call("createDatabase", key, {
       body: withoutUndefined(request),
       idempotencyKey
-    }).catch(unconfirmed("Database creation", idempotencyKey, "the same name and region"));
+    }).catch(unconfirmed("Database creation", idempotencyKey, request.expires_at ? `the same name, region and --expires-at ${request.expires_at}` : "the same name and region"));
   }
   getDatabase(key, name) {
     return this.call("getDatabase", key, { params: { name } });
@@ -1216,6 +1281,30 @@ var ManagementApi = class {
   listDatabaseUsage(key, page, query = {}) {
     return this.page("listDatabaseUsage", key, page, query);
   }
+  listStreams(key, page, prefix) {
+    return this.page("listStreams", key, page, { prefix });
+  }
+  /** A replay with the same idempotency key returns the stream the first
+   * request created. */
+  createStream(key, request, idempotencyKey) {
+    return this.call("createStream", key, {
+      body: withoutUndefined(request),
+      idempotencyKey
+    }).catch(unconfirmed("Stream creation", idempotencyKey, request.expires_at ? `the same name, region, content type and --expires-at ${request.expires_at}` : "the same name, region and content type"));
+  }
+  getStream(key, name) {
+    return this.call("getStream", key, { params: { name } });
+  }
+  updateStream(key, name, change) {
+    return this.call("updateStream", key, { params: { name }, body: change });
+  }
+  deleteStream(key, name) {
+    return this.call("deleteStream", key, { params: { name } });
+  }
+  /** The whole usage page: its rows, `other`, prices and checkpoint. */
+  listStreamUsage(key, page, query = {}) {
+    return this.page("listStreamUsage", key, page, query);
+  }
   getUsage(key, period) {
     return this.call("getUsage", key, { query: { period } });
   }
@@ -1611,19 +1700,23 @@ async function memberUpdateCommand(deps, member, options = {}) {
 function keyAccess(apiKey) {
   return apiKey.read_only ? "read-only" : "read-write";
 }
-function narrowedByDatabase(apiKey) {
-  return apiKey.databases.length + apiKey.database_prefixes.length > 0;
+function narrowedByName(apiKey) {
+  return apiKey.databases.length + apiKey.database_prefixes.length + apiKey.streams.length + apiKey.stream_prefixes.length > 0;
 }
 function keyBuckets(apiKey) {
   if (apiKey.buckets.length) return apiKey.buckets.join(", ");
-  return narrowedByDatabase(apiKey) ? "none" : "all";
+  return narrowedByName(apiKey) ? "none" : "all";
+}
+function keyNames(apiKey, names, prefixes) {
+  if (names.length + prefixes.length > 0)
+    return [...names, ...prefixes.map((prefix) => `${prefix}*`)].join(", ");
+  return apiKey.buckets.length || narrowedByName(apiKey) ? "none" : "all";
 }
 function keyDatabases(apiKey) {
-  if (narrowedByDatabase(apiKey))
-    return [...apiKey.databases, ...apiKey.database_prefixes.map((prefix) => `${prefix}*`)].join(
-      ", "
-    );
-  return apiKey.buckets.length ? "none" : "all";
+  return keyNames(apiKey, apiKey.databases, apiKey.database_prefixes);
+}
+function keyStreams(apiKey) {
+  return keyNames(apiKey, apiKey.streams, apiKey.stream_prefixes);
 }
 function apiKeyFields(apiKey) {
   return fields([
@@ -1634,6 +1727,7 @@ function apiKeyFields(apiKey) {
     ["Access", keyAccess(apiKey)],
     ["Buckets", keyBuckets(apiKey)],
     ["Databases", keyDatabases(apiKey)],
+    ["Streams", keyStreams(apiKey)],
     ["Expires", when(apiKey.expires_at)],
     ["Last used", when(apiKey.last_used_at)],
     ["Created", apiKey.created_at]
@@ -1657,6 +1751,7 @@ async function apiKeyListCommand(deps, options = {}) {
         "ACCESS",
         "BUCKETS",
         "DATABASES",
+        "STREAMS",
         "EXPIRES",
         "LAST USED"
       ],
@@ -1668,6 +1763,7 @@ async function apiKeyListCommand(deps, options = {}) {
         keyAccess(apiKey),
         keyBuckets(apiKey),
         keyDatabases(apiKey),
+        keyStreams(apiKey),
         when(apiKey.expires_at),
         when(apiKey.last_used_at)
       ])
@@ -1684,6 +1780,8 @@ async function apiKeyCreateCommand(deps, name, options = {}) {
     buckets: options.bucket,
     databases: options.database,
     database_prefixes: options.databasePrefix,
+    streams: options.stream,
+    stream_prefixes: options.streamPrefix,
     expires_in: options.expiresIn
   });
   print(
@@ -1811,11 +1909,11 @@ async function bucketDeleteCommand(deps, name, options = {}) {
     `Bucket ${bucket.name} is ${bucket.state}; its streams are being purged.`
   );
 }
-function databaseAccess(database) {
-  return database.public_read ? "public" : "private";
+function readAccess(resource) {
+  return resource.public_read ? "public" : "private";
 }
-function databaseSize(database) {
-  const { log, snapshot } = database.stored_bytes;
+function storedSize(resource) {
+  const { log, snapshot } = resource.stored_bytes;
   if (log === null && snapshot === null) return "unknown";
   return `${bytes(log)} log, ${bytes(snapshot, "no")} snapshot`;
 }
@@ -1828,11 +1926,12 @@ function databaseFields(database) {
     ["Kind", databaseOwner(database)],
     ["Region", database.region],
     ["State", database.state],
-    ["Read access", databaseAccess(database)],
+    ["Read access", readAccess(database)],
     ["URL", database.url],
+    ["Expires", database.expires_at ?? "never"],
     ["Incarnation", database.incarnation ?? "none yet"],
     ["Last write", when(database.last_write_at)],
-    ["Stored", databaseSize(database)],
+    ["Stored", storedSize(database)],
     ["Created", `${database.created_at} by ${database.created_by}`]
   ]);
 }
@@ -1859,19 +1958,44 @@ async function databaseListCommand(deps, options = {}) {
         databaseOwner(database),
         database.region,
         database.state,
-        databaseAccess(database),
+        readAccess(database),
         when(database.last_write_at),
-        databaseSize(database),
+        storedSize(database),
         database.url
       ])
     ) : "No databases."
   );
   noticeUnavailable(deps, page.unavailable_regions, "sizes");
 }
+var EXPIRY_UNITS = { s: 1, m: 60, h: 3600, d: 86400 };
+var EXPIRES_IN_MIN_SECONDS = 90;
+function expiresInSeconds(value) {
+  const match = /^([1-9][0-9]{0,8})([smhd])$/.exec(value.trim());
+  if (!match)
+    throw new Error(
+      "Give a whole number of seconds, minutes, hours or days, such as 90s, 30m, 24h or 7d."
+    );
+  const seconds = Number(match[1]) * EXPIRY_UNITS[match[2]];
+  if (seconds < EXPIRES_IN_MIN_SECONDS)
+    throw new Error(
+      `An expiry is at least ${EXPIRES_IN_MIN_SECONDS}s after this command creates it; give 90s or more.`
+    );
+  return seconds;
+}
+function creationExpiry(noun, options, now = Date.now()) {
+  if (options.expiresIn !== void 0 && options.idempotencyKey !== void 0)
+    throw new Error(
+      `--expires-in counts from now, so a retry would name another expiry; retry an unconfirmed ${noun} creation with --idempotency-key and the --expires-at time its message printed.`
+    );
+  if (options.expiresAt !== void 0) return options.expiresAt;
+  if (options.expiresIn === void 0) return void 0;
+  return new Date(now + options.expiresIn * 1e3).toISOString();
+}
 async function databaseCreateCommand(deps, name, options = {}) {
+  const expiresAt = creationExpiry("database", options);
   const database = await deps.api.createDatabase(
     await deps.auth.apiKey(),
-    { name, region: options.region },
+    { name, region: options.region, expires_at: expiresAt },
     options.idempotencyKey ?? randomUUID2()
   );
   print(
@@ -1887,7 +2011,7 @@ async function databaseCreateCommand(deps, name, options = {}) {
 }
 function databaseNextStep(name) {
   return [
-    "Next: npm i @tonbo/sqlite-ursula",
+    "Next: npm i @tonbo/sqlite-ursula@0.11.2",
     `      open(${JSON.stringify(name)}) from "@tonbo/sqlite-ursula/tonbo"`
   ].join("\n");
 }
@@ -1926,22 +2050,17 @@ async function databaseDeleteCommand(deps, name, options = {}) {
     database.state === "deleted" ? `Deleted database ${database.name}; its name is free again.` : `Database ${database.name} is ${database.state}; its name is free again once it is deleted.`
   );
 }
-function databaseUsageSort(value) {
+function usageSort(value) {
   if (value === "-list_value" || value === "list_value") return "-list_value";
   if (value === "name") return "name";
   throw new Error("--sort is list_value or name.");
 }
-async function databaseUsageCommand(deps, options = {}) {
-  const usage = await deps.api.listDatabaseUsage(
-    await deps.auth.apiKey(),
-    { limit: options.limit, cursor: options.cursor },
-    { period: options.period, sort: options.sort, prefix: options.prefix, names: options.names }
-  );
-  if (options.json) deps.output(JSON.stringify(usage));
+function printResourceUsage(deps, json, usage, noun) {
+  if (json) deps.output(JSON.stringify(usage));
   else
     deps.output(
       [
-        `Database usage in ${usage.period} at list price, before the monthly allowance and credit (${usage.currency.toUpperCase()}; metered up to ${when(usage.as_of, "not yet metered")})`,
+        `${noun === "database" ? "Database" : "Stream"} usage in ${usage.period} at list price, before the monthly allowance and credit (${usage.currency.toUpperCase()}; metered up to ${when(usage.as_of, "not yet metered")})`,
         usage.data.length ? table(
           [
             "NAME",
@@ -1961,7 +2080,7 @@ async function databaseUsageCommand(deps, options = {}) {
             row.snapshot_gib_months ?? "",
             usd(row.list_value_micros)
           ])
-        ) : "No database usage.",
+        ) : `No ${noun} usage.`,
         `Other metered usage: ${usd(usage.other.list_value_micros)}`,
         "Charges, after the allowance and credit, are in `tonbo usage show`."
       ].join("\n")
@@ -1969,6 +2088,127 @@ async function databaseUsageCommand(deps, options = {}) {
   if (usage.next_cursor) deps.notice(`More results: run again with --cursor ${usage.next_cursor}`);
   noticeUnavailable(deps, usage.unavailable_regions, "usage");
 }
+async function databaseUsageCommand(deps, options = {}) {
+  const usage = await deps.api.listDatabaseUsage(
+    await deps.auth.apiKey(),
+    { limit: options.limit, cursor: options.cursor },
+    { period: options.period, sort: options.sort, prefix: options.prefix, names: options.names }
+  );
+  printResourceUsage(deps, options.json, usage, "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)],
+    ["URL", stream.url],
+    ["Incarnation", stream.incarnation ?? "none yet"],
+    ["Last write", when(stream.last_write_at)],
+    ["Stored", storedSize(stream)],
+    ["Created", `${stream.created_at} by ${stream.created_by}`]
+  ]);
+}
+async function streamListCommand(deps, options = {}) {
+  const page = await deps.api.listStreams(
+    await deps.auth.apiKey(),
+    { limit: options.limit, cursor: options.cursor },
+    options.prefix
+  );
+  printPage(
+    deps,
+    options.json,
+    page,
+    (streams) => streams.length ? table(
+      ["NAME", "REGION", "STATE", "CONTENT TYPE", "READ ACCESS", "LAST WRITE", "STORED", "URL"],
+      streams.map((stream) => [
+        stream.name,
+        stream.region,
+        stream.state,
+        stream.content_type,
+        readAccess(stream),
+        when(stream.last_write_at),
+        storedSize(stream),
+        stream.url
+      ])
+    ) : "No streams."
+  );
+  noticeUnavailable(deps, page.unavailable_regions, "sizes");
+}
+async function streamCreateCommand(deps, name, options = {}) {
+  const expiresAt = creationExpiry("stream", options);
+  const stream = await deps.api.createStream(
+    await deps.auth.apiKey(),
+    {
+      name,
+      region: options.region,
+      content_type: options.contentType,
+      expires_at: expiresAt
+    },
+    options.idempotencyKey ?? randomUUID2()
+  );
+  print(
+    deps,
+    options.json,
+    stream,
+    [
+      stream.state === "active" ? `Created stream ${stream.name}.` : `Stream ${stream.name} is being created; \`tonbo stream show ${stream.name}\` reports it active when it is ready.`,
+      streamFields(stream)
+    ].join("\n")
+  );
+  if (!options.json)
+    deps.notice(
+      [
+        `Next: append with POST ${stream.url} and Content-Type: ${stream.content_type}`,
+        `      read from the start with GET ${stream.url}?offset=-1`
+      ].join("\n")
+    );
+}
+async function streamShowCommand(deps, name, options = {}) {
+  const stream = await deps.api.getStream(await deps.auth.apiKey(), name);
+  print(deps, options.json, stream, streamFields(stream));
+}
+async function streamUpdateCommand(deps, name, options = {}) {
+  if (options.public === options.private)
+    throw new Error("Pass exactly one of --public and --private.");
+  const stream = await deps.api.updateStream(await deps.auth.apiKey(), name, {
+    public_read: options.public === true
+  });
+  print(
+    deps,
+    options.json,
+    stream,
+    stream.public_read ? `Stream ${stream.name} is public: anyone can read it at ${stream.url}.` : `Stream ${stream.name} is private: only the account's keys can read it.`
+  );
+}
+async function streamDeleteCommand(deps, name, options = {}) {
+  await confirm(
+    deps,
+    options.yes,
+    `delete stream ${name}`,
+    () => Promise.resolve(
+      `Delete stream ${name} and everything in it? This cannot be undone. Type the stream's name to confirm:`
+    ),
+    name
+  );
+  const stream = await deps.api.deleteStream(await deps.auth.apiKey(), name);
+  print(
+    deps,
+    options.json,
+    stream,
+    stream.state === "deleted" ? `Deleted stream ${stream.name}; its name is free again.` : `Stream ${stream.name} is ${stream.state}; its name is free again once it is deleted.`
+  );
+}
+async function streamUsageCommand(deps, options = {}) {
+  const usage = await deps.api.listStreamUsage(
+    await deps.auth.apiKey(),
+    { limit: options.limit, cursor: options.cursor },
+    { period: options.period, sort: options.sort, prefix: options.prefix, names: options.names }
+  );
+  printResourceUsage(deps, options.json, usage, "stream");
+}
 async function usageShowCommand(deps, options = {}) {
   const usage = await deps.api.getUsage(await deps.auth.apiKey(), options.period);
   print(
@@ -2002,6 +2242,7 @@ 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_unavailable: "`tonbo machine shapes` lists the shapes a Machine may name now.",
   port_reserved: "Serve the application on another port.",
   revision_mismatch: "The Machine changed since it was read; `tonbo machine show` it and run the update again.",
@@ -2038,6 +2279,10 @@ function idleActionText(machine) {
 function machineState(machine) {
   return machine.failure ? `${machine.state}: ${machine.failure.code}: ${machine.failure.message}` : machine.state;
 }
+function imageText(machine) {
+  const { reference, digest } = machine.image;
+  return `${reference} (${digest ?? "platform image"})`;
+}
 function machineFields(machine) {
   return fields([
     ["Name", machine.name],
@@ -2046,7 +2291,7 @@ function machineFields(machine) {
     ["State", machineState(machine)],
     ["Power", machine.status.power],
     ["Shape", machine.shape],
-    ["Image", `${machine.image.reference} (${machine.image.digest})`],
+    ["Image", imageText(machine)],
     ["Command", machine.command ? machine.command.join(" ") : "the image's own"],
     ["Ports", machinePortsText(machine)],
     ["HTTPS", machine.hostnames.https],
@@ -2128,6 +2373,11 @@ async function machineListCommand(deps, options = {}) {
       );
   });
 }
+function createdText(machine) {
+  if (machine.state === "creating")
+    return `Machine ${machine.name} is being created; \`tonbo machine show ${machine.name}\` reports it active when it is ready.`;
+  return `Created Machine ${machine.name}.`;
+}
 async function machineCreateCommand(deps, name, command, options = {}) {
   await machineCommand(async () => {
     if (!options.image) throw new Error("Pass --image <reference>.");
@@ -2151,15 +2401,13 @@ async function machineCreateCommand(deps, name, command, options = {}) {
       },
       options.idempotencyKey ?? randomUUID3()
     );
-    print(
-      deps,
-      options.json,
-      machine,
-      [
-        machine.state === "active" ? `Created Machine ${machine.name}.` : `Machine ${machine.name} is being created; \`tonbo machine show ${machine.name}\` reports it active when it is ready.`,
-        machineFields(machine)
-      ].join("\n")
-    );
+    if (machine.state === "failed") {
+      print(deps, options.json, machine, machineFields(machine));
+      throw new Error(
+        `Machine ${machine.name} failed to be created; delete it with \`tonbo machine delete ${machine.name}\` and create it again.`
+      );
+    }
+    print(deps, options.json, machine, [createdText(machine), machineFields(machine)].join("\n"));
   });
 }
 async function machineShowCommand(deps, name, options = {}) {
@@ -2360,6 +2608,20 @@ function machineSpecOptions(command, update) {
     parseWhole
   );
 }
+function parseExpiresIn(value) {
+  try {
+    return expiresInSeconds(value);
+  } catch (error) {
+    throw new InvalidArgumentError(error.message);
+  }
+}
+function parseUsageSort(value) {
+  try {
+    return usageSort(value);
+  } catch (error) {
+    throw new InvalidArgumentError(error.message);
+  }
+}
 function createProgram(dependencies = createDependencies) {
   const program = new Command().name("tonbo").description("Sign in to Tonbo and manage account resources.").version(packageVersion.version);
   program.command("login").description("sign in through the browser and save a personal key for this computer").option("--account <name>", "the account to log in to; defaults to your personal account").action(async (options) => loginCommand(dependencies(), options));
@@ -2423,6 +2685,14 @@ function createProgram(dependencies = createDependencies) {
       "--database-prefix <prefix>",
       "narrow the key to the databases whose name starts with this, for its whole life; repeat for several; never with --bucket",
       repeated
+    ).option(
+      "--stream <name>",
+      "narrow the key to this raw stream, for its whole life; repeat for several; never with --bucket",
+      repeated
+    ).option(
+      "--stream-prefix <prefix>",
+      "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
@@ -2483,16 +2753,26 @@ function createProgram(dependencies = createDependencies) {
     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(
+      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"
+      ).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"
+      ).argParser(parseExpiresIn).conflicts("expiresAt")
     ).option(
       "--idempotency-key <key>",
-      "reuse the key of an unconfirmed creation to get the database it created"
+      "reuse the key of an unconfirmed creation to get the database it created; with --expires-at, never --expires-in"
     ),
     "createDatabase"
   ).action(
     async (name, options) => databaseCreateCommand(dependencies(), name, options)
   );
   operationOptions(
-    database.command("show <name>").description("show a database, its URL and size"),
+    database.command("show <name>").description("show a database, its URL, expiry and size"),
     "getDatabase"
   ).action(
     async (name, options) => databaseShowCommand(dependencies(), name, options)
@@ -2513,21 +2793,70 @@ function createProgram(dependencies = createDependencies) {
     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",
-      (value) => {
-        try {
-          return databaseUsageSort(value);
-        } catch (error) {
-          throw new InvalidArgumentError(error.message);
-        }
-      }
-    ).option("--prefix <prefix>", "only databases whose name starts with this").option("--names <names>", "only these databases, up to 100 names, comma-separated"),
+    ).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"),
     "listDatabaseUsage"
   ).action(
     async (options) => databaseUsageCommand(dependencies(), options)
   );
+  const stream = program.command("stream").description("the account's raw durable streams");
+  operationOptions(
+    stream.command("list").description("list the streams in every region").option("--prefix <prefix>", "only streams whose name starts with this"),
+    "listStreams"
+  ).action(
+    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(
+      "--content-type <type>",
+      "the media type every append sends, such as application/json; application/octet-stream by default"
+    ).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"
+      ).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"
+      ).argParser(parseExpiresIn).conflicts("expiresAt")
+    ).option(
+      "--idempotency-key <key>",
+      "reuse the key of an unconfirmed creation to get the stream it created; with --expires-at, never --expires-in"
+    ),
+    "createStream"
+  ).action(
+    async (name, options) => streamCreateCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    stream.command("show <name>").description("show a stream, its URL, content type, expiry and size"),
+    "getStream"
+  ).action(
+    async (name, options) => streamShowCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    stream.command("update <name>").description("publish a stream for anonymous reads, or take it private (owners and admins)").addOption(new Option("--public", "serve anonymous reads").conflicts("private")).addOption(new Option("--private", "serve only the account's keys").conflicts("public")),
+    "updateStream"
+  ).action(
+    async (name, options) => streamUpdateCommand(dependencies(), name, options)
+  );
+  operationOptions(
+    stream.command("delete <name>").description("delete a stream and everything in it").option("--yes", "delete without asking; required when stdin is not a terminal"),
+    "deleteStream"
+  ).action(
+    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"),
+    "listStreamUsage"
+  ).action(
+    async (options) => streamUsageCommand(dependencies(), options)
+  );
   const machine = program.command("machine").description("the account's Machines");
   operationOptions(
     machine.command("list").description("list the Machines in every region"),
@@ -2538,8 +2867,11 @@ function createProgram(dependencies = createDependencies) {
   operationOptions(
     machineSpecOptions(
       machine.command("create <name> [command...]").description(
-        "create a Machine from a public linux/arm64 image; [command...] after -- replaces the image's CMD"
-      ).requiredOption("--image <reference>", "the public OCI image the Machine boots").option(
+        "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"
       ),
@@ -2562,7 +2894,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; 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(
+      ).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(
         "--revision <revision>",
         "write only if the Machine is still at this revision (tonbo machine show); the revision it reads by default",
         parseWhole

package/package.json

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