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 

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 

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.

| Command | Purpose | |---------|---------| | bdata scrape | Scrape any URL as markdown, HTML, JSON, or screenshot | | bdata search "" | Search Google/Bing/Yandex with structured results | | bdata pipelines [params] | Extract structured data from 40+ platforms | | bdata pipelines list | List all 40+ available pipeline types | | bdata status | Check async job status | | bdata zones | List proxy zones | | bdata budget | View account balance and costs | | bdata skill add | Install AI agent skills | | bdata skill list | List available skills | | bdata config | View/set configuration | | bdata login | Authenticate with Bright Data | | bdata version | Show CLI version and system info |

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 
Wait until complete
bdata status  --wait
With custom timeout
bdata status  --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:

| Flag | Effect | |------|--------| | *(none)* | Human-readable formatted output with colors | | --json | Compact JSON to stdout | | --pretty | Indented JSON to stdout | | -o | Write to file (format auto-detected from extension) |

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:

| Variable | Purpose | |----------|---------| | BRIGHTDATA_API_KEY | API key (skips login entirely) | | BRIGHTDATA_UNLOCKER_ZONE | Default Web Unlocker zone | | BRIGHTDATA_SERP_ZONE | Default SERP zone | | BRIGHTDATA_POLLING_TIMEOUT | Polling timeout in seconds |

Troubleshooting

| Error | Fix | |-------|-----| | CLI not found | Install with npm i -g @brightdata/cli or curl -fsSL https://cli.brightdata.com/install.sh \| bash | | "No Web Unlocker zone specified" | bdata config set default_zone_unlocker or re-run bdata login | | "Invalid or expired API key" | bdata login | | "Access denied" | Check zone permissions in the Bright Data control panel | | "Rate limit exceeded" | Wait and retry, or use --async for large jobs | | Async job timeout | Increase with --timeout 1200 or BRIGHTDATA_POLLING_TIMEOUT=1200 |

Key Design Principles

# 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

| Error | Fix | |-------|-----| | CLI not found | Install with npm i -g @brightdata/cli or curl -fsSL https://cli.brightdata.com/install.sh \| bash | | "No Web Unlocker zone specified" | bdata config set default_zone_unlocker or re-run bdata login | | "Invalid or expired API key" | bdata login | | "Access denied" | Check zone permissions in the Bright Data control panel | | "Rate limit exceeded" | Wait and retry, or use --async for large jobs | | Async job timeout | Increase with --timeout 1200 or BRIGHTDATA_POLLING_TIMEOUT=1200 |