+++
title = "Install the CLI and log in"
description = "Install bonsai on macOS or Linux, then log in with a browser or an API token."
weight = 115
updated = 2026-11-11

[extra]
nav_title = "Install and log in"
weight = 20
+++

## Install

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

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/omc/bonsai-cli/releases/latest/download/bonsai-installer.sh | sh
```

There are builds for macOS (Apple silicon and Intel) and Linux (x86-64 and ARM64). There is no Windows build.

To install by hand, download the archive for your machine from the [latest release](https://github.com/omc/bonsai-cli/releases/latest):

| Machine | Archive |
|---|---|
| macOS, Apple silicon | [`bonsai-aarch64-apple-darwin.tar.xz`](https://github.com/omc/bonsai-cli/releases/latest/download/bonsai-aarch64-apple-darwin.tar.xz) |
| macOS, Intel | [`bonsai-x86_64-apple-darwin.tar.xz`](https://github.com/omc/bonsai-cli/releases/latest/download/bonsai-x86_64-apple-darwin.tar.xz) |
| Linux, x86-64 | [`bonsai-x86_64-unknown-linux-musl.tar.xz`](https://github.com/omc/bonsai-cli/releases/latest/download/bonsai-x86_64-unknown-linux-musl.tar.xz) |
| Linux, ARM64 | [`bonsai-aarch64-unknown-linux-musl.tar.xz`](https://github.com/omc/bonsai-cli/releases/latest/download/bonsai-aarch64-unknown-linux-musl.tar.xz) |

Each release lists its archives' SHA-256 checksums in [`sha256.sum`](https://github.com/omc/bonsai-cli/releases/latest/download/sha256.sum). Download it next to the archive and check it, then unpack the archive and move `bonsai` to a folder on your `PATH`:

```bash
sha256sum --check --ignore-missing sha256.sum
tar -xJf bonsai-x86_64-unknown-linux-musl.tar.xz
mv bonsai-x86_64-unknown-linux-musl/bonsai ~/.local/bin/
```

On macOS, use `shasum -a 256` in place of `sha256sum`.

With Nix:

```bash
nix profile install github:omc/bonsai-cli
```

From source, with Rust 1.88 or newer:

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

Check that it runs:

```bash
bonsai --version
```

## Log in

```bash
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. `bonsai login --web` picks this without asking, and `--no-browser` prints the link instead of opening it, for a machine you reach over SSH.
- **With a token.** Paste an [API token](@/docs/account/api-tokens/index.md) created in the dashboard. In scripts, pipe it in:

  ```bash
  bonsai login --with-token < token.txt
  ```

The token decides what the CLI can do. Creating, resizing and destroying clusters needs `clusters:write`, connection URLs need `credentials:read`, and top search queries need `query_logs:read`. See [scopes](@/docs/api/authentication/index.md#scopes).

### Where the token is kept

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` in the [config folder](@/docs/cli/configuration/index.md#files) instead, readable only by you.

A stored token is used only with the API URL it was logged in to.

### In CI

Skip `login` and set `BONSAI_TOKEN`:

```bash
export BONSAI_TOKEN=bonsai_<key>_<secret>
```

`BONSAI_TOKEN` wins over a stored token. See [Scripting and CI](@/docs/cli/scripting/index.md).

## Check your setup

`bonsai whoami` shows which account and token you're using, and where the token came from:

```
$ bonsai whoami
Account             Acme Search (acme)
Profile             default
API                 https://api.bonsai.io/v1
Token               keychain
Token key (public)  1a2b3c4d5e6f7a8b
Token name          Bonsai CLI on macbook
Scopes              account:read, clusters:read, clusters:write, credentials:read
Expires             never
```

`bonsai doctor` checks that the API is reachable, the token is valid, the CLI and the API agree on the API's version, and your clock is right:

```
$ bonsai doctor
✓ API reachable     https://api.bonsai.io/v1 (Bonsai API)
✓ Token valid       Acme Search (acme), from the keychain
✓ Contract version  1.0.0-draft
✓ Clock             0s off the API's
```

## Log out

```bash
bonsai logout
```

This revokes the token on Bonsai and forgets it on this machine. Add `--keep-token` to leave the token valid and only forget it here, for a token that other machines share.

## Update

Once a day, a command run in a terminal checks for a newer release, and ends with a line saying how to update when there is one. If you used the install script, update with:

```bash
bonsai-update
```

See [Updates](@/docs/cli/configuration/index.md#updates) for what the check sends and how to turn it off.