Bright Data CLI

Scrape, search, and extract structured web data — directly from your terminal.

Overview

@brightdata/cli is the official npm package for the Bright Data CLI. It installs the brightdata command (with bdata as a shorthand alias) for access to the full Bright Data API surface:

Command	What it does
`brightdata scrape`	Scrape any URL — bypasses CAPTCHAs, JS rendering, anti-bot protections
`brightdata search`	Google / Bing / Yandex search with structured JSON output
`brightdata pipelines`	Extract structured data from 40+ platforms (Amazon, LinkedIn, TikTok…)
`brightdata zones`	List and inspect your Bright Data proxy zones
`brightdata budget`	View account balance and per-zone cost & bandwidth
`brightdata skill`	Install Bright Data AI agent skills into your coding agent
`brightdata config`	Manage CLI configuration
`brightdata init`	Interactive setup wizard

Installation

Requires Node.js ≥ 20

macOS / Linux

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

Windows

npm install -g @brightdata/cli

Or install manually on any platform

npm install -g @brightdata/cli

You can also run without installing:

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

Quick Start

# 1. Run the interactive setup wizard
brightdata init

# 2. Scrape a page as markdown
brightdata scrape https://example.com

# 3. Search Google
brightdata search "web scraping best practices"

# 4. Extract a LinkedIn profile
brightdata pipelines linkedin_person_profile "https://linkedin.com/in/username"

# 5. Check your account balance
brightdata budget

Authentication

Get your API key from brightdata.com/cp/setting/users.

# Interactive — opens browser, saves key automatically
brightdata login

# Non-interactive — pass key directly
brightdata login --api-key <your-api-key>

# Environment variable — no login required
export BRIGHTDATA_API_KEY=your-api-key

On first login the CLI checks for required zones (cli_unlocker, cli_browser) and creates them automatically if missing.

# Clear saved credentials
brightdata logout

Commands

`init`

Interactive setup wizard. The recommended way to get started.

brightdata init

Walks through: API key detection → zone selection → default output format → quick-start examples.

Flag	Description
`--skip-auth`	Skip the authentication step
`-k, --api-key <key>`	Provide API key directly

`scrape`

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

brightdata scrape <url> [options]

Flag	Description
`-f, --format <fmt>`	`markdown` · `html` · `screenshot` · `json` (default: `markdown`)
`--country <code>`	Geo-target by ISO country code (e.g. `us`, `de`, `jp`)
`--zone <name>`	Web Unlocker zone name
`--mobile`	Use a mobile user agent
`--async`	Submit async job, return a snapshot ID
`-o, --output <path>`	Write output to file
`--json` / `--pretty`	JSON output (raw / indented)
`-k, --api-key <key>`	Override API key

Examples

# Scrape as markdown (default)
brightdata scrape https://news.ycombinator.com

# Scrape as raw HTML
brightdata scrape https://example.com -f html

# US geo-targeting, save to file
brightdata scrape https://amazon.com -f json --country us -o product.json

# Pipe to a markdown viewer
brightdata scrape https://docs.github.com | glow -

# Async — returns a snapshot ID you can poll with `status`
brightdata scrape https://example.com --async

`search`

Search Google, Bing, or Yandex via Bright Data's SERP API. Google results include structured data (organic results, ads, people-also-ask, related searches).

brightdata search <query> [options]

Flag	Description
`--engine <name>`	`google` · `bing` · `yandex` (default: `google`)
`--country <code>`	Localized results (e.g. `us`, `de`)
`--language <code>`	Language code (e.g. `en`, `fr`)
`--page <n>`	Page number, 0-indexed (default: `0`)
`--type <type>`	`web` · `news` · `images` · `shopping` (default: `web`)
`--device <type>`	`desktop` · `mobile`
`--zone <name>`	SERP zone name
`-o, --output <path>`	Write output to file
`--json` / `--pretty`	JSON output (raw / indented)
`-k, --api-key <key>`	Override API key

Examples

# Formatted table output (default)
brightdata search "typescript best practices"

# German localized results
brightdata search "restaurants berlin" --country de --language de

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

# Page 2 of results
brightdata search "web scraping" --page 1

# Extract just the URLs
brightdata search "open source scraping" --json | jq -r '.organic[].link'

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

`pipelines`

Extract structured data from 40+ platforms using Bright Data's Web Scraper API. Triggers an async collection job, polls until ready, and returns results.

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

Flag	Description
`--format <fmt>`	`json` · `csv` · `ndjson` · `jsonl` (default: `json`)
`--timeout <seconds>`	Polling timeout (default: `600`)
`-o, --output <path>`	Write output to file
`--json` / `--pretty`	JSON output (raw / indented)
`-k, --api-key <key>`	Override API key

