CLI Reference

Installation & updates

# Install (run once)
curl -fsSL https://box.ascii.dev/install | sh

# Check for and apply updates
box self-update

The CLI auto-checks for updates on each run. Suppress with --no-update.

Global flags

These flags work with any command:

Flag	Description
`--api-url <URL>`	Override the API endpoint (env: `BOX_API_URL`)
`--json`	Output machine-readable JSON instead of human text
`--no-update`	Skip the automatic update check

Authentication

`box onboard`

Full onboarding flow: opens GitHub OAuth, authenticates, and saves your token.

box onboard

box login
box login box_abc123...

Box lifecycle

`box new`

Create a new box.

box new [--ttl SECONDS]

Flag	Default	Maximum
`--ttl`	`3600` (1 hour)	`2592000` (30 days)

Returns the box ID, IP, and initial state.

`box list`

List all your boxes with their current state and ID.

box list

`box info <id>`

Get details for a specific box: state, IP, desktop availability, TTL remaining.

box info bx_f7k2q9hd

`box stop <id>`

Pause a running box. Creates a snapshot then stops billing. The box enters archiving → archived.

box stop bx_f7k2q9hd

Snapshotting takes a moment. The box is not yet stopped when the command returns — poll box info to confirm archived state.

`box resume <id>`

Resume a stopped box from its last snapshot.

box resume bx_f7k2q9hd

Requires the box to have a completed snapshot (i.e. it was stopped cleanly via box stop).

`box delete <id>`

Permanently delete a box and all its data.

box delete bx_f7k2q9hd

`box fork <id>`

Clone a box from its latest snapshot into a new independent box.

box fork bx_f7k2q9hd

Returns the new box ID asynchronously (HTTP 202). Requires the source box to have a completed snapshot.

Access

`box ssh <id>`

SSH into a box. Manages the key at ~/.ssh/ascii_box_ed25519 automatically.

box ssh bx_f7k2q9hd

`box scp`

Copy files to/from a box. Use bx_<id>:/path as the remote address.

# Download a file
box scp bx_f7k2q9hd:/home/user/output.zip ./output.zip

# Upload a file
box scp ./local-file.txt bx_f7k2q9hd:/home/user/

# Copy a directory recursively
box scp --recursive ./my-project bx_f7k2q9hd:/home/user/

Flag	Description
`--recursive`	Copy directories recursively

`box forward <id>`

Forward one or more ports from a box to your local machine.

box forward bx_f7k2q9hd --remote 8080
box forward bx_f7k2q9hd --remote 8080,5432 --local 8080,5433
box forward bx_f7k2q9hd --remote 3000 --bind 0.0.0.0

Flag	Default	Description
`--remote <ports>`	required	Comma-separated ports on the box
`--local <ports>`	same as remote	Local ports to bind
`--bind <addr>`	`127.0.0.1`	Local bind address

`box desktop <id>`

Open the box’s desktop streaming URL in your browser.

box desktop bx_f7k2q9hd

AI agents

`box prompt <id>`

Send a natural-language prompt to an AI agent running inside the box.

box prompt bx_f7k2q9hd --provider claude "Fix the failing tests in this repo"
box prompt bx_f7k2q9hd --provider codex --model o3 "Refactor auth module"

Flag	Required	Values
`--provider`	yes	`claude`, `codex`, `claude-code`
`--model`	no	Provider-specific model name

Account

`box limits`

Display your current usage, quota, and subscription status.

box limits

`box dashboard`

Open your web dashboard in the browser.

box dashboard

`box config`

Show the path to your local config file and its current contents.

box config

Config is stored at ~/.config/ascii/box/config.json.

​Installation & updates

​Global flags

​Authentication

​box onboard

​box login [key]

​Box lifecycle

​box new

​box list

​box info <id>

​box stop <id>

​box resume <id>

​box delete <id>

​box fork <id>

​Access

​box ssh <id>

​box scp

​box forward <id>

​box desktop <id>

​AI agents

​box prompt <id>

​Account

​box limits

​box dashboard

​box config

Installation & updates

Global flags

Authentication

`box onboard`

`box login [key]`

Box lifecycle

`box new`

`box list`

`box info <id>`

`box stop <id>`

`box resume <id>`

`box delete <id>`

`box fork <id>`

Access

`box ssh <id>`

`box scp`

`box forward <id>`

`box desktop <id>`

AI agents

`box prompt <id>`

Account

`box limits`

`box dashboard`

`box config`