> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# 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](https://tonbo.dev/docs/reference/management.md), 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](https://tonbo.dev/docs/platform/api-keys.md)). 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 login`](#tonbo-login)
- [`tonbo logout`](#tonbo-logout)
- [`tonbo account`](#tonbo-account)
- [`tonbo region`](#tonbo-region)
- [`tonbo member`](#tonbo-member)
- [`tonbo agent`](#tonbo-agent)
- [`tonbo api-key`](#tonbo-api-key)
- [`tonbo database`](#tonbo-database)
- [`tonbo stream`](#tonbo-stream)
- [`tonbo machine`](#tonbo-machine)
- [`tonbo usage`](#tonbo-usage)

## Global flags

`-h, --help` after any command prints its help.

| Flag | Description |
| --- | --- |
| `-V, --version` | Output the version number. |

## `tonbo login`

```shell
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`

```shell
tonbo logout
```

Revoke this computer's key and remove the saved login.

## `tonbo account`

The account you are logged in to.

### `tonbo account show`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
tonbo api-key show <key-id> [options]
```

Show one key.

| Flag | Description |
| --- | --- |
| `--json` | Print the API data as JSON. |

### `tonbo api-key revoke`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`](https://tonbo.dev/docs/machines/troubleshooting/manage.md#region_not_offered) (422), “Machines are not offered in any region yet.”

The account's Machines.

### `tonbo machine list`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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`

```shell
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. |