Brightdata Cli

Bright Data CLI

The Bright Data CLI (brightdata or bdata) gives you full access to Bright Data's web data platform from the terminal. It handles authentication, proxy zones, anti-bot bypass, CAPTCHA solving, and JavaScript rendering automatically — the user just needs to log in once.

Installation

If the CLI is not installed yet, guide the user:

macOS / Linux:

curl -fsSL https://cli.brightdata.com/install.sh | bash

Windows or manual install (any platform):

npm install -g @brightdata/cli

Without installing (one-off usage):

npx --yes --package @brightdata/cli brightdata <command>

Requires Node.js >= 20. After install, both brightdata and bdata (shorthand) are available.

First-Time Setup

Before anything else, check if the user is authenticated. If they haven't logged in yet, guide them through the one-time setup:

# One-time login — opens the browser for OAuth, then everything is automatic
bdata login

This single command: 1. Opens the browser for secure OAuth authentication 2. Saves the API key locally (never needs to be entered again) 3. Auto-creates required proxy zones (cli_unlocker, cli_browser) 4. Sets default configuration

After login, every subsequent command works without any manual intervention.

For headless/SSH environments where no browser is available:

bdata login --device

For direct API key authentication (non-interactive):

bdata login --api-key <key>

To verify setup is complete, run:

bdata config

Command Reference

Read references/commands.md for the full command reference with all flags, options, and examples for every command.

Read references/pipelines.md for the complete list of 40+ pipeline types (Amazon, LinkedIn, Instagram, TikTok, YouTube, Reddit, and more) with their specific parameters.

Quick Command Overview

bdata is the shorthand for brightdata. Both work identically.

How to Use Each Command

Scraping

Scrape any URL with automatic bot bypass, CAPTCHA handling, and JS rendering:

# Default: returns clean markdown
bdata scrape https://example.com

# Get raw HTML
bdata scrape https://example.com -f html

# Get structured JSON
bdata scrape https://example.com -f json

# Take a screenshot
bdata scrape https://example.com -f screenshot -o page.png

# Geo-targeted scrape from the US
bdata scrape https://amazon.com --country us

# Save to file
bdata scrape https://example.com -o page.md

# Async mode for heavy pages
bdata scrape https://example.com --async

Searching

Search engines with structured JSON output (Google returns parsed organic results, ads, People Also Ask, and related searches):

# Google search with formatted table
bdata search "web scraping best practices"

# Get raw JSON for piping
bdata search "typescript tutorials" --json

# Search Bing
bdata search "bright data pricing" --engine bing

# Localized search
bdata search "restaurants berlin" --country de --language de

# News search
bdata search "AI regulation" --type news

# Extract just URLs
bdata search "open source tools" --json | jq -r '.organic[].link'

Pipelines (Structured Data Extraction)

Extract structured data from 40+ platforms. These trigger async jobs that poll until results are ready:

# LinkedIn profile
bdata pipelines linkedin_person_profile "https://linkedin.com/in/username"

# Amazon product
bdata pipelines amazon_product "https://amazon.com/dp/B09V3KXJPB"

# Instagram profile
bdata pipelines instagram_profiles "https://instagram.com/username"

# Amazon search
bdata pipelines amazon_product_search "laptop" "https://amazon.com"

# YouTube comments (top 50)
bdata pipelines youtube_comments "https://youtube.com/watch?v=..." 50

# Google Maps reviews (last 7 days)
bdata pipelines google_maps_reviews "https://maps.google.com/..." 7

# Output as CSV
bdata pipelines amazon_product "https://amazon.com/dp/..." --format csv -o product.csv

# List all available pipeline types
bdata pipelines list

Checking Status

For async jobs (from --async scrapes or pipelines):

# Quick status check
bdata status <job-id>

# Wait until complete
bdata status <job-id> --wait

# With custom timeout
bdata status <job-id> --wait --timeout 300

Budget & Zones

# Quick account balance
bdata budget

# Detailed balance with pending charges
bdata budget balance

# All zones cost/bandwidth
bdata budget zones

# Specific zone costs
bdata budget zone my_zone

# Date range filter
bdata budget zones --from 2024-01-01T00:00:00 --to 2024-02-01T00:00:00

# List all zones
bdata zones

# Zone details
bdata zones info cli_unlocker

Configuration

# View all config
bdata config

# Set defaults
bdata config set default_zone_unlocker my_zone
bdata config set default_format json

Installing AI Agent Skills

# Interactive picker — choose skills and target agents
bdata skill add

# Install a specific skill
bdata skill add scrape

# List available skills
bdata skill list

Output Modes

Every command supports multiple output formats:

When piped (stdout is not a TTY), colors and spinners are automatically disabled.

Chaining Commands

