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 automaticbdata 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 markdownbdata scrape https://example.com# Get raw HTMLbdata scrape https://example.com -f html# Get structured JSONbdata scrape https://example.com -f json# Take a screenshotbdata scrape https://example.com -f screenshot -o page.png# Geo-targeted scrape from the USbdata scrape https://amazon.com --country us# Save to filebdata scrape https://example.com -o page.md# Async mode for heavy pagesbdata 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 tablebdata search "web scraping best practices"# Get raw JSON for pipingbdata search "typescript tutorials" --json# Search Bingbdata search "bright data pricing" --engine bing# Localized searchbdata search "restaurants berlin" --country de --language de# News searchbdata search "AI regulation" --type news# Extract just URLsbdata 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 profilebdata pipelines linkedin_person_profile "https://linkedin.com/in/username"# Amazon productbdata pipelines amazon_product "https://amazon.com/dp/B09V3KXJPB"# Instagram profilebdata pipelines instagram_profiles "https://instagram.com/username"# Amazon searchbdata 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 CSVbdata pipelines amazon_product "https://amazon.com/dp/..." --format csv -o product.csv# List all available pipeline typesbdata pipelines list

Checking Status

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

# Quick status checkbdata status <job-id># Wait until completebdata status <job-id> --wait# With custom timeoutbdata status <job-id> --wait --timeout 300

Budget & Zones

# Quick account balancebdata budget# Detailed balance with pending chargesbdata budget balance# All zones cost/bandwidthbdata budget zones# Specific zone costsbdata budget zone my_zone# Date range filterbdata budget zones --from 2024-01-01T00:00:00 --to 2024-02-01T00:00:00# List all zonesbdata zones# Zone detailsbdata zones info cli_unlocker

Configuration

# View all configbdata config# Set defaultsbdata config set default_zone_unlocker my_zonebdata config set default_format json

Installing AI Agent Skills

# Interactive picker — choose skills and target agentsbdata skill add# Install a specific skillbdata skill add scrape# List available skillsbdata 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 itbdata search "top open source projects" --json \  | jq -r '.organic[0].link' \  | xargs bdata scrape# Scrape and view with markdown readerbdata scrape https://docs.github.com | glow -# Amazon product data to CSVbdata 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.