# List all available dataset types
brightdata pipelines list

Examples

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

# Amazon product → CSV
brightdata pipelines amazon_product "https://amazon.com/dp/B09V3KXJPB" \
  --format csv -o product.csv

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

# Amazon search by keyword
brightdata pipelines amazon_product_search "laptop" "https://amazon.com"

# Google Maps reviews
brightdata pipelines google_maps_reviews "https://maps.google.com/..." 7

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

See Dataset Types Reference for the full list.

`status`

Check the status of an async snapshot job (returned by --async or pipelines).

brightdata status <job-id> [options]

Flag	Description
`--wait`	Poll until the job completes
`--timeout <seconds>`	Polling timeout (default: `600`)
`-o, --output <path>`	Write output to file
`--json` / `--pretty`	JSON output (raw / indented)
`-k, --api-key <key>`	Override API key

# Check current status
brightdata status s_abc123xyz

# Block until complete
brightdata status s_abc123xyz --wait --pretty

# Custom timeout (5 minutes)
brightdata status s_abc123xyz --wait --timeout 300

`zones`

List and inspect your Bright Data proxy zones.

brightdata zones               # List all active zones
brightdata zones info <name>   # Show full details for a zone

# Export all zones as JSON
brightdata zones --json -o zones.json

# Inspect a specific zone
brightdata zones info my_unlocker_zone --pretty

`budget`

View your account balance and per-zone cost and bandwidth usage. Read-only — no writes to the API.

brightdata budget                     # Show account balance (quick view)
brightdata budget balance             # Account balance + pending charges
brightdata budget zones               # Cost & bandwidth table for all zones
brightdata budget zone <name>         # Detailed cost & bandwidth for one zone

Flag	Description
`--from <datetime>`	Start of date range (e.g. `2024-01-01T00:00:00`)
`--to <datetime>`	End of date range
`--json` / `--pretty`	JSON output (raw / indented)
`-k, --api-key <key>`	Override API key

# Current account balance
brightdata budget

# Zone costs for January 2024
brightdata budget zones --from 2024-01-01T00:00:00 --to 2024-02-01T00:00:00

# Detailed view of a specific zone
brightdata budget zone my_unlocker_zone

`skill`

Install Bright Data AI agent skills into your coding agent (Claude Code, Cursor, Copilot, etc.). Skills provide your agent with context and instructions for using Bright Data APIs effectively.

brightdata skill add              # Interactive picker — choose skill + agent
brightdata skill add <name>       # Install a specific skill directly
brightdata skill list             # List all available Bright Data skills

Available skills

Skill	Description
`search`	Search Google and get structured JSON results
`scrape`	Scrape any webpage as clean markdown with bot bypass
`data-feeds`	Extract structured data from 40+ websites
`bright-data-mcp`	Orchestrate 60+ Bright Data MCP tools
`bright-data-best-practices`	Reference knowledge base for writing Bright Data code

# Interactive — select skills and choose which agents to install to
brightdata skill add

# Install the scrape skill directly
brightdata skill add scrape

# See what's available
brightdata skill list

`config`

View and manage CLI configuration.

brightdata config                              # Show all config
brightdata config get <key>                    # Get a single value
brightdata config set <key> <value>            # Set a value

Key	Description
`default_zone_unlocker`	Default zone for `scrape` and `search`
`default_zone_serp`	Default zone for `search` (overrides unlocker zone)
`default_format`	Default output format: `markdown` or `json`
`api_url`	Override the Bright Data API base URL

brightdata config set default_zone_unlocker my_zone
brightdata config set default_format json

`login` / `logout`

brightdata login                      # Interactive login
brightdata login --api-key <key>      # Non-interactive
brightdata logout                     # Clear saved credentials

Configuration

Config is stored in an OS-appropriate location:

OS	Path
macOS	`~/Library/Application Support/brightdata-cli/`
Linux	`~/.config/brightdata-cli/`
Windows	`%APPDATA%\brightdata-cli\`

Two files are stored:

credentials.json — API key
config.json — zones, output format, preferences

Priority order (highest → lowest):

CLI flags  →  Environment variables  →  config.json  →  Defaults

Environment Variables

Variable	Description
`BRIGHTDATA_API_KEY`	API key (overrides stored credentials)
`BRIGHTDATA_UNLOCKER_ZONE`	Default Web Unlocker zone
`BRIGHTDATA_SERP_ZONE`	Default SERP zone
`BRIGHTDATA_POLLING_TIMEOUT`	Default polling timeout in seconds

BRIGHTDATA_API_KEY=xxx BRIGHTDATA_UNLOCKER_ZONE=my_zone \
  brightdata scrape https://example.com

Output Modes

Every command supports:

Mode	Flag	Behavior
Human-readable	(default)	Formatted table or markdown, with colors
JSON	`--json`	Compact JSON to stdout
Pretty JSON	`--pretty`	Indented JSON to stdout
File	`-o <path>`	Write to file; format inferred from extension

Auto-detected file formats:

Extension	Format
`.json`	JSON
`.md`	Markdown
`.html`	HTML
`.csv`	CSV

Pipe-Friendly Usage

When stdout is not a TTY, colors and spinners are automatically disabled. Errors go to stderr, data to stdout.

# Extract URLs from search results
brightdata search "nodejs tutorials" --json | jq -r '.organic[].link'

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

# Save scraped content to a file
brightdata scrape https://example.com -f markdown > page.md

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

# Chain search → scrape
brightdata search "top open source projects" --json \
  | jq -r '.organic[0].link' \
  | xargs brightdata scrape

Dataset Types Reference

brightdata pipelines list   # See all types in your terminal

E-Commerce

Type	Platform
`amazon_product`	Amazon product page
`amazon_product_reviews`	Amazon reviews
`amazon_product_search`	Amazon search results
`walmart_product`	Walmart product page
`walmart_seller`	Walmart seller profile
`ebay_product`	eBay listing
`bestbuy_products`	Best Buy
`etsy_products`	Etsy
`homedepot_products`	Home Depot
`zara_products`	Zara
`google_shopping`	Google Shopping

Professional Networks

Type	Platform
`linkedin_person_profile`	LinkedIn person
`linkedin_company_profile`	LinkedIn company
`linkedin_job_listings`	LinkedIn jobs
`linkedin_posts`	LinkedIn posts
`linkedin_people_search`	LinkedIn people search
`crunchbase_company`	Crunchbase
`zoominfo_company_profile`	ZoomInfo

Social Media

Type	Platform
`instagram_profiles`	Instagram profiles
`instagram_posts`	Instagram posts
`instagram_reels`	Instagram reels
`instagram_comments`	Instagram comments
`facebook_posts`	Facebook posts
`facebook_marketplace_listings`	Facebook Marketplace
`facebook_company_reviews`	Facebook reviews
`facebook_events`	Facebook events
`tiktok_profiles`	TikTok profiles
`tiktok_posts`	TikTok posts
`tiktok_shop`	TikTok shop
`tiktok_comments`	TikTok comments
`x_posts`	X (Twitter) posts
`youtube_profiles`	YouTube channels
`youtube_videos`	YouTube videos
`youtube_comments`	YouTube comments
`reddit_posts`	Reddit posts

Other

Type	Platform
`google_maps_reviews`	Google Maps reviews
`google_play_store`	Google Play
`apple_app_store`	Apple App Store
`reuter_news`	Reuters news
`github_repository_file`	GitHub repository files
`yahoo_finance_business`	Yahoo Finance
`zillow_properties_listing`	Zillow
`booking_hotel_listings`	Booking.com

Troubleshooting

Error: No Web Unlocker zone specified

brightdata config set default_zone_unlocker <your-zone-name>
# or
export BRIGHTDATA_UNLOCKER_ZONE=<your-zone-name>

Error: Invalid or expired API key

brightdata login

Error: Access denied

Check zone permissions in the Bright Data control panel.

Error: Rate limit exceeded

Wait a moment and retry. Use --async for large jobs to avoid timeouts.

Async job is too slow

brightdata pipelines amazon_product <url> --timeout 1200
# or
export BRIGHTDATA_POLLING_TIMEOUT=1200

Garbled output in non-interactive terminal

Colors and spinners are disabled automatically when not in a TTY. If you still see ANSI codes, add | cat at the end of your command.

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github/workflows		.github/workflows
assets		assets
src		src
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.mjs		vitest.config.mjs

Folders and files

Latest commit

History

Repository files navigation

Bright Data CLI

Overview

Table of Contents

Installation

macOS / Linux

Windows

Or install manually on any platform

Quick Start

Authentication

Commands

init

scrape

search

pipelines

status

zones

budget

skill

config

login / logout

Configuration

Environment Variables

Output Modes

Pipe-Friendly Usage

Dataset Types Reference

E-Commerce

Professional Networks

Social Media

Other

Troubleshooting

Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors 1

Languages

`init`

`scrape`

`search`

`pipelines`

`status`

`zones`

`budget`

`skill`

`config`

`login` / `logout`

Packages