+++
title = "Managing clusters with the CLI"
description = "List, create, show, rename, resize and destroy clusters, and follow their Actions."
weight = 117
updated = 2026-11-11

[extra]
nav_title = "Managing clusters"
weight = 40
+++

Everything about clusters is a subcommand of `bonsai cluster`.

## Naming a cluster

Commands take a cluster's ID (`search-nozais`) or its name (`search`). If two clusters share a name, the command exits with code 2 and asks for the ID.

Set `BONSAI_CLUSTER` to give commands a default cluster:

```bash
export BONSAI_CLUSTER=search
bonsai cluster show
bonsai cluster usage
```

`cluster rename` and `cluster resize` always take the cluster as an argument.

## List clusters

```
$ bonsai cluster list
NAME    ID             STATE  PLAN          REGION         SIZE
search  search-nozais  ready  standard-fir  aws-us-east-1  233.0 MiB
```

Filter with `--state`, `--region` and `--name`:

```bash
bonsai cluster list --state ready --region aws-us-east-1
```

A cluster's state is one of `draft`, `provisioning`, `ready`, `failed`, `read_only`, `disabled`, `deprovisioning` or `deprovisioned`. Destroyed clusters stay in the list as `deprovisioned`.

## Show a cluster

`bonsai cluster show <cluster>` prints the cluster's state, plan, region, release, host, usage against its plan's limits, and latest Action. It doesn't print the password; that's [`cluster url`](@/docs/cli/connection-urls/index.md).

`bonsai cluster open <cluster>` opens the cluster's page in the dashboard. Add `--no-browser` to print the link instead.

## Create a cluster

```bash
bonsai cluster create search --plan standard-fir --region aws-us-east-1
```

| Flag | |
|---|---|
| `--plan <P>` | The plan's ID, from `bonsai plans` |
| `--region <R>` | The region's ID, from `bonsai regions` |
| `--space <S>` | A private space's ID, from `bonsai spaces`, instead of a region |
| `--release <V>` | The release's ID, from `bonsai releases`. Without it, you get the first one the plan offers in the region |
| `--keep-failed` | Leave a cluster whose create failed, instead of removing it |
| `--no-wait`, `--timeout`, `--idempotency-key` | See [Actions](#actions) |

On a terminal, `cluster create` asks for the plan and region if you leave them out. Without a terminal, it needs every flag.

If the build fails after Bonsai started it, Bonsai removes the failed cluster, and the CLI tells you so. `--keep-failed` leaves it in place to look at.

A paid plan needs a payment method on the account, unless the account is billed by invoice. Without one, the create is refused with exit code 6, and the message has a link to a page where a card can be added.

### Plans, regions, spaces and releases

```bash
bonsai plans                          # plans your account may use, and where
bonsai plans --region aws-eu-west-1   # only plans offered in one region
bonsai plans --release opensearch-3.8.0
bonsai regions                        # regions open for new clusters
bonsai regions --plan standard-fir    # only regions where one plan is offered
bonsai spaces                         # your account's private spaces
bonsai releases                       # Elasticsearch and OpenSearch releases
bonsai releases --engine opensearch
```

## Rename a cluster

```
$ bonsai cluster rename search search-prod
✓ Renamed search to search-prod (search-nozais)
```

Renaming changes the name only. The cluster's ID, host and URL stay the same.

## Resize a cluster

`cluster resize` moves a cluster to another plan:

```bash
bonsai cluster resize search standard-oak
```

A smaller plan can refuse a cluster that is over its limits (exit code 8). The price changes with the plan.

## Destroy a cluster

```bash
bonsai cluster destroy search
```

On a terminal, this asks you to type the cluster's name. Where there are no prompts, pass the cluster's current name with `--confirm`:

```bash
bonsai cluster destroy search-nozais --confirm search
```

Destroying a cluster deletes its data, and can't be undone.

## Actions {#actions}

Creating, resizing and destroying take a while, so each runs as an [Action](@/docs/api/actions/index.md) on Bonsai's side. The CLI waits for the Action and shows its steps as they finish.

- **`--timeout <D>`** stops waiting after a duration such as `90s`, `10m` or `1h30m`. The default is `30m`. Running out exits with code 9. The Action keeps running.
- **`--no-wait`** prints the Action and returns at once.
- **Ctrl-C** stops waiting, not the Action.
- **`bonsai wait <action-id>`** picks the wait up again later, after any of the three.
- **`--idempotency-key <KEY>`** sends your own `Idempotency-Key` instead of a fresh one, for scripts that retry on their own. See [Retrying safely](@/docs/api/retrying-safely/index.md).

```bash
bonsai cluster create search --plan standard-fir --region aws-us-east-1 --no-wait
bonsai wait act_x9jwtigfg398a72v
```

Only one change runs on a cluster at a time. Starting a second one exits with code 7.

`bonsai cluster wait <cluster>` blocks until a cluster is `ready`, whichever Action is getting it there.

### History

`bonsai cluster history <cluster>` lists a cluster's Actions, newest first, including the ones Bonsai starts on its own. Add `--steps` to show each Action's steps and `--limit <N>` to cap the list:

```
$ bonsai cluster history search --steps
act_x9jwtigfg398a72v  cluster.provision  success  1s ago
  ✓ Reserving capacity  just now
  ✓ Provisioning cluster  just now
  ✓ Configuring routes  just now
  ✓ Running health check  just now
```

`bonsai action show <action-id>` shows one Action: its type, state, subject, steps, error and result.