Skip to main content

​
Installation

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. 
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. 
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. 
bw run [options]

​
Flags

FlagDescriptionDefault
-p, --port <number>Port to listen on8787
--headlessRun the browser in headless mode (no visible window)false (headed)
--max-concurrent <number>Maximum concurrent browser pages for parallel requests3

​
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

MethodEndpointDescription
GET/api/healthHealth check
GET/api/sitesList all cached manifests
GET/api/sites/:slug/manifestFull manifest JSON
GET/api/sites/:slug/views/:state/:viewExecute a view
POST/api/sites/:slug/actions/:state/:actionExecute an action

​
Examples

Start with defaults (port 8787, headed, 3 concurrent): 
bw run
Start on a different port in headless mode: 
bw run --port 3000 --headless
Allow more concurrent executions: 
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

VariableDescriptionDefault
BW_TOKENSession token (overrides config file, useful for CI)—
BW_API_URLBrowserWire backend URLhttps://app.browserwire.io