+++
title = "CLI Quickstart"
description = "Create a cluster, connect to it, watch it, resize it and destroy it."
weight = 116
updated = 2026-11-11

[extra]
nav_title = "Quickstart"
weight = 30
+++

This walks through the life of a cluster with the `bonsai` CLI: pick a plan and a region, create the cluster, connect to it, watch it, and destroy it. It assumes you have [installed the CLI and logged in](@/docs/cli/install/index.md), with a token that has the `clusters:write` and `credentials:read` scopes.

## 1. Pick a plan and a region

Plans differ by account. List the ones yours can use:

```
$ bonsai plans
ID              NAME            PRICE    TENANCY  REGIONS
sandbox         Sandbox         Free     shared   aws-us-east-1
staging         Staging         $15/mo   shared   aws-us-east-1
standard-fir    Standard Fir    $20/mo   shared   aws-ap-southeast-2, aws-eu-ce…
standard-elm    Standard Elm    $50/mo   shared   aws-ap-southeast-2, aws-eu-ce…
…
```

Then see where one plan is offered:

```
$ bonsai regions --plan standard-fir
ID                  NAME                       CLOUD
aws-ap-southeast-2  AWS Asia Pacific (Sydney)  aws
aws-eu-central-1    AWS Germany (Frankfurt)    aws
aws-eu-west-1       AWS EU West (Ireland)      aws
aws-us-east-1       AWS US East (Virginia)     aws
aws-us-west-2       AWS US West (Oregon)       aws
```

## 2. Create the cluster

```
$ bonsai cluster create search --plan standard-fir --region aws-us-east-1
Provisioning search (act_x9jwtigfg398a72v)
  ✓ Reserving capacity
  ✓ Provisioning cluster
  ✓ Configuring routes
  ✓ Running health check
✓ search is ready  search-nozais.us-east-1.bonsaisearch.net
  Connection URL (includes the password): run bonsai cluster url search
```

`cluster create` waits until the cluster is ready and shows each step. On a terminal it asks for anything you leave out, such as the plan or the region.

A paid plan needs a payment method on the account. Without one, the create is refused with exit code 6 and a link to a page where a card can be added. Nothing is created.

From here on, name the cluster by its name (`search`) or by its ID (`search-nozais`).

## 3. Connect to it

Write the cluster's URL into the file your app reads:

```
$ bonsai cluster url search --write .env
✓ Added BONSAI_URL in .env
```

That sets `BONSAI_URL` in `.env` without printing the password. The file must be ignored by git, so the password can't be committed.

Or print the URL, for a shell variable:

```bash
export BONSAI_URL=$(bonsai cluster url search)
curl "$BONSAI_URL"
```

The URL includes the password, so keep it out of logs and source control. See [Connection URLs](@/docs/cli/connection-urls/index.md).

## 4. Watch it

```
$ bonsai cluster show search
Name           search
ID             search-nozais
State          ready
Plan           Standard Fir (standard-fir)
Region         AWS US East (Virginia) (aws-us-east-1)
Release        OpenSearch 3.8.0 (opensearch-3.8.0)
Host           search-nozais.us-east-1.bonsaisearch.net
Docs           28,553 / 500,000 (5%)
Shards         2 / 10 (20%)
Size           233.0 MiB / 953.7 MiB (24%)
Latest action  cluster.provision success (act_x9jwtigfg398a72v)
Created        2026-11-11 17:23:46 UTC (1s ago)
```

```bash
bonsai cluster usage search      # docs, shards and size against the plan's limits
bonsai cluster metrics search    # request rates, errors and latency
bonsai cluster queries search    # top search terms; needs the query_logs:read scope
```

See [Usage, metrics and queries](@/docs/cli/monitoring/index.md).

## 5. Resize it

When the cluster outgrows its plan, move it to another:

```
$ bonsai cluster resize search standard-oak
Changing the plan of search (act_z5giu466ldqqawho)
  ✓ Checking capacity
  ✓ Changing plan
  ✓ Updating billing
✓ search is on standard-oak now
```

## 6. Destroy it

```bash
bonsai cluster destroy search
```

On a terminal, this asks you to type the cluster's name. In a script, pass it with `--confirm search`.

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

## Next steps

- [Managing clusters](@/docs/cli/clusters/index.md): every cluster command, and how Actions work.
- [Scripting and CI](@/docs/cli/scripting/index.md): `--json`, exit codes and running without prompts.
- [Agent skill](@/docs/cli/agent-skill/index.md) and [MCP server](@/docs/cli/mcp-server/index.md): let a coding agent do all of the above.