CLI command reference

The executable is bxc. The compatibility alias bcompute accepts the same commands.

bxc [--json] COMMAND [OPTIONS]

Global options

Authentication and maintenance

bxc login

Start browser device authorization. bxc auth and bxc auth login are equivalent.

The CLI supports native browser launchers on macOS, Linux, Windows, and WSL. Failure to launch a browser does not stop authorization; open the printed URL manually.

bxc logout

Revoke the saved credential through Sandbox API v2, then remove the local credential and configuration files. bxc auth logout is equivalent. Logout requires a working connection so that access is revoked server-side.

bxc doctor

Verify authentication by listing Sandboxes. Human output shows the connected origin and number of Sandboxes. JSON output has this shape:

{"connected":true,"url":"https://app.boxcompute.ai","sandboxes":2}

bxc update

Read the latest package version from npm and, when it is newer, run a global install of that exact version. bxc up is equivalent. This command does not require BoxCompute authentication.

bxc version

Print the installed version and exit. bxc --version is equivalent.

Discover resources

bxc workspaces

List workspaces owned by the authenticated account:

WORKSPACE_ID<TAB>NAME

Use a workspace ID with bxc sandbox start. In JSON mode, the result is { "workspaces": [...] }.

bxc sandboxes

List owned Sandbox instances:

SANDBOX_ID<TAB>STATE<TAB>NAME

bxc list and bxc ls are aliases. In JSON mode, the result is { "sandboxes": [...] }. A Sandbox state is cold, pending, running, or expired. New VM creation can remain pending while provisioning.

Credit, wallet history, and usage

CLI 0.10.0 adds the following account-owned reads. They require usage:read, remain available at zero credit, and never start or resume compute. See credit and wallet history for monetary units, null estimates, and the difference between wallet deductions and observed AI costs.

bxc credits
bxc --json billing transactions --bucket promo --limit 20
bxc usage --days 7
bxc costs --from 2026-10-01T00:00:00Z --to 2026-10-11T00:00:00Z

Transactions return one newest-first page. Pass its nextCursor as --before with the same filters to continue; null means the end. JSON preserves signed integer micro-USD amounts.

Manage Sandboxes

bxc sandbox start WORKSPACE_ID

Create and start another Sandbox under a workspace. It returns the new Sandbox ID, state, and name. Each successful call can create a distinct instance, so save the returned ID and inspect the list before retrying after an uncertain network failure.

The start command accepts --idempotency-key KEY (required with --vm; reusable for any create) and --name NAME. It creates a VM Sandbox by default; use --size small or --size large and --no-wait to return the creation receipt without waiting for a pending VM to reach running. Legacy --gvisor and --cpu options request new gVisor creation, which the hosted API rejects with 400 INVALID_REQUEST. It does not expose the VM browser-preview, operator-selected cooperative-SSH, or selected-TCP service-access routes.

bxc sandbox resume SANDBOX_ID

Start the same existing stopped VM with its retained disk and files; compute billing resumes. Optional --idempotency-key KEY recovers the same request, and --no-wait returns a pending receipt without polling. This calls the existing-slot start route with {} rather than creating a new Sandbox. An uncertain response is not automatically retried: inspect status before deciding what to do. An unavailable legacy gVisor runtime cannot be recreated through resume.

bxc sandbox status SANDBOX_ID

Inspect one Sandbox without executing a command. JSON mode returns { "sandbox": {...} }.

bxc sandbox exec SANDBOX_ID -- PROGRAM [ARG...]

Execute a structured argument vector inside a Sandbox:

bxc sandbox exec SANDBOX_ID \
  --cwd /workspace/project \
  --env NODE_ENV=test \
  --env CI=true \
  --timeout 300 \
  --max-output-bytes 1048576 \
  -- npm test -- --runInBand

In human mode, remote standard output stays on local standard output. Remote standard error and an execution summary are written to local standard error. The CLI exits with the remote exitCode, or 1 when no exit code is available. A non-zero exit therefore reports command failure even though the API request itself succeeded.

In JSON mode, standard output contains:

{
  "sandboxId": "sbx_REDACTED",
  "stdout": "tests passed\n",
  "stderr": "",
  "exitCode": 0,
  "timedOut": false,
  "stdoutTruncated": false,
  "stderrTruncated": false,
  "wallTimeSeconds": 4.2
}

bxc sandbox logs SANDBOX_ID

Read current or retained logs without starting stopped compute:

bxc sandbox logs SANDBOX_ID \
  --since 2026-09-06T00:00:00Z \
  --until 2026-09-07T00:00:00Z \
  --stream stderr \
  --source execute \
  --limit 100

Human output is one tab-separated entry per line, followed by a summary on standard error. JSON output is { "logs": {...} } and preserves the structured entries, retention window, and truncation marker. See Read Sandbox logs for source semantics and retention behavior.

bxc sandbox delete SANDBOX_ID --yes

Destroy the Sandbox runtime and customer-facing instance. bxc sandbox rm is an alias. The explicit --yes confirmation is required. Deletion leaves the parent workspace intact and cannot be undone through the CLI.

Manage coding-agent skills

Skill management does not require BoxCompute authentication.

bxc skill detect

Check known configuration directories and executable names for compatible coding agents. Detection does not recursively search your home directory. The command reports detected harnesses and the destination for each skill.

bxc skill list

List harnesses that are detected or already have the BoxCompute skill installed. bxc skill ls is an alias.

bxc skill install [TARGET...]

Install a managed copy of the packaged boxcompute-sandbox skill. With no target, auto installs to every detected harness.

bxc skill install
bxc skill install codex claude
bxc skill install both
bxc skill install all

Targets are claude, codex, amp, opencode, cursor, gemini, copilot, cline, roo, goose, pi, windsurf, and agents. both expands to Claude Code and Codex. all installs every supported destination even when the harness is not detected. bxc skill add is an alias.

The command will not replace an unrelated or locally modified directory. Pass --force only when you intend to overwrite that copy:

bxc skill install codex --force

bxc skill remove [TARGET...] --yes

Remove CLI-managed skill copies. With no target, auto selects detected or installed harnesses. Explicit confirmation is required.

bxc skill remove codex claude --yes
bxc skill remove all --yes

The command protects a locally modified copy. Add --force only when you intend to delete those modifications. bxc skill rm and bxc skill uninstall are aliases.

bxc skill info

Print the packaged SKILL.md to standard output. bxc skill print is an alias. This is useful for auditing the exact instructions before installation.

Managed skill updates

The CLI records a digest beside each installed skill. A global CLI update refreshes an untouched managed copy during package installation. If package lifecycle scripts were disabled, the next ordinary bxc command performs the same check.

Locally modified copies are never overwritten automatically. The CLI reports their paths and leaves replacement behind the explicit bxc skill install --force command. Start a new agent session after an update so the harness loads the current instructions.

Exit statuses

Error messages are written to standard error. API failures include their HTTP status.