CLI

cubicle manages Boxes, access, SSH and the private network from your computer: set it up with Install the CLI, then sign in with cubicle login.

cubicle <command> [options]

CommandsCopy Anchor Link

box is an alias for boxes: cubicle box list works too.

Global optionsCopy Anchor Link

--api URL belongs to cubicle login only; see cubicle login.

• Put options anywhere before --. After --, everything goes to the command in the Box (exec) or to ssh (ssh). Other commands ignore it.
• A command ignores options it does not use, such as --wait on boxes list.
• An option the CLI does not know is an error. The message contains Unknown option '--<name>', and the command exits 1.
• cubicle with no command, and cubicle --help, print the usage and exit 2. cubicle <command> --help prints the same usage and exits 0.

JSON outputCopy Anchor Link

With --json, a command prints its result on stdout as JSON with 2-space indentation. For most commands that is the API's response.

• boxes get, connect, disconnect, status and devices list always print JSON.
• keys rm, sessions revoke, members rm, grants add, grants rm, service-accounts rm, api-keys revoke and devices revoke print nothing when they succeed, with or without --json.
• login, logout, tunnel install, tunnel uninstall and ssh ignore --json.
• Errors are always plain text on stderr, also with --json. Check the exit code.

Box argumentsCopy Anchor Link

Commands that take BOX accept one of these:

The CLI does not accept a bare name such as job-1, although the HTTP API does.

• A bare name fails with BOX must be a box ID or ORG/NAME.
• A missing argument fails with missing BOX argument.
• For ORG/NAME, the CLI looks the name up in the organization's list of Boxes. If none matches, it fails with no box acme/job-1.
• That list includes a deleted Box until its Node has removed it. Right after you delete acme/job-1 and create a new one with the same name, acme/job-1 can still refer to the deleted Box, and commands fail with not_found: box not found. Use the new Box's ID until the old one has left cubicle boxes list.

ErrorsCopy Anchor Link

Errors go to stderr, and the command exits 1, or 2 for an unknown command.

Each API request times out after 30 s. The CLI does not retry a request that fails, also not a 429 rate_limited one: the command exits 1. Troubleshooting has fixes for common errors and points to the guide that fixes each feature's own errors, and Errors lists the API's error codes.

Exit codesCopy Anchor Link

Environment variablesCopy Anchor Link

CB_CLI_CREDENTIAL_STORE takes effect when you log in. The login records which store holds its token, and later commands read it from there. Any other value means automatic.

Files the CLI writesCopy Anchor Link

logout removes login.json, credentials.json and the token from the Keychain or Secret Service. Install the CLI lists what the installer writes.

API-key modeCopy Anchor Link

Set CB_CLI_API_KEY to a service account API key and CB_CLI_API_URL to the API. Every command then authenticates with the key and never uses your stored login. Use this in CI and other unattended jobs.

export CB_CLI_API_URL=https://api.cubicle.sh
export CB_CLI_API_KEY=cbk_…
cubicle whoami                  # acme/ci (acme:member)
cubicle boxes create --org acme job-1 --wait
cubicle exec acme/job-1 -- sh -c 'echo hello'
cubicle boxes delete acme/job-1

Without CB_CLI_API_URL, every command that would use your login fails with CB_CLI_API_KEY requires CB_CLI_API_URL.

• These commands work with a key: whoami, boxes list, boxes bases, boxes create, boxes get, boxes start, boxes stop, boxes delete, exec, snapshot, snapshots and restore.
• These fail with api_key_not_allowed: API keys cannot use this route: keys, sessions, members, grants, service-accounts, api-keys, connect, devices, ssh-config and ssh. Without the tunnel installed, connect and ssh fail first with "the Cubicle tunnel is not installed".
• With a read key, only whoami, boxes list, boxes bases, boxes get and snapshots work. The commands that change something fail with insufficient_scope: this API key is read-only.
• A key sees only its own organization. Other organizations' Boxes fail with not_found. boxes list without --org lists the key's organization.
• exec needs a grant on the Box. A service account gets one on every Box it creates.
• version, tunnel status, status and disconnect do not call the API. logout still removes a stored login if there is one.

Create a service account and a key shows how to get a key.