Skip to main content

​
Install the CLI

The fastest way to run the Bright Data CLI is npx, which executes the latest version with no global install: 
npx -p @brightdata/cli brightdata --version
Prefix any command in these docs with npx -p @brightdata/cli to run it the same way, with no global dependency to maintain. The Bright Data CLI requires Node.js 20 or later. For a persistent brightdata command and faster startup, install the CLI globally instead: 
npm install -g @brightdata/cli
Verify a global install: 
brightdata --version
The shorthand alias bdata is also available, both with npx -p @brightdata/cli bdata and after a global install - use whichever you prefer.

​
Update the CLI

Upgrade to the latest version with the same package manager you installed with: 
npm install -g @brightdata/cli@latest
Check your installed version against the latest published version: 
brightdata --version           # your installed version
npm view @brightdata/cli version   # latest version on npm
New commands ship in CLI releases. For example, scraper heal and scraper approve were added in v0.3.1. Run the update command above to pick them up. See the release notes for what changed in each version.

​
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

​
Where configuration is stored

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.