Capture pipeline
When you run profile upload, profile refresh, or profile inspect, the CLI executes this pipeline:
- Copy — A filtered snapshot of your local browser profile (skipping caches, GPU data, and lock files) is written to a temp directory.
- 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.
- Extract — The CLI connects via CDP (
Storage.getCookies+ per-originlocalStorage/IndexedDB) and captures all auth state. - Filter — Domain exclusions (persistent list + per-run
--exclude-domain) and the private-domain filter are applied. Excluded data never leaves your machine. - Upload — The filtered payload is sent to the Browserless server.
- Cleanup — The temp directory and headless process are torn down.
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.