Configuration

config

Manage CLI settings. The configuration is stored in ~/.browserless/config.json (mode 0600, created on first use).

Command: browserless config <subcommand>

Subcommands

• get <key> Read a config value. Sensitive keys are redacted by default; pass --show-sensitive to print verbatim.
• set <key> <value> Write a user-managed config value.
• unset <key> Remove a user-managed config value.

Configurable keys

Key	Description
server	Target server URL (mutually exclusive with region).
region	Production region shorthand: sfo, lon, or ams.
terms_ttl_days	Days between liability disclaimer re-prompts (default 7).
telemetry	true or false (default on).
excluded_domains	Managed via profile exclude add/rm/list.

Examples

Set a region

browserless config set region sfo

Point to a self-hosted server

browserless config set server https://my-browserless.example.com

Disable telemetry

browserless config set telemetry false

Read a config value

browserless config get region

Global flags

Every command that hits the Browserless API accepts these flags.

Command: browserless {command} [global flags]

Flags

• --token <token> Override token resolution (flag > env > keychain > config file).
• --server <url> Override the configured server URL.
• --region <code> sfo / lon / ams shorthand for --server. Passing both --server and --region is an error.
• --json Emit the server response as JSON (script-friendly).

Environment variables

Variable	Effect
BROWSERLESS_TOKEN	Use this token without a stored credential (overrides keychain + file).
BROWSERLESS_ACCEPT_TERMS	1 to pre-accept the liability disclaimer.
BROWSERLESS_CONFIG_DIR	Override ~/.browserless/ location (useful for CI or multi-tenant setups).
BROWSERLESS_DISABLE_KEYCHAIN	1 to force plaintext config-file storage even if the keychain works.
BROWSERLESS_CDP_WAIT_MS	Override the 15 s CDP-readiness timeout (raise on slow CI runners).
BROWSERLESS_TELEMETRY_DISABLED	1 to disable usage analytics for the run.
DO_NOT_TRACK	1 also disables usage analytics (cross-tool standard).
CI	When set, the disclaimer refuses to prompt interactively. Use --accept-terms instead.

Exit codes

Code	Meaning
0	Success
1	Internal bug (prints a stack trace)
2	Bad arguments (UsageError)
3	Precondition failed: no token, disclaimer declined, profile busy, corrupt config (PreconditionError)
4	Local capture pipeline failed: copy / browser launch / CDP (CaptureError)
5	Server returned a non-2xx response (ApiError)

Usage analytics

The CLI reports lightweight, pseudonymous usage data so the team knows which commands to invest in. It's on by default and easy to turn off.

What is sent (once per command, only when authenticated against a Browserless cloud region):

• The command that ran (e.g. profile upload) and the names of flags you passed (never their values).
• Outcome: ok / error, exit code, and error class on failure.
• Duration, CLI version, OS/architecture/Node major, whether it's running under CI.
• The production region (sfo / lon / ams). Never a raw server URL.
• A random per-install device ID stored in the Browserless config directory (default: ~/.browserless/telemetry-device-id).

Never sent: your API token, profile names, captured URLs or domains, cookies, or any captured auth state. Commands targeting self-hosted servers aren't tracked at all.

Opt out:

browserless config set telemetry false

Or per-run via environment variable:

BROWSERLESS_TELEMETRY_DISABLED=1 browserless profile upload ...
DO_NOT_TRACK=1 browserless profile upload ...