Authentication

Connect the CLI to your Browserless account by storing your API token locally.

The token is stored in your OS keychain (macOS Keychain, libsecret on Linux, DPAPI on Windows) and falls back to a mode-0600 file at ~/.browserless/config.json.

Command: browserless auth <subcommand>

Prerequisites

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

Subcommands

• login [token] Store your API token. Accepts a positional argument or stdin (echo $TOKEN | browserless auth login). Omitting the argument and piping from stdin keeps the token out of your shell history.
• status Print the current identity and where the token is stored.
• logout Wipe credentials from both keychain and config file.

Examples

Log in with a token

browserless auth login bless_abc123def456

Check auth status

browserless auth status

Authenticated
  Token stored in: keychain
  Server: https://production-sfo.browserless.io

Token resolution

When a command needs authentication, the CLI checks these sources in order:

1. --token flag
2. BROWSERLESS_TOKEN environment variable
3. OS keychain (keyed by server URL, so credentials for multiple regions coexist)
4. ~/.browserless/config.json (mode 0600 fallback)

If none resolve, the command exits with code 3.

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.

Next steps

CLI overview

all available CLI commands

Authentication

set up CLI credentials