The CLI is pipe-friendly:

# Search → extract first URL → scrape it
bdata search "top open source projects" --json \
  | jq -r '.organic[0].link' \
  | xargs bdata scrape

# Scrape and view with markdown reader
bdata scrape https://docs.github.com | glow -

# Amazon product data to CSV
bdata pipelines amazon_product "https://amazon.com/dp/xxx" --format csv > product.csv

Environment Variables

These override stored configuration:

Troubleshooting

Key Design Principles

• One-time auth: After bdata login, everything is automatic. No tokens to manage, no keys to pass.
• Zones auto-created: Login creates cli_unlocker and cli_browser zones automatically.
• Smart defaults: Markdown output, auto-detected formats from file extensions, colors only in TTY.
• Pipe-friendly: JSON output + jq for automation. Colors/spinners disabled in pipes.
• Async support: Heavy jobs can run in background with --async + status --wait.
• npm package: @brightdata/cli — install globally or use via npx.

Bright Data CLI — Full Command Reference

Package: @brightdata/cli | Commands: brightdata / bdata (shorthand) | Requires: Node.js >= 20

Installation

# macOS / Linux
curl -fsSL https://cli.brightdata.com/install.sh | bash

# Any platform
npm install -g @brightdata/cli

# Without installing
npx --yes --package @brightdata/cli brightdata <command>

---

Global Options

These flags work with any command:

---

bdata login

Authenticate with Bright Data. Opens the browser for OAuth by default.

What happens on login: 1. Opens browser for OAuth (or uses device flow / direct API key) 2. Validates the API key 3. Saves credentials locally (~/.config/brightdata-cli/credentials.json) 4. Checks for required zones (cli_unlocker, cli_browser) 5. Creates missing zones automatically 6. Sets cli_unlocker as default zone if none configured

bdata login                        # Browser OAuth (recommended)
bdata login --device               # Headless/SSH environments
bdata login --api-key <key>        # Direct API key

---

bdata logout

Clear stored credentials.

bdata logout

---

bdata scrape <url>

Scrape any URL using Bright Data's Web Unlocker. Handles CAPTCHAs, JavaScript rendering, and anti-bot protections automatically.

bdata scrape https://news.ycombinator.com
bdata scrape https://example.com -f html
bdata scrape https://amazon.com -f json --country us -o product.json
bdata scrape https://example.com -f screenshot -o page.png
bdata scrape https://example.com --async
bdata scrape https://docs.github.com | glow -

---

bdata search <query>

Search Google, Bing, or Yandex via Bright Data's SERP API.

Google returns structured JSON with: organic results, ads, People Also Ask, related searches. Bing/Yandex return markdown by default.

bdata search "typescript best practices"
bdata search "restaurants berlin" --country de --language de
bdata search "AI regulation" --type news
bdata search "web scraping" --page 1
bdata search "open source scraping" --json | jq -r '.organic[].link'
bdata search "bright data pricing" --engine bing

---

bdata pipelines <type> [params...] [options]

Extract structured data from 40+ platforms. Triggers an async collection job, polls until ready, returns results.

bdata pipelines list                                           # List all types
bdata pipelines linkedin_person_profile "https://linkedin.com/in/username"
bdata pipelines amazon_product "https://amazon.com/dp/B09V3KXJPB" --format csv -o product.csv
bdata pipelines instagram_profiles "https://instagram.com/username"
bdata pipelines amazon_product_search "laptop" "https://amazon.com"
bdata pipelines google_maps_reviews "https://maps.google.com/..." 7
bdata pipelines youtube_comments "https://youtube.com/watch?v=..." 50

See pipelines.md for the full list of types and their parameters.

---

bdata status <job-id>

Check status of an async snapshot job.

bdata status s_abc123xyz
bdata status s_abc123xyz --wait --pretty
bdata status s_abc123xyz --wait --timeout 300

---

bdata zones

List and inspect Bright Data proxy zones.

bdata zones                        # List all active zones
bdata zones info <name>            # Full details for a zone
bdata zones --json -o zones.json   # Export as JSON
bdata zones info my_zone --pretty  # Pretty-print zone info

---

bdata budget

View account balance and per-zone cost/bandwidth. Read-only.

bdata budget
bdata budget balance
bdata budget zones
bdata budget zone my_zone
bdata budget zones --from 2024-01-01T00:00:00 --to 2024-02-01T00:00:00

---

bdata config

View and manage CLI configuration.

bdata config
bdata config set default_zone_unlocker my_zone
bdata config set default_format json
bdata config get default_zone_unlocker

---

bdata init

Interactive setup wizard. Walks through authentication, zone selection, and default configuration.

bdata init

---

bdata skill

Install Bright Data AI agent skills into coding agents (Claude Code, Cursor, Copilot, etc.).

