+++
title = "Configuring the CLI"
description = "Profiles, environment variables, config files, shell completion and updates."
weight = 123
updated = 2026-11-11

[extra]
nav_title = "Configuration"
weight = 100
+++

The CLI works without any configuration once you've logged in. These settings are for more than one account, unusual networks, and tuning the output.

## Flags and environment variables

| | |
|---|---|
| `--profile`, `BONSAI_PROFILE` | Use a named profile, such as one per account |
| `--api-url`, `BONSAI_API_URL` | Talk to another API URL. The default is `https://api.bonsai.io/v1` |
| `BONSAI_TOKEN` | Use this token instead of the stored one |
| `BONSAI_CLUSTER` | The default cluster, by ID or name |
| `BONSAI_CA_BUNDLE` | Extra CA certificates (PEM), such as behind a TLS-inspecting proxy |
| `BONSAI_KEYRING=off` | Don't use the system keychain |
| `BONSAI_NO_UPDATE_NOTIFIER` | Don't check for new releases |
| `CI` | When set, commands never prompt, and the update check is skipped |
| `COLUMNS` | The table width, on a terminal |
| `NO_COLOR` | Turn colour off |
| `--json` | Print the API's JSON instead of tables and text |
| `--no-input` | Never prompt. A missing value is an error (exit code 2) |
| `-q`, `--quiet` | Print only data and errors |
| `-v`, `-vv` | Log requests to stderr. Tokens are never logged |

A flag wins over its environment variable, which wins over the config file. The flags in this table work on every command, before or after its name.

## Profiles

A profile is a named login. Use one per account to switch between them:

```bash
bonsai login --profile work
bonsai login --profile personal

bonsai cluster list --profile work
BONSAI_PROFILE=personal bonsai cluster list
```

Without `--profile`, the CLI uses the profile named `default`. `bonsai whoami` shows which profile and account a command would use.

Each profile keeps its own token. A stored token is used only with the API URL it was logged in to: point a profile at another URL and the CLI refuses to send the token there. Log in again, or set `BONSAI_TOKEN`.

## Files {#files}

Settings live in `~/.config/bonsai/`, or in `$XDG_CONFIG_HOME/bonsai/` if that is set:

| File | |
|---|---|
| `config.toml` | Your profiles |
| `credentials.toml` | Stored tokens, only when you logged in with `--store-file`. Mode `0600` |
| `update-check.json` | When the CLI last checked for a new release |

Tokens are otherwise in your system keychain, not in a file.

## Shell completion

`bonsai completion <shell>` prints a completion script for `bash`, `zsh`, `fish`, `elvish` or `powershell`. Load it from your shell's startup file:

```bash
# bash, in ~/.bashrc
source <(bonsai completion bash)

# zsh, in ~/.zshrc
source <(bonsai completion zsh)

# fish
bonsai completion fish > ~/.config/fish/completions/bonsai.fish
```

## Updates {#updates}

Once a day, a command run in a terminal asks GitHub (`api.github.com`) for the latest release. If it's newer, the command ends with a line saying how to update, such as `bonsai-update` if you used the install script.

The request carries only the CLI's version, operating system and architecture, in its User-Agent. The check is skipped in CI, under `--quiet`, when stderr isn't a terminal, for Nix installs, and when `BONSAI_NO_UPDATE_NOTIFIER` is set.

`bonsai version` shows the CLI's version, the version of the API it was built for, and the version of the API it's talking to.