CLI Command Reference (canonical tree)

Every action has one canonical path, written abx GROUP VERB. On top of that there is a small, fixed set of top-level shortcuts for the commands people type most. The set is hard-coded: it cannot be extended, renamed or removed through configuration, and there is no per-user alias table.

Top-level commands, exactly these: abx sandbox, abx template, abx config, abx mcp, abx provider, abx create, abx list, abx info, abx kill, abx exec, abx connect, abx upload, abx download, abx run, abx deploy.

abx --help lists them in three sections: Command groups (sandbox, template, config, mcp), Providers (provider) and Sandbox shortcuts (the ten shortcuts, each documented as "Same as 'abx …'"). A test fails when that list and this page disagree.

Shortcuts

There is no top-level abx init or abx install: use abx template init and abx template install (credentials are abx config init).

Canonical tree

abx
├── sandbox
│   ├── create [DESCRIPTION]            list            info SANDBOX_ID        kill [SANDBOX_ID]
│   ├── exec SANDBOX_ID COMMAND...      connect SANDBOX_ID
│   ├── upload SANDBOX_ID LOCAL REMOTE  download SANDBOX_ID REMOTE LOCAL
│   ├── capabilities SANDBOX_ID
│   ├── files    list | mkdir | mv | rm | search | stat
│   ├── process  list | info | signal            (inspect / control only; start a process with exec --background)
│   ├── command  list | run                      (named commands registered on the in-sandbox server)
│   └── system   env | info | metrics | packages | ports
├── template     init | search | info | list | build | push | create | delete | deploy | install
├── config       init | get | set | list | delete
├── mcp          deploy | install | start | status | stop
└── provider     list | show | info | install | uninstall | update | default | config | doctor | test

abx provider --help is owned by the provider documentation (Providers); only the group is part of the fixed surface described here.

Usage lines (from abx … --help):

Global options

-j/--json, -q/--quiet, -v/--verbose, --no-color, --log-level [debug|info|warning|error], --ci, --version, -h/--help. They go before the command (abx --json list).

There is no global --timeout and no --profile. A sandbox lifetime is --timeout SECONDS on abx create only; a command timeout is --timeout SECONDS on abx exec.

Running commands: abx exec

abx exec SANDBOX_ID -- python --version                 # wait, exit with the remote exit code
abx exec SANDBOX_ID --cwd /app --env DEBUG=1 --timeout 300 -- pytest -q
abx exec SANDBOX_ID --stream -- pip install numpy        # stdout/stderr live
abx exec SANDBOX_ID --background -- python -m http.server 8000   # print the pid, return at once
abx exec SANDBOX_ID "ls /app | wc -l"                    # one quoted argument is a command line (pipes work)

The command after -- is run exactly as given, without a shell; a single quoted argument is read as a command line and gets a shell only when it contains pipes or redirects. Use sh -c '...' for variable expansion. Inspect or signal a background process with abx sandbox process list|info|signal.

abx connect SANDBOX_ID opens a line-by-line REPL. Every line is a new process (state such as cd or exported variables does not persist); it is not a PTY.

Named commands: abx run / abx sandbox command

There is exactly one mechanism: commands registered on the in-sandbox server (CommandRegistry, GET /commands, POST /commands/{name}). They are not declared in template.yaml.

abx sandbox command list SANDBOX_ID                                  # name, arguments, description
abx run SANDBOX_ID build --arg target=staging --arg n=2              # same as: abx sandbox command run
abx run SANDBOX_ID add --json-args '{"x": 1, "y": 2}'                # typed values

A string result is printed as is, any other value as JSON (--json wraps it as {"result": ...}). A command that fails on the server exits 1; an unknown name exits 2; a sandbox without a running server reports "No SandboxServer reachable" and exits non-zero.

Setup: abx config init

abx config init asks for the credentials and the region only. Two flags add sections:

Features that need a missing setting print a one-line pointer to abx config init --build or abx config init --llm. Without a terminal (or with --yes/--ci) the command prints the equivalent abx config set … lines instead of prompting.

Removed spellings