Available skills: search, scrape, data-feeds, bright-data-mcp, bright-data-best-practices

bdata skill add              # Interactive
bdata skill add scrape       # Direct install
bdata skill list             # See what's available

---

Configuration Storage

Two files:

• credentials.json — API key (mode 0o600)
• config.json — Zones, output format, preferences

Priority order: CLI flags > Environment variables > config.json > Defaults

Pipeline Types Reference

All pipeline types available via bdata pipelines <type> [params...].

Run bdata pipelines list to see all types in your terminal.

Parameter Patterns

Most types require just a URL:

bdata pipelines <type> "<url>"

Some types have additional parameters — these are documented below.

---

E-Commerce

Amazon Search Example

# Requires both keyword and domain URL
bdata pipelines amazon_product_search "wireless headphones" "https://amazon.com"

---

Professional Networks

LinkedIn People Search Example

# Requires URL, first name, and last name
bdata pipelines linkedin_people_search "https://linkedin.com/search/results/people" "John" "Doe"

---

Social Media

YouTube Comments Example

# Optional second param: number of comments (default: 10)
bdata pipelines youtube_comments "https://youtube.com/watch?v=dQw4w9WgXcQ" 50

Facebook Reviews Example

# Optional second param: number of reviews (default: 10)
bdata pipelines facebook_company_reviews "https://facebook.com/company" 25

---

Maps, Reviews & Other

Google Maps Reviews Example

# Optional second param: days_limit (default: 3)
bdata pipelines google_maps_reviews "https://maps.google.com/maps/place/..." 7

---

Output Options

All pipeline commands support:

# JSON (default)
bdata pipelines amazon_product "<url>"

# CSV
bdata pipelines amazon_product "<url>" --format csv

# NDJSON / JSONL
bdata pipelines amazon_product "<url>" --format ndjson

# Save to file
bdata pipelines amazon_product "<url>" -o product.json

# Custom timeout (default 600 seconds)
bdata pipelines amazon_product "<url>" --timeout 1200

How Pipelines Work

1. CLI sends a trigger request to /datasets/v3/trigger with the dataset ID and input 2. Receives a snapshot_id 3. Polls /datasets/v3/snapshot/{snapshot_id} until status is no longer starting/building/running 4. Returns the collected data in the requested format

The default timeout is 600 seconds (10 minutes). For large datasets, increase with --timeout or set BRIGHTDATA_POLLING_TIMEOUT environment variable.

Bright Data CLI Installation

Quick Install

macOS / Linux:

curl -fsSL https://cli.brightdata.com/install.sh | bash

Any platform (requires Node.js >= 20):

npm install -g @brightdata/cli

Without installing (one-off usage):

npx --yes --package @brightdata/cli brightdata <command>

Verify Installation

Check if installed and authenticated:

bdata config

Authentication

If not authenticated, run:

bdata login

This opens the browser for secure OAuth authentication. After login: 1. API key is saved locally (never needs to be entered again) 2. Required proxy zones (cli_unlocker, cli_browser) are auto-created 3. Default configuration is set

For headless/SSH environments where no browser is available:

bdata login --device

For direct API key authentication (non-interactive):

bdata login --api-key <key>

If you fail to authenticate, use the following error handling instructions:

If ANY command returns an authentication error after you ran bdata login (e.g., "not authenticated", "unauthorized", "API key"), use an ask user question tool if available:

Question: "How would you like to authenticate with Bright Data?"

Options:

1. Login with browser (Recommended) — Opens your browser to authenticate with Bright Data 2. Login with device flow — For SSH/headless environments 3. Enter API key manually — Paste an existing API key from brightdata.com

If user selects browser login:

Run bdata login to automatically open the browser. Wait for them to confirm authentication, then retry the original command.

If user selects device flow:

Run bdata login --device and guide them through the device code flow.

If user selects manual API key:

Ask for their API key, then run:

bdata login --api-key "<their-key>"

Or set the environment variable:

export BRIGHTDATA_API_KEY="<their-key>"

Tell them to add this export to ~/.zshrc or ~/.bashrc for persistence, then retry the original command.

Troubleshooting

Command not found

If bdata command is not found after installation:

1. Make sure npm global bin is in PATH 2. Try: npx --yes --package @brightdata/cli brightdata --version 3. Or reinstall: npm install -g @brightdata/cli

Permission errors

If you get permission errors during installation:

# Option 1: Use the curl installer (recommended)
curl -fsSL https://cli.brightdata.com/install.sh | bash

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Add the export to your shell profile

Zone errors

If you get "No Web Unlocker zone specified":

bdata config set default_zone_unlocker <zone>
# Or re-run login to auto-create zones:
bdata login