> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> What the bonya CLI is, how to install it, and how it resolves sandboxes and config

`bonya` is the command-line client for the Bonya Compute API — create sandboxes, get a shell in one, move files in and out, and publish preview URLs. It is a thin wrapper around the Go SDK: every command builds an SDK client and calls straight into it.

```shell Shell theme={null}
bonya login              # authenticate in your browser
bonya console            # pick a sandbox (or create one) and get a shell
```

## Install

```shell Homebrew theme={null}
brew install bonyai/tap/bonya
```

```shell Install script theme={null}
curl -fsSL https://get.bonya.ai/install.sh | sh
```

Both work on macOS and Linux. Every command supports `-h`/`--help`, and `bonya --version` (or `bonya version`) prints the installed version.

## Command groups

`bonya --help` groups commands by what they're for, rather than listing them alphabetically:

> [card] [Getting started](https://docs.bonya.ai/cli-reference/login.md)
>
> `login`, `console`, `create`

> [card] [Sandboxes](https://docs.bonya.ai/cli-reference/sandboxes.md)
>
> `list`, `get`, `delete`, `exec`

> [card] [Inside a sandbox](https://docs.bonya.ai/cli-reference/fs.md)
>
> `fs`, `session`, `preview`, `snapshot`

> [card] [Account](https://docs.bonya.ai/cli-reference/org.md)
>
> `org`, `whoami`, `logout`, `version`

## Persistent flags

Every command accepts these flags, each falling back to an environment variable and then to whatever `bonya login` saved. See [Configuration](https://docs.bonya.ai/cli-reference/configuration.md) for the exact precedence rules and config file location.

| Flag | Environment variable | Notes |
| - | - | - |
| `--api-key` | `BONYA_API_KEY` | Required, from a flag, env var, or saved login. |
| `--endpoint` | `BONYA_ENDPOINT` | API endpoint. Defaults to `https://api.bonya.ai` when unset. |
| `--organization-id` | `BONYA_ORGANIZATION_ID` | Omit to use your personal organization; see [`bonya org`](https://docs.bonya.ai/cli-reference/org). |
| `--ca-bundle` | `BONYA_CA_BUNDLE` | Path to a PEM CA bundle, for private development CAs. |
| `--json` | — | Machine-readable JSON instead of tables. Never colored, never prompts. |
| `--no-color` | `NO_COLOR` | Plain text output. |
| `--no-input` | — | Never prompt; fail with a clear message when an argument is missing. |

`--ca-bundle`, `--endpoint`, and `--no-input` are fully functional but hidden from `bonya --help` output.

## Sandboxes are named by name *or* id

Every command that takes a sandbox accepts **either a name or an id, in the same argument** — you never have to say which one you meant:

```shell theme={null}
bonya console web                                    # by name
bonya console sbx-4f1c9a2b3c4d5e6f7a8b9c0d1e2f3a4b   # by id
```

### How resolution works

The CLI decides what an argument means with a fixed algorithm (`resolveSandboxRef`):

1. **Empty argument** — omit the sandbox entirely and it opens a picker over every sandbox in scope. If your account has none yet, it offers to create one.
2. **Id shape** — a value matching `^sbx-[0-9a-f]{32}$` (the literal `sbx-` prefix followed by 32 lowercase hex characters) is looked up directly as an id, with no list call.
3. **Name match** — anything else is looked up by exact, case-sensitive name:
   * **Exactly one match** — resolves straight to that sandbox.
   * **No match** — the CLI says so, then (interactively) falls back to a picker over every sandbox; non-interactively it fails with a message telling you to pass an id or run `bonya list`.
   * **Multiple matches** — names are not unique, so the CLI narrows the picker to just the matching sandboxes; non-interactively it fails and lists their ids so you can disambiguate.

> [!NOTE]
>
> Server-generated names never collide with the id shape by accident — ids are an internal, fixed 36-character format, so a name would have to be deliberately crafted to match it.

### `--by-name`

`--by-name` is a per-command flag (not persistent — it's not listed above) available on every command that takes a sandbox argument, except `create`, `list`, `login`, `logout`, `whoami`, `version`, and the `org` subcommands. It skips the id-shape check in step 2 above and forces the argument to be resolved as a name.

This exists for the one case the shape check can't cover on its own: a sandbox deliberately (or accidentally) named to look exactly like an id.

```shell theme={null}
bonya get sbx-4f1c9a2b3c4d5e6f7a8b9c0d1e2f3a4b --by-name
```

## Scripting

Every interactive behavior — pickers, confirmations, spinners — turns itself off automatically when there's nobody to interact with. See [Configuration](https://docs.bonya.ai/cli-reference/configuration.md) for the exact conditions and what happens instead of prompting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.