> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ascii.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for all box CLI commands and global flags.

## Installation & updates

```bash theme={null}
# 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                    |

`--json` is enabled automatically whenever output is piped or redirected, so scripts get JSONL without passing the flag.

Wherever a command takes a box ID, two aliases also work: `current` (the last box created in this shell) and `self` (the box you are running inside, when using the CLI from within a box).

***

## Shell completion

`box completions <shell>` prints a completion script for bash, zsh, fish, or PowerShell. It completes subcommands and your live box IDs (plus `current` and `self`), with a 15 second cache so repeated tabs are instant.

```bash theme={null}
# bash: add to ~/.bashrc
eval "$(box completions bash)"

# zsh: add to ~/.zshrc, after compinit
eval "$(box completions zsh)"

# fish
box completions fish > ~/.config/fish/completions/box.fish

# PowerShell: add to $PROFILE
box completions powershell | Out-String | Invoke-Expression
```

***

## Authentication

### `box onboard`

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

```bash theme={null}
box onboard
```

### `box login [key]`

Sign in with an existing API token, or start a browser sign-in flow if no key is given. GitHub is the default; Google and email also work.

```bash theme={null}
box login
box login --google
box login --email you@example.com
box login box_abc123...
```

Create production API keys from the dashboard API Keys page. See [API Keys](/box/api-keys) for key management and [Use in Docker](/box/use-in-production) for Docker and hosted-worker setup.

### `box logout`

Sign out and clear the local token.

```bash theme={null}
box logout
```

### `box status`

Show API health, the signed-in account and plan, and the local config path.

```bash theme={null}
box status
```

***

## Box lifecycle

### `box new`

Create a new box.

```bash theme={null}
box new [--ttl SECONDS]
box new --no-auto-stop
box new --env KEY=VALUE --env OTHER=VALUE
box new --no-env
```

| Flag             | Default         | Maximum                   |
| ---------------- | --------------- | ------------------------- |
| `--ttl`          | `3600` (1 hour) | `2592000` (30 days)       |
| `--no-auto-stop` | off             | no automatic stop         |
| `--env`, `-e`    | none            | 100 variables, 64KB total |
| `--no-env`       | off             | none                      |

`--env` sets per-box environment variables on top of your dashboard secrets; per-box values win on name conflicts. See [Secrets & Setup](/box/secrets).

`--no-env` creates a box that receives none of the secrets attached to your account, and confines the box to itself so it can't act on your account or other boxes. Use it for boxes you give to your own users. SSH, SCP, desktop, snapshots, and public URLs still work. See [Secrets & Setup](/box/secrets).

Returns the box ID, IP, and initial state.

For a long uninterrupted workflow, disable auto-stop:

```bash theme={null}
box new --no-auto-stop
```

See [Long-Running Tasks](/box/long-running-tasks).

### `box list`

List all your boxes with their current state and ID.

```bash theme={null}
box list
```

### `box extend <id>`

Change the auto-stop timer for an existing Box.

```bash theme={null}
box extend bx_f7k2q9hd --hours 12
box extend bx_f7k2q9hd --ttl 2592000
box extend bx_f7k2q9hd --no-auto-stop
```

Use `--hours` or `--ttl` for a timed extension. Use `--no-auto-stop` when the Box should keep running until you stop it yourself.

### `box info <id>`

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

```bash theme={null}
box info bx_f7k2q9hd
```

### `box stop <id>`

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

```bash theme={null}
box stop bx_f7k2q9hd
```

<Note>Snapshotting takes a moment. The box is not yet stopped when the command returns; poll `box info` to confirm `archived` state.</Note>

### `box resume <id>`

Resume a stopped box from its last snapshot. The box is usable in a few seconds regardless of data size; remaining file content streams in the background. See [Snapshots](/box/snapshots).

```bash theme={null}
box resume bx_f7k2q9hd
box resume --no-env bx_f7k2q9hd
```

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

Use `--no-env` to resume a stopped box after dropping your account secrets and scrubbing owner secrets inherited from the snapshot. This is one-way: the box stays no-env afterward.

Resume behaves like a server reboot: systemd services you enabled start again automatically. Processes you ran by hand (dev servers, background jobs, tunnels, desktop sessions) do not survive; restart them, or make them a systemd service.

### `box delete <id>`

Permanently delete a box and all its data.

```bash theme={null}
box delete bx_f7k2q9hd
```

### `box fork <id>`

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

```bash theme={null}
box fork bx_f7k2q9hd
box fork --no-env bx_f7k2q9hd
```

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

Forking copies the snapshotted filesystem into a new Box; enabled systemd services start automatically, like on resume. Processes the source box ran by hand are not forked; start them again in the fork if needed.

Use `--no-env` to fork into a no-env box. A fork of a no-env source is always no-env.

### `box events <id>`

Read a Box's persisted lifecycle and agent chat events. Add `--follow` to keep polling for new events.

```bash theme={null}
box events bx_f7k2q9hd
box events bx_f7k2q9hd --follow
```

| Flag       | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `--follow` | Continue polling and printing new events until interrupted |

### `box interrupt <id>`

Interrupt the currently running agent work in a Box.

```bash theme={null}
box interrupt bx_f7k2q9hd
```

***

## Access

### `box ssh <id> [command]`

SSH into a box, or run a command non-interactively. Manages the key at `~/.ssh/ascii_box_ed25519` automatically.

```bash theme={null}
box ssh bx_f7k2q9hd
box ssh bx_f7k2q9hd "cd /home/user/my-repo && npm test"
box ssh bx_f7k2q9hd -- bash -lc "cd /home/user/my-repo && npm test"
box ssh bx_f7k2q9hd -- bash -s < ./setup.sh
```

### `box scp`

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

```bash theme={null}
# 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 TCP port from a box to your local machine.

