Skip to main content

​
Install the CLI

npm install -g @brightdata/cli
Verify the installation: 
brightdata --version
The shorthand alias bdata is also available after installation - use whichever you prefer.

​
Authenticate

Run the login command to connect your Bright Data account: 
brightdata login
This opens your browser for secure OAuth authentication. Once complete, the CLI:
  1. Validates and stores your API key locally
  2. Auto-creates required proxy zones (cli_unlocker, cli_browser)
  3. Sets sensible defaults so you can start immediately
You only need to log in once. All subsequent commands authenticate automatically.

​
Alternative authentication methods

When no browser is available, use the device flow:
brightdata login --device
This prints a URL and a code. Open the URL on any device, enter the code, and the CLI completes authentication.
For CI/CD pipelines or non-interactive environments, pass your API key directly:
brightdata login --api-key YOUR_API_KEY
You can find your API key in the Bright Data control panel.
Set the BRIGHTDATA_API_KEY environment variable to skip login entirely:
export BRIGHTDATA_API_KEY=YOUR_API_KEY
This is useful for Docker containers, GitHub Actions, and other automated environments.

​
Interactive setup wizard

For a guided first-time experience, use the init command: 
brightdata init
This walks you through authentication, zone selection, and default configuration step by step.
FlagDescription
--skip-authSkip the authentication step (if already logged in)
-k, --api-key <key>Provide API key directly

​
Verify your setup

After logging in, confirm everything is working: 
# Check your configuration
brightdata config

# Verify API connectivity
brightdata budget

# Try a quick scrape
brightdata scrape https://example.com

​
Configuration storage

The CLI stores credentials and configuration locally:
OSPath
macOS~/Library/Application Support/brightdata-cli/
Linux~/.config/brightdata-cli/
Windows%APPDATA%\brightdata-cli\
Two files are created:
FilePurposePermissions
credentials.jsonAPI key0o600 (owner-only)
config.jsonZones, output format, preferencesStandard
Priority order for configuration: CLI flags → Environment variables → config.json → Defaults. You can always override any setting on a per-command basis.

​
Next steps

Commands

Explore the full command reference.

Usage Examples

Jump into real-world workflows and recipes.