CLI reference
Last updated 2 November 2026
Every command of the tonbo CLI with its arguments and flags, rendered from the definitions its --help prints, for when you script it or look up a flag.
Install it with npm i -g @tonbo/cli and sign in with tonbo login. Every command but login and logout calls one operation of the Management API, with the role you have in the account you logged in to, or with the key in TONBO_API_KEY, which overrides the saved login (see API keys and tokens). A list prints one page; when there are more, it names on stderr the --cursor to run it again with. The page leaves out the commands of resources these docs do not describe; tonbo --help lists every command.
tonbo logintonbo logouttonbo accounttonbo regiontonbo membertonbo agenttonbo api-keytonbo databasetonbo streamtonbo machinetonbo usage
Global flags
-h, --help after any command prints its help.
| Flag | Description |
|---|---|
-V, --version | Output the version number. |
tonbo login
tonbo login [options]Sign in through the browser and save a personal key for this computer.
| Flag | Description |
|---|---|
--account <name> | The account to log in to; defaults to your personal account. |
tonbo logout
tonbo logoutRevoke this computer's key and remove the saved login.
tonbo account
The account you are logged in to.
tonbo account show
tonbo account show [options]Show the account, your role in it and its limits.
| Flag | Description |
|---|---|
--json | Print the API data as JSON. |
tonbo region
Regions new resources can be created in.
tonbo region list
tonbo region list [options]List the regions.
| Flag | Description |
|---|---|
--json | Print the API data as JSON. |
tonbo member
The people and Agents of the account.
tonbo member list
tonbo member list [options]List the members and their roles.
| Flag | Description |
|---|---|
--limit <count> | The most items to return. |
--cursor <cursor> | Continue from the cursor a previous page printed. |
--json | Print the API data as JSON. |
tonbo member update
tonbo member update <member> [options]Change a member's role, or rename an Agent; <member> is a subject, or an Agent's id or name.
| Flag | Description |
|---|---|
--role <role> | The member's new role; only an owner grants owner. One of owner, admin, member. |
--name <name> | The Agent's new name. |
--json | Print the API data as JSON. |
tonbo agent
Manage the Agents of your account.
tonbo agent create
tonbo agent create <name> [options]Create an agent.
| Flag | Description |
|---|---|
--role <role> | The Agent's role; member by default. One of owner, admin, member. |
--region <region> | Permanent home region (see tonbo region list); required once several regions accept new agents. |
--idempotency-key <key> | Reuse the key of an unconfirmed creation to get the Agent it created. |
--json | Print the API data as JSON. |
tonbo api-key
The keys of the account's members.
tonbo api-key list
tonbo api-key list [options]List your keys, or every key of the account for an owner or admin.
| Flag | Description |
|---|---|
--limit <count> | The most items to return. |
--cursor <cursor> | Continue from the cursor a previous page printed. |
--json | Print the API data as JSON. |
tonbo api-key create
tonbo api-key create <name> [options]Create a key and print its secret, once.
| Flag | Description |
|---|---|
--member <member> | An Agent (subject, id or name) to create the key for; yourself by default. |
--read-only | Narrow the key to read-only actions, for its whole life. |
--bucket <name> | Narrow the key to this bucket, for its whole life; repeat for several. |
--database <name> | Narrow the key to this database, for its whole life; repeat for several; never with --bucket. |
--database-prefix <prefix> | Narrow the key to the databases whose name starts with this, for its whole life; repeat for several; never with --bucket. |
--stream <name> | Narrow the key to this raw stream, for its whole life; repeat for several; never with --bucket. |
--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. |
--expires-in <period> | When the key expires; never by default. One of 15_days, 1_month, 6_months, 1_year, never. |
--json | Print the API data as JSON. |
tonbo api-key show
tonbo api-key show <key-id> [options]Show one key.
| Flag | Description |
|---|---|
--json | Print the API data as JSON. |
tonbo api-key revoke
tonbo api-key revoke <key-id> [options]Revoke a key and every token minted from it.
| Flag | Description |
|---|---|
--yes | Revoke without asking; required when stdin is not a terminal. |
--json | Print the API data as JSON. |
tonbo database
The account's databases.
tonbo database list
tonbo database list [options]List the databases in every region.
| Flag | Description |
|---|---|
--prefix <prefix> | Only databases whose name starts with this. |
--limit <count> | The most items to return. |
--cursor <cursor> | Continue from the cursor a previous page printed. |
--json | Print the API data as JSON. |
tonbo database create
tonbo database create <name> [options]Create a database; its region is fixed for its life.
| Flag | Description |
|---|---|
--region <region> | The database's region (see tonbo region list); the database default region by default. |
--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. |
--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. |
--idempotency-key <key> | Reuse the key of an unconfirmed creation to get the database it created; with --expires-at, never --expires-in. |
--json | Print the API data as JSON. |
tonbo database show
tonbo database show <name> [options]Show a database, its URL, expiry and size.
| Flag | Description |
|---|---|
--json | Print the API data as JSON. |
tonbo database update
tonbo database update <name> [options]Publish a database for anonymous reads, or take it private (owners and admins).
| Flag | Description |
|---|---|
--public | Serve anonymous reads. |
--private | Serve only the account's keys. |
--json | Print the API data as JSON. |
tonbo database delete
tonbo database delete <name> [options]Delete a database and everything in it.
| Flag | Description |
|---|---|
--yes | Delete without asking; required when stdin is not a terminal. |
--json | Print the API data as JSON. |
tonbo database usage
tonbo database usage [options]Each database's usage of one month at list price, before allowance and credit.
| Flag | Description |
|---|---|
--period <month> | The calendar month in UTC, as YYYY-MM; the current one by default. |
--sort <order> | List_value (highest first, the default) or name. |
--prefix <prefix> | Only databases whose name starts with this. |
--names <names> | Only these databases, up to 100 names, comma-separated. |
--limit <count> | The most items to return. |
--cursor <cursor> | Continue from the cursor a previous page printed. |
--json | Print the API data as JSON. |
tonbo stream
The account's raw durable streams.
tonbo stream list
tonbo stream list [options]List the streams in every region.
| Flag | Description |
|---|---|
--prefix <prefix> | Only streams whose name starts with this. |
--limit <count> | The most items to return. |
--cursor <cursor> | Continue from the cursor a previous page printed. |
--json | Print the API data as JSON. |
tonbo stream create
tonbo stream create <name> [options]Create a stream; its region and content type are fixed for its life.
| Flag | Description |
|---|---|
--region <region> | The stream's region (see tonbo region list); the database default region by default. |
--content-type <type> | The media type every append sends, such as application/json; application/octet-stream by default. |
--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. |
--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. |
--idempotency-key <key> | Reuse the key of an unconfirmed creation to get the stream it created; with --expires-at, never --expires-in. |
--json | Print the API data as JSON. |
tonbo stream show
tonbo stream show <name> [options]Show a stream, its URL, content type, expiry and size.
| Flag | Description |
|---|---|
--json | Print the API data as JSON. |
tonbo stream update
tonbo stream update <name> [options]Publish a stream for anonymous reads, or take it private (owners and admins).
| Flag | Description |
|---|---|
--public | Serve anonymous reads. |
--private | Serve only the account's keys. |
--json | Print the API data as JSON. |
tonbo stream delete
tonbo stream delete <name> [options]Delete a stream and everything in it.
| Flag | Description |
|---|---|
--yes | Delete without asking; required when stdin is not a terminal. |
--json | Print the API data as JSON. |
tonbo stream usage
tonbo stream usage [options]Each stream's usage of one month at list price, before allowance and credit.
| Flag | Description |
|---|---|
--period <month> | The calendar month in UTC, as YYYY-MM; the current one by default. |
--sort <order> | List_value (highest first, the default) or name. |
--prefix <prefix> | Only streams whose name starts with this. |
--names <names> | Only these streams, up to 100 names, comma-separated. |
--limit <count> | The most items to return. |
--cursor <cursor> | Continue from the cursor a previous page printed. |
--json | Print the API data as JSON. |
tonbo machine Not open yet
Machines are not open yet. These pages describe Machines as they will open; until then, a create answers region_not_offered (422), “Machines are not offered in any region yet.”
The account's Machines.
tonbo machine list
tonbo machine list [options]List the Machines in every region, and your computers in a personal account.
| Flag | Description |
|---|---|
--limit <count> | The most items to return. |
--cursor <cursor> | Continue from the cursor a previous page printed. |
--json | Print the API data as JSON. |
tonbo machine create
tonbo machine create --image <reference> <name> [command...] [options]Create a Machine from an image; [command...] after -- replaces the image's CMD.
| Flag | Description |
|---|---|
--image <reference> | Required. 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. |
--region <region> | The Machine's region, fixed for its life; the --volume's region, or else the account's default region, by default. |
--shape <shape> | The Machine's size (see tonbo machine shapes). |
--port <port[:access]> | A port the Machine serves, private (the default) or public; repeat for several. |
--default-port <port> | The port served at the Machine's hostname without a port prefix; the first --port by default. |
--env <KEY=VALUE> | A non-secret environment variable; repeat for several. |
--sleep-after <seconds> | How long the Machine stays awake without a connection. |
--idle-action <action> | What sleeping does to the Machine. One of suspend, release. |
--stop-grace <seconds> | The seconds between SIGTERM and SIGKILL on a planned stop. |
--volume <name:path> | Mount the Volume <name> (see tonbo volume list) at <path>; a Machine has at most one, of its own region. |
--idempotency-key <key> | Reuse the key of an unconfirmed creation to get the Machine it created. |
--wait | Wait until the Machine is active, or say why it failed. |
--timeout <seconds> | How long --wait waits; 300 by default. |
--json | Print the API data as JSON. |
tonbo machine show
tonbo machine show <name> [options]Show a Machine, its hostnames and its state, or one of your computers.
| Flag | Description |
|---|---|
--json | Print the API data as JSON. |
tonbo machine update
tonbo machine update <name> [command...] [options]Change a Machine; [command...] after -- replaces its command at the next boot.
| Flag | Description |
|---|---|
--image <reference> | A new image, named as for create; applies at the next boot. |
--image-command | Run the image's own CMD again at the next boot. |
--unset-env <KEY> | Remove an environment variable; repeat for several. |
--clear-ports | Remove every port. |
--if-match <etag> | Change 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. |
--discard-snapshot | Apply a change that discards the Machine's snapshot. |
--no-volume | Remove the Machine's Volume at the next boot; the Volume is kept. |
--shape <shape> | The Machine's size (see tonbo machine shapes); applies at the next boot. |
--port <port[:access]> | A port the Machine serves, private (the default) or public; repeat for several; replaces every port. |
--default-port <port> | The port served at the Machine's hostname without a port prefix; the first --port by default, or the current default while --port still lists it. |
--env <KEY=VALUE> | A non-secret environment variable; repeat for several; applies at the next boot. |
--sleep-after <seconds> | How long the Machine stays awake without a connection. |
--idle-action <action> | What sleeping does to the Machine. One of suspend, release. |
--stop-grace <seconds> | The seconds between SIGTERM and SIGKILL on a planned stop. |
--volume <name:path> | Mount the Volume <name> (see tonbo volume list) at <path>; a Machine has at most one, of its own region; applies at the next boot. |
--json | Print the API data as JSON. |
tonbo machine sleep
tonbo machine sleep <name> [options]Put a Machine to sleep now; its next request boots it on its latest spec.
| Flag | Description |
|---|---|
--if-match <etag> | Put to sleep 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. |
--wait | Wait until the Machine is asleep. |
--timeout <seconds> | How long --wait waits; 300 by default. |
--json | Print the API data as JSON. |
tonbo machine delete
tonbo machine delete <name> [options]Delete a Machine with its disk, database and logs, or forget one of your computers.
| Flag | Description |
|---|---|
--yes | Delete without asking; required when stdin is not a terminal. |
--if-match <etag> | Delete 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. |
--json | Print the API data as JSON. |
tonbo machine activations
tonbo machine activations <name> [options]List a Machine's activations, newest first, and how each ended.
| Flag | Description |
|---|---|
--limit <count> | The most items to return. |
--cursor <cursor> | Continue from the cursor a previous page printed. |
--json | Print the API data as JSON. |
tonbo machine shapes
tonbo machine shapes [options]List the shapes a Machine may have.
| Flag | Description |
|---|---|
--json | Print the API data as JSON. |
tonbo usage
The account's rated usage.
tonbo usage show
tonbo usage show [options]Show one month's rated usage.
| Flag | Description |
|---|---|
--period <month> | The calendar month in UTC, as YYYY-MM; the current one by default. |
--json | Print the API data as JSON. |