Skip to main content
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.

​
Install

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:

Getting started

login, console, create

Sandboxes

list, get, delete, exec

Inside a sandbox

fs, session, preview, snapshot

Account

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 for the exact precedence rules and config file location. --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:

​
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.
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.

​
Scripting

Every interactive behavior — pickers, confirmations, spinners — turns itself off automatically when there’s nobody to interact with. See Configuration for the exact conditions and what happens instead of prompting.