Skip to content

About

The command-line client for Bonsai, managed Elasticsearch and OpenSearch.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Bonsai

Bonsai CLI

The command-line client for Bonsai, managed Elasticsearch and OpenSearch.

Documentation     Quickstart     AI agents     Command reference     Changelog

Download for macOS, Apple silicon Download for macOS, Intel Download for Linux, x86-64 Download for Linux, ARM64

bonsai creates, resizes and destroys clusters, gets their connection URLs, and shows their usage, metrics and top search queries, from your terminal, from CI, or through a coding agent. It talks to the Bonsai API with your account's token, so anything it does, the dashboard and the API can do too.

bonsai login
bonsai cluster create search --plan standard-fir --region aws-us-east-1
bonsai cluster url search --write .env

A terminal session: creating a cluster, writing its connection URL to .env, then checking its usage and listing clusters

Install

On macOS or Linux, the install script downloads the binary for your machine:

curl --proto '=https' --tlsv1.2 -LsSf https://bonsai.io/install.sh | sh

To install by hand, download the archive for your machine with one of the buttons above, or from the latest release, and put bonsai on your PATH. Each release lists its checksums in sha256.sum. There are builds for macOS (Apple silicon and Intel) and Linux (x86-64 and ARM64). There is no Windows build.

With Nix:

nix profile install github:omc/bonsai-cli

From source, with Rust 1.88 or newer:

git clone https://github.com/omc/bonsai-cli
cd bonsai-cli
cargo install --path crates/bonsai

If you used the install script, bonsai-update moves you to the latest release. See Install and log in.

Log in

bonsai login

On a terminal, bonsai login asks how you want to log in:

  • With a browser. It shows a one-time code and opens a Bonsai page where you approve the login. The CLI receives a new API token, named after your machine. Add --no-browser to print the link instead of opening it.
  • With a token. Paste an API token created in the Bonsai dashboard. In scripts, pipe it in with bonsai login --with-token < token.txt.

The token goes in your system keychain: the macOS Keychain or the Secret Service on Linux. On a machine without a keychain, add --store-file to keep it in credentials.toml instead, readable only by you.

In CI, skip login and set BONSAI_TOKEN:

export BONSAI_TOKEN=bonsai_…

bonsai whoami shows which account and token you're using. bonsai doctor checks your setup.

Quick start

bonsai plans                                    # what you can create, and where
bonsai regions --plan standard-fir              # where one plan is offered
bonsai cluster create search --plan standard-fir --region aws-us-east-1
bonsai cluster url search                       # the connection URL, password included
bonsai cluster usage search
bonsai cluster metrics search
bonsai cluster queries search                   # needs the query_logs:read scope
bonsai cluster destroy search --confirm 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 region or the plan. Run without a terminal, it needs every flag.

Use the URL in your app:

export BONSAI_URL=$(bonsai cluster url search)
bonsai cluster url search --write .env

--write sets BONSAI_URL in the file (--env names another variable), replacing the old line, without printing the URL. It writes only inside the current folder, refuses a file that git doesn't ignore or that is tracked, and leaves the file with mode 0600.

The quickstart walks through the same steps with their output.

Commands

Area Commands
Account login, logout, whoami, doctor, version
Clusters cluster list, cluster create, cluster show, cluster open, cluster rename, cluster resize, cluster destroy, cluster wait, cluster history
Connecting cluster url
Watching cluster usage, cluster metrics, cluster queries
Actions action show, wait
Catalogue plans, regions, spaces, releases
Anything else api, completion
Agents skill install, skill print, mcp

bonsai <command> --help shows each command's flags, and the command reference lists them all.

A cluster can be named by its ID or by its name. Set BONSAI_CLUSTER to give commands a default cluster.

Slow work such as creating, resizing and destroying runs as an Action on Bonsai's side. The CLI waits for it by default. With --no-wait it returns at once, and bonsai wait <action-id> picks the wait up again later. Ctrl-C stops waiting, not the Action.

bonsai api sends any request to the API with your token, for things that have no command yet:

bonsai api GET /clusters --paginate
bonsai api POST /clusters/<cluster-id>/credentials -d '{"name": "reader", "access_type": "ro"}'

It prints the API's response as it is, so it can print passwords. Paths take cluster IDs, not names.

Scripting and CI

Every command takes --json, which prints the API's JSON for scripts and jq. Messages and progress go to stderr and data goes to stdout, so $(bonsai cluster url search) captures only the URL.

Commands never prompt when stdin isn't a terminal, when CI is set, or with --no-input. Instead they fail with exit code 2 and name the missing flag.

