Borealis Docs

Borealis CLI

The CLI is a Node.js client for the same versioned public API used by integrations.

Install and sign in

Node.js 22 or newer is required:

npm install --global @amaretto-software-labs/borealis-cli
borealis auth login
borealis auth whoami

For a one-off invocation, use npx @amaretto-software-labs/borealis-cli --help. Source code and release instructions are in the official CLI repository.

Interactive sign-in opens a browser. Keep the CLI running until it confirms that credentials have been stored. Sessions use the platform credential store.

Inspect context first

borealis context show --json
borealis sandbox list --page 1 --page-size 50 --json

Use --profile NAME to separate saved sessions and --organization ORGANISATION_ID to select an organisation you can access. Confirm context before mutations.

Form a command

Path identifiers are positional. Request values can be supplied as JSON:

borealis sandbox create --body '{"name":"demo","image":"ubuntu:24.04","command":"sleep","args":["infinity"]}'

Run borealis --help for command groups and use a command’s --help for its arguments. The first sandbox guide walks through the complete lifecycle.

Automate carefully

Use --json for structured output. Supply an automation token through BOREALIS_ACCESS_TOKEN or --token-file; avoid putting credentials directly in command arguments.

Keyed operations generate an idempotency key and accept an explicit --idempotency-key. Preserve the key when retrying an uncertain mutation. Destructive operations require confirmation; scripts should enable unattended confirmation only after independently checking their target and intended effect.

See authentication for permissions and API reliability for retry behaviour.