+++
title = "CLI command reference"
description = "Every bonsai command and its flags."
weight = 124
updated = 2026-11-11

[extra]
nav_title = "Command reference"
weight = 110
+++

Every `bonsai` command and its flags. `bonsai <command> --help` prints the same for the version you have installed.

`<cluster>` is a cluster's ID or name. Where noted, it can be left out when `BONSAI_CLUSTER` is set. Durations (`<D>`) are written like `90s`, `10m`, `1h30m` or `7d`.

## Global flags

These work on every command.

| Flag | |
|---|---|
| `--json` | Print the API's JSON instead of tables and text |
| `--no-input` | Never prompt. A missing value is an error (exit code 2) |
| `-q`, `--quiet` | Print only data and errors, no progress or notes |
| `-v`, `--verbose` | Log requests to stderr. `-vv` logs more |
| `--profile <P>` | The config profile to use. Also `BONSAI_PROFILE` |
| `--api-url <URL>` | The API root. Also `BONSAI_API_URL` |
| `-h`, `--help` | Print help |
| `-V`, `--version` | Print the version |

List commands also take `-w`, `--wide` to show every column.

## Account

### bonsai login

Log in with a browser or an API token. See [Install and log in](@/docs/cli/install/index.md).

| Flag | |
|---|---|
| `--web` | Log in through the browser, without asking |
| `--no-browser` | Print the login link instead of opening it |
| `--with-token` | Read an API token from stdin |
| `--store-file` | Without a keychain, keep the token in `credentials.toml` (mode `0600`) |

### bonsai logout

Revoke the token and forget it on this machine.

| Flag | |
|---|---|
| `--keep-token` | Leave the token valid on Bonsai, and only forget it here |

### bonsai whoami

Show the account, profile, API URL, the token's key, name, scopes and expiry, and where the token came from.

### bonsai doctor

Check the API, the token, the contract version and the clock.

### bonsai version

Show the CLI's version, the version of the API it was built for, and the version of the API it's talking to.

## Clusters

See [Managing clusters](@/docs/cli/clusters/index.md).

### bonsai cluster list

List clusters.

| Flag | |
|---|---|
| `--state <S>` | Only clusters in this state |
| `--region <R>` | Only clusters in this region |
| `--name <N>` | Only clusters with this name |

### bonsai cluster create

`bonsai cluster create <name>` creates a cluster and waits until it's ready.

| Flag | |
|---|---|
| `--plan <P>` | The plan's ID |
| `--region <R>` | The region's ID |
| `--space <S>` | A private space's ID, instead of a region |
| `--release <V>` | The release's ID. The default is the first the plan offers in the region |
| `--keep-failed` | Leave a cluster whose create failed, instead of removing it |
| `--no-wait` | Print the Action and return without waiting |
| `--timeout <D>` | Stop waiting after this long (exit code 9). The Action keeps running. The default is `30m` |
| `--idempotency-key <KEY>` | Send this `Idempotency-Key` instead of a fresh one |

### bonsai cluster show

`bonsai cluster show [cluster]` shows a cluster's state, plan, host, usage and latest Action.

### bonsai cluster open

`bonsai cluster open [cluster]` opens the cluster's page in the dashboard.

| Flag | |
|---|---|
| `--no-browser` | Print the link instead of opening it |

### bonsai cluster rename

`bonsai cluster rename <cluster> <new-name>` renames a cluster.

### bonsai cluster resize

`bonsai cluster resize <cluster> <plan>` changes a cluster's plan. Takes `--no-wait`, `--timeout <D>` and `--idempotency-key <KEY>`, as `cluster create` does.

### bonsai cluster destroy

`bonsai cluster destroy [cluster]` deprovisions a cluster and deletes its data. Takes `--no-wait`, `--timeout <D>` and `--idempotency-key <KEY>`, as `cluster create` does.

| Flag | |
|---|---|
| `--confirm <NAME>` | The cluster's current name. Needed when prompts are off |

### bonsai cluster wait

`bonsai cluster wait [cluster]` blocks until a cluster reaches a state.