id=$(bonsai cluster create "ci-$RUN_ID" --plan sandbox --region aws-us-east-1 --json | jq -r .result.cluster)
export BONSAI_URL=$(bonsai cluster url "$id")
run-tests
bonsai cluster destroy "$id" --confirm "ci-$RUN_ID"

Exit codes say what went wrong: 3 for a missing token or scope, 4 for not found, 5 for a failed Action, 9 for a timeout. Scripting and CI has the full list.

AI agents

A coding agent can manage clusters with the same binary, in two ways. You can use both.

bonsai skill install writes a Claude Code skill to ~/.claude/skills/bonsai/SKILL.md. It tells the agent to use --json --no-input, which commands to run, what the exit codes mean, and to confirm before changes that cost money. For other agents, bonsai skill print prints the same text, e.g. to add to AGENTS.md.

bonsai mcp is an MCP server on stdin and stdout, for clients that call tools instead of running a shell. To add it to Claude Code, run this in your project folder:

claude mcp add bonsai -- bonsai mcp

Other clients (Claude Desktop, Cursor, VS Code) take the usual mcpServers entry: {"bonsai": {"command": "bonsai", "args": ["mcp"]}}.

The agent never sees your API token or a cluster's password. The server uses the token bonsai login stored, so nothing goes in the client's config, and write_cluster_url writes the connection URL to a git-ignored env file and answers with the password as ****. destroy_cluster needs the cluster's current name as confirmation, and bonsai mcp --read-only leaves out the tools that change clusters.

See Using Bonsai with AI agents for setup by client, example prompts and the safety model.

Documentation

Overview What the CLI does, and when to use the API or Terraform instead
Install and log in Installing, logging in, where the token is kept, updating
Quickstart Create a cluster, connect to it, watch it and destroy it
Managing clusters Create, show, rename, resize and destroy, and how Actions run
Connection URLs Get a cluster's URL without leaking its password
Usage, metrics and queries What a cluster holds and how it's used
Scripting and CI JSON output, exit codes, running without prompts, bonsai api
Agent skill Teach Claude Code, or another agent, to use the CLI
MCP server The tools bonsai mcp serves, and how to connect a client
Configuration Profiles, environment variables, files, shell completion, update checks
Command reference Every command and flag

Support

If you have a question, a problem, or something you'd like the CLI to do, write to support@bonsai.io.

Contributing

The workspace has five crates:

Crate What it is
crates/bonsai The bonsai binary
crates/bonsai-api The HTTP client and the API's types
crates/bonsai-core Login, config, token storage, and waiting on Actions
crates/bonsai-contract Checks responses against openapi/v1.yml, the API's OpenAPI description
crates/bonsai-mock A local mock of the Bonsai API, for development and tests
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
BONSAI_KEYRING=off cargo test --workspace

Running against the mock

bonsai-mock is a working stand-in for the Bonsai API, backed by SQLite. It implements every operation in openapi/v1.yml and keeps state between requests, so you can try every command without a Bonsai account.

cargo run -p bonsai-mock -- --db /tmp/bonsai-mock.sqlite serve --port 4010

On first start it prints a token for each of its two demo accounts:

  • acme has every scope and a card on file.
  • globex has read-only scopes and no card, for testing payment errors.

Then log in against it:

echo '<acme token>' | BONSAI_KEYRING=off bonsai login --with-token --store-file --api-url http://127.0.0.1:4010/v1
bonsai cluster create demo --plan standard-fir --region aws-us-east-1

Scenarios make the next request fail in a chosen way:

cargo run -p bonsai-mock -- --db /tmp/bonsai-mock.sqlite scenario set fail_next action_failed
cargo run -p bonsai-mock -- --db /tmp/bonsai-mock.sqlite scenario set metrics_unavailable true
cargo run -p bonsai-mock -- --db /tmp/bonsai-mock.sqlite scenario set rate_limit_next 3
cargo run -p bonsai-mock -- --db /tmp/bonsai-mock.sqlite scenario clear

Other flags:

  • --step-ms sets how long each Action step takes (default 1500).
  • --reset starts from a fresh database.
  • --public-url sets the origin the mock puts in links and Location headers, and accepts its host as a Host; use it behind a TLS proxy.
  • --checkout-url makes payment action_urls that prefix plus a fake Stripe session ID, instead of the mock's own checkout page.
  • bonsai-mock token create --account acme --scopes "…" makes more tokens.

The mock only listens on 127.0.0.1.

The mock's tests check every response it sends against openapi/v1.yml. A coverage test makes sure every operation, and every status code the contract documents, is exercised.

License

Apache 2.0. See LICENSE.

About

The command-line client for Bonsai, managed Elasticsearch and OpenSearch.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages