+++
title = "Bonsai CLI"
description = "What the bonsai command-line client does, and where to start."
weight = 114
updated = 2026-11-11

[extra]
nav_title = "Overview"
weight = 10
+++

`bonsai` is the command-line client for Bonsai. It talks to the [Bonsai API v1](@/docs/api/overview/index.md) with your account's token, so anything it does, the dashboard and the API can do too. With it you can:

- Create, rename, resize and destroy clusters, and wait for those changes to finish.
- Get a cluster's connection URL, or write it straight into your app's `.env` file.
- Read a cluster's usage, request metrics and top search queries.
- List the plans, regions, private spaces and releases your account can use.
- Send any other API request with `bonsai api`.
- Give a coding agent the same abilities, with a [skill](@/docs/cli/agent-skill/index.md) or an [MCP server](@/docs/cli/mcp-server/index.md).

It runs on macOS and Linux.

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

## Start here

- [Install and log in](@/docs/cli/install/index.md): get the binary, then log in with a browser or a token.
- [Quickstart](@/docs/cli/quickstart/index.md): create a cluster, connect to it, watch it and destroy it.
- [Managing clusters](@/docs/cli/clusters/index.md): create, show, rename, resize and destroy, and how slow changes run as Actions.
- [Connection URLs](@/docs/cli/connection-urls/index.md): get a cluster's URL without leaking its password.
- [Usage, metrics and queries](@/docs/cli/monitoring/index.md): watch what a cluster holds and how it's used.
- [Scripting and CI](@/docs/cli/scripting/index.md): JSON output, exit codes, running without prompts, and `bonsai api`.
- [Agent skill](@/docs/cli/agent-skill/index.md): teach Claude Code, or another agent, to use the CLI.
- [MCP server](@/docs/cli/mcp-server/index.md): serve the cluster tools to Claude Code, Claude Desktop, Cursor or VS Code.
- [Configuration](@/docs/cli/configuration/index.md): profiles, environment variables, files, shell completion and updates.
- [Command reference](@/docs/cli/reference/index.md): every command and flag.

## 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` |
| Catalog | `plans`, `regions`, `spaces`, `releases` |
| Anything else | `api`, `completion` |
| Agents | `skill install`, `skill print`, `mcp` |

`bonsai <command> --help` shows each command's flags.

## The CLI, the API or Terraform?

- Use the **CLI** at a terminal, in shell scripts and CI jobs, and with coding agents.
- Use the [**API**](@/docs/api/overview/index.md) from your own code, or for what the CLI has no command for yet, such as managing credentials. `bonsai api` reaches those from the shell.
- Use the [**Terraform provider**](@/docs/integrations/deploy-with-terraform/index.md) when clusters belong in your infrastructure as code.

## Questions and feedback

If you have a question, a problem, or something you'd like the CLI to do, write to [support@bonsai.io](mailto:support@bonsai.io).