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

# Installation

> System requirements, install steps, and configuration for the BrowserWire CLI.

## System requirements

| Requirement | Details                                          |
| ----------- | ------------------------------------------------ |
| **Node.js** | v22 or later                                     |
| **OS**      | macOS or Linux                                   |
| **Browser** | Chromium (installed automatically by Playwright) |

## Install the CLI

Install `@browserwire/cli` globally via npm:

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

This makes the `bw` command available in your terminal. The `postinstall` script automatically downloads Playwright and a bundled Chromium browser.

<Tip>You can also run commands without a global install using `npx @browserwire/cli <command>`.</Tip>

Verify the installation:

```bash theme={null}
bw --version
```

## Create an account and authenticate

BrowserWire requires an account for recording and training. Run:

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

This opens your default browser to the BrowserWire sign-in page at `app.browserwire.io`. If you don't have an account yet, click **Sign up** — you can register with email or an OAuth provider (Google, GitHub, etc.).

After you authenticate in the browser:

1. The browser shows **"Logged in successfully!"** — you can close the tab
2. Your terminal confirms: `Logged in as you@example.com`
3. A session token is saved to `~/.config/browserwire/config.json` (file permissions `0600`)

The token is valid for **30 days**. When it expires, `bw record` will automatically prompt you to re-authenticate before uploading — you won't lose your recording.

<Tip>If the browser doesn't open automatically, the CLI prints a URL you can copy and visit manually. The login flow has a 120-second timeout.</Tip>

### CI / automation

For headless environments where interactive login isn't possible, set the `BW_TOKEN` environment variable:

```bash theme={null}
export BW_TOKEN="your-session-token"
```

When `BW_TOKEN` is set, the CLI uses it directly and skips the config file.

## Configuration

The CLI reads configuration from these sources, in order of precedence:

| Source                    | Example                                    |
| ------------------------- | ------------------------------------------ |
| **Environment variables** | `BW_TOKEN`, `BW_API_URL`                   |
| **Config file**           | `~/.config/browserwire/config.json`        |
| **CLI flags**             | `--port`, `--headless`, `--max-concurrent` |

### Environment variables

| Variable     | Description                           | Default                      |
| ------------ | ------------------------------------- | ---------------------------- |
| `BW_TOKEN`   | Session token (overrides config file) | —                            |
| `BW_API_URL` | Backend API URL                       | `https://app.browserwire.io` |

### Config file

The config file is managed by `bw login` and stored at:

```
~/.config/browserwire/config.json
```

Or `$XDG_CONFIG_HOME/browserwire/config.json` if `XDG_CONFIG_HOME` is set.

```json theme={null}
{
  "sessionToken": "eyJhbGciOi..."
}
```

<Warning>The config file contains your session token. It is created with `0600` permissions (owner-only read/write). Do not commit it to version control.</Warning>

## Uninstall

```bash theme={null}
npm uninstall -g @browserwire/cli
rm -rf ~/.config/browserwire
```