Capture pipeline

When you run profile upload, profile refresh, or profile inspect, the CLI executes this pipeline:

1. Copy — A filtered snapshot of your local browser profile (skipping caches, GPU data, and lock files) is written to a temp directory.
2. Launch — Your real browser binary is spawned headless against the temp copy with sync, telemetry, and Safe Browsing disabled so nothing mutates your live profile.
3. Extract — The CLI connects via CDP (Storage.getCookies + per-origin localStorage / IndexedDB) and captures all auth state.
4. Filter — Domain exclusions (persistent list + per-run --exclude-domain) and the private-domain filter are applied. Excluded data never leaves your machine.
5. Upload — The filtered payload is sent to the Browserless server.
6. Cleanup — The temp directory and headless process are torn down.

Windows: quit the browser before capturing

On Windows, Chromium-based browsers (Chrome, Edge, Brave and others) keep their cookie database locked while they run, including when they keep running in the background after the last window is closed. Quit the browser completely before you run profile upload, profile refresh, or profile inspect. On macOS and Linux the browser can stay open.

Prerequisites

• The Browserless CLI installed (npm install -g @browserless.io/cli)
• A Browserless API token from your account dashboard

Profile size limits

The server enforces these caps on the upload payload:

Limit	Value
Serialized artifact size	2 MB
Origins per capture	50
IndexedDB databases per origin	5
IndexedDB entries per store	1,000
Profile name length	255 characters
Profile name pattern	No whitespace, ?, or #

If your capture exceeds 2 MB, use --auto-fit to drop the heaviest origins until it fits, or --exclude-domain / --only-domain to narrow scope.

FAQ & Troubleshooting

The CLI command isn't recognized

Verify the CLI is installed globally with npm list -g @browserless.io/cli. If missing, run npm install -g @browserless.io/cli to install it.

How do I authenticate the CLI?

Run browserless auth and enter your API token when prompted. The token is stored locally for subsequent commands.

On Windows, the capture fails with "resource busy or locked" (EBUSY) or says the browser is still running

Windows keeps the browser's cookie database locked while the browser runs, so the CLI cannot copy your profile and exits with code 4. Quit the browser completely, then run the command again:

1. Use Exit from the browser menu, or right-click its icon in the taskbar notification area and choose Exit.
2. If it still fails, end any remaining browser processes (for example chrome.exe or msedge.exe) in Task Manager.
3. To stop the browser from staying open in the background, turn off Continue running background apps under Settings → System.

Next steps

CLI overview

all available CLI commands

Authentication

set up CLI credentials