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

# CLI Reference

> All commands and flags for the bw command-line tool.

## Installation

```bash theme={null}
npm install -g @browserwire/cli
```

The CLI is available as the `bw` command. Requires **Node.js 22+** on **macOS or Linux**.

***

## `bw login`

Authenticate with BrowserWire via your browser.

```bash theme={null}
bw login
```

Opens your default browser to the BrowserWire sign-in page. After authentication, a session token is saved to `~/.config/browserwire/config.json` with `0600` permissions. The token is valid for 30 days.

If the browser doesn't open automatically, the CLI prints a URL you can visit manually.

**Timeout:** 120 seconds. If authentication isn't completed in time, the command exits with an error.

***

## `bw record <url>`

Open a browser, navigate to a URL, and record a session.

```bash theme={null}
bw record https://example.com
```

### How it works

1. Launches a Chrome browser and navigates to the URL
2. You browse freely — recording hasn't started yet
3. Press **Enter** to start recording (page reloads for a clean snapshot)
4. Interact with the site — every DOM mutation, click, keystroke, and navigation is captured
5. Press **Enter** to stop recording
6. Events are uploaded and a training run is triggered automatically
7. The dashboard opens in your browser to the recording detail page

### Terminal output

```
Launching browser for https://example.com...

Navigate the site freely.
Press Enter to START recording, then Enter again to STOP.

Reloading page for clean snapshot...
Recording started. Navigate the site, then press Enter to stop.

Captured 847 events.
Uploading recording...
Upload complete.
Starting training...
Opening dashboard: https://app.browserwire.io/dashboard/recordings/abc123
```

### Authentication

If your session token is missing or expired, the CLI prompts you to log in before uploading. You won't lose your recording — the auth flow runs after the session is captured.

### New tabs

Links that would open in a new tab are redirected into the current page so the recording stays continuous.

***

## `bw run`

Start a local execution server that serves your discovered APIs.

```bash theme={null}
bw run [options]
```

### Flags

| Flag                        | Description                                            | Default          |
| --------------------------- | ------------------------------------------------------ | ---------------- |
| `-p, --port <number>`       | Port to listen on                                      | `8787`           |
| `--headless`                | Run the browser in headless mode (no visible window)   | `false` (headed) |
| `--max-concurrent <number>` | Maximum concurrent browser pages for parallel requests | `3`              |

### What it does

1. Verifies you're logged in (exits with error if not)
2. Fetches all your manifests from the BrowserWire API
3. Launches a persistent Chrome browser (headed by default)
4. Starts an HTTP server on `127.0.0.1:<port>`

### Endpoints served

| Method | Endpoint                                  | Description               |
| ------ | ----------------------------------------- | ------------------------- |
| `GET`  | `/api/health`                             | Health check              |
| `GET`  | `/api/sites`                              | List all cached manifests |
| `GET`  | `/api/sites/:slug/manifest`               | Full manifest JSON        |
| `GET`  | `/api/sites/:slug/views/:state/:view`     | Execute a view            |
| `POST` | `/api/sites/:slug/actions/:state/:action` | Execute an action         |

### Examples

Start with defaults (port 8787, headed, 3 concurrent):

```bash theme={null}
bw run
```

Start on a different port in headless mode:

```bash theme={null}
bw run --port 3000 --headless
```

Allow more concurrent executions:

```bash theme={null}
bw run --max-concurrent 5
```

### Concurrency

Each API request opens a new browser page. If the maximum concurrent limit is reached, additional requests receive a `429 Too Many Requests` response. Increase `--max-concurrent` if you need more parallelism.

### Graceful shutdown

Press **Ctrl+C** to stop the server. The browser is closed and the process exits cleanly.

***

## `bw --version`

Print the CLI version.

***

## `bw --help`

Show usage information for all commands.

***

## Environment variables

| Variable     | Description                                          | Default                      |
| ------------ | ---------------------------------------------------- | ---------------------------- |
| `BW_TOKEN`   | Session token (overrides config file, useful for CI) | —                            |
| `BW_API_URL` | BrowserWire backend URL                              | `https://app.browserwire.io` |