```bash theme={null}
box forward bx_f7k2q9hd --remote 8080
box forward bx_f7k2q9hd --remote 3000 --bind 0.0.0.0
```

| Flag              | Default        | Description            |
| ----------------- | -------------- | ---------------------- |
| `--remote <port>` | required       | Remote port on the box |
| `--local <port>`  | same as remote | Local port to bind     |
| `--bind <addr>`   | `127.0.0.1`    | Local bind address     |

### `box desktop <id>`

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

```bash theme={null}
box desktop bx_f7k2q9hd
box desktop bx_f7k2q9hd --vnc
box desktop bx_f7k2q9hd --vnc --public
```

By default the desktop streams over Moonlight (60fps WebRTC). On restrictive or
low-bandwidth networks where WebRTC is choppy or won't connect, use `--vnc` for
a VNC stream that tunnels over plain HTTPS and is far more tolerant of poor
connections. The viewer also offers a one-click switch to VNC if the default
stream struggles.

| Flag       | Default | Description                                                         |
| ---------- | ------- | ------------------------------------------------------------------- |
| `--vnc`    | off     | Stream over VNC instead of Moonlight. More stable on poor networks. |
| `--public` | off     | With `--vnc`, return a URL that does not require an access token.   |

<Note>
  The first `--vnc` on a box takes a few seconds while it prepares the VNC
  stack (the CLI shows a spinner); subsequent opens are instant.
</Note>

***

## Snapshots

### `box snapshots [id]`

List snapshots across your boxes, or for one box.

```bash theme={null}
box snapshots
box snapshots bx_f7k2q9hd
```

### `box snapshot latest|tree|pull`

Inspect or download a snapshot. Works while the box is stopped.

```bash theme={null}
box snapshot latest bx_f7k2q9hd
box snapshot tree <snapshotId>              # files and sizes
box snapshot pull <snapshotId> -o ./restore # download and reassemble
```

`pull` writes `home_user/` (your `/home/user`) and `docker/` (named volumes). See [Snapshots](/box/snapshots).

***

## AI agents

### `box prompt <id>`

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

```bash theme={null}
box prompt bx_f7k2q9hd --provider claude "Fix the failing tests in this repo"
box prompt bx_f7k2q9hd --provider codex --model gpt-5.4-mini --reasoning-effort xhigh "Refactor auth module"
```

| Flag                 | Required | Values                                                                                   |
| -------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `--provider`         | yes      | `claude`, `codex`, `claude-code`                                                         |
| `--model`            | no       | Provider-specific model name                                                             |
| `--reasoning-effort` | no       | Provider/model-specific level such as `none`, `low`, `medium`, `high`, `xhigh`, or `max` |

Run `box prompt --help` to fetch the current provider, model, and reasoning-effort list from the Box API.

***

## Account

### `box limits`

Display your current usage, quota, and subscription status.

```bash theme={null}
box limits
```

### `box dashboard`

Open your web dashboard in the browser. The CLI passes your local Box token to the dashboard. If that token is a service API key, Box operations still work, but creating, rotating, or revoking API keys requires signing in through the browser flow.

```bash theme={null}
box dashboard
```

### `box config`

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

```bash theme={null}
box config
```

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