> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariana.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                    |

***

## 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 the browser OAuth flow if no key is given.

```bash theme={null}
box login
box login box_abc123...
```

***

## Box lifecycle

### `box new`

Create a new box.

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

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

### `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.

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

```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
```

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.

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

### `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 or more ports from a box to your local machine.

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

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

***

## 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 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.

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

### `box dashboard`

Open your web dashboard in the browser.

```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`.