| Flag | |
|---|---|
| `--for <STATE>` | The state to wait for. `ready` is the default, and the only one |
| `--timeout <D>` | Give up after this long (exit code 9). The default is `30m` |

### bonsai cluster history

`bonsai cluster history [cluster]` lists a cluster's Actions, newest first.

| Flag | |
|---|---|
| `--limit <N>` | At most this many Actions |
| `--steps` | Show each Action's steps |

### bonsai cluster url

`bonsai cluster url [cluster]` prints a cluster's connection URL, password included, or writes it to a file. See [Connection URLs](@/docs/cli/connection-urls/index.md).

| Flag | |
|---|---|
| `--write <FILE>` | Set the variable in this file instead of printing the URL. The file must be inside the current folder and, in a git repository, ignored by git |
| `--env <NAME>` | Print `NAME=<url>`. With `--write`, the variable to set. The default there is `BONSAI_URL` |
| `--credential <ID>` | The credential's ID. The default is the cluster's default credential |

### bonsai cluster usage

`bonsai cluster usage [cluster]` shows docs, shards and size against the plan's limits, over time. See [Usage, metrics and queries](@/docs/cli/monitoring/index.md).

| Flag | |
|---|---|
| `--since <D>` | How far back to look, at most 90 days. The default is `7d` |

### bonsai cluster metrics

`bonsai cluster metrics [cluster]` shows request rates, errors, traffic and latency over time.

| Flag | |
|---|---|
| `--since <D>` | How far back to look, at most 30 days. The default is `1h` |
| `--resolution <R>` | The bucket size, such as `1m` or `1h` |

### bonsai cluster queries

`bonsai cluster queries [cluster]` shows the most frequent search terms. Needs the `query_logs:read` scope.

| Flag | |
|---|---|
| `--window <W>` | The window the API counts over. The default is `7d` |
| `--top <N>` | Show this many terms. The default is 20, or every term under `--json` |

## Actions

### bonsai action show

`bonsai action show <action-id>` shows an Action's type, state, subject, steps, error and result.

### bonsai wait

`bonsai wait <action-id>` waits for an Action again, after `--no-wait`, Ctrl-C or a timeout.

| Flag | |
|---|---|
| `--timeout <D>` | Give up after this long (exit code 9). The Action keeps running. The default is `30m` |

## Catalog

### bonsai plans

Plans this account may use.

| Flag | |
|---|---|
| `--region <R>` | Only plans offered in this region |
| `--release <V>` | Only plans offering this release. With `--region`, in that region |

### bonsai regions

Regions open for new clusters.

| Flag | |
|---|---|
| `--plan <P>` | Only regions where this plan is offered |

### bonsai spaces

The account's private spaces.

### bonsai releases

Releases this account may use.

| Flag | |
|---|---|
| `--engine <ENGINE>` | Only this engine's releases: `elasticsearch` or `opensearch` |

## Other

### bonsai api

`bonsai api <method> <path>` sends an authenticated request to `/v1` and prints the JSON. See [`bonsai api`](@/docs/cli/scripting/index.md#bonsai-api).

| Flag | |
|---|---|
| `-d`, `--data <JSON>` | The JSON body. `@FILE` reads a file, and `-` reads stdin |
| `-H`, `--header <NAME: VALUE>` | An extra header. Repeatable |
| `--paginate` | Follow `next_cursor` and print every page's data as one array |

### bonsai completion

`bonsai completion <shell>` prints a completion script for `bash`, `zsh`, `fish`, `elvish` or `powershell`.

## Agents

### bonsai skill install

Write the bonsai skill to `~/.claude/skills`. See [Agent skill](@/docs/cli/agent-skill/index.md).

| Flag | |
|---|---|
| `--project` | Install into `./.claude/skills` instead |

### bonsai skill print

Print the skill, such as to add it to `AGENTS.md`.

### bonsai mcp

Serve the cluster tools to Claude Code or another MCP client, over stdio. See [MCP server](@/docs/cli/mcp-server/index.md).

| Flag | |
|---|---|
| `--read-only` | Leave out the tools that create, rename, resize or destroy clusters |

## Exit codes

See [Exit codes](@/docs/cli/scripting/index.md#exit-codes).