Command Reference

Global options

These flags work with any command:

Flag	Description
`-k, --api-key <key>`	Override API key for this request
`--timing`	Show request timing info
`-v, --version`	Show CLI version

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

Flag	Description
`-k, --api-key <key>`	Use API key directly (skips browser)
`-c, --customer-id <id>`	Bright Data account ID (optional)
`-d, --device`	Use device flow for SSH/headless environments

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

On first login, the CLI automatically creates cli_unlocker and cli_browser proxy zones and sets sensible defaults.

`brightdata logout`

Clear stored credentials.

brightdata logout

`brightdata scrape <url>`

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

Flag	Description
`-f, --format <fmt>`	`markdown` (default), `html`, `screenshot`, `json`
`--country <code>`	ISO country code for geo-targeting (e.g. `us`, `de`, `jp`)
`--zone <name>`	Web Unlocker zone name
`--mobile`	Use a mobile user agent
`--async`	Submit async, return a snapshot ID
`-o, --output <path>`	Write output to file
`--json`	Force JSON output
`--pretty`	Pretty-print JSON output

brightdata scrape https://news.ycombinator.com

`brightdata search <query>`

Search Google, Bing, or Yandex via Bright Data’s SERP API. Google returns structured JSON with organic results, ads, People Also Ask, and related searches. Bing and Yandex return markdown by default.

Flag	Description
`--engine <name>`	`google` (default), `bing`, `yandex`
`--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` (default), `news`, `images`, `shopping`
`--device <type>`	`desktop`, `mobile`
`--zone <name>`	SERP zone name
`-o, --output <path>`	Write output to file
`--json`	Force JSON output
`--pretty`	Pretty-print JSON output

brightdata search "typescript best practices"

`brightdata discover <query>`

AI-powered web discovery. Submit a query with optional intent, and Bright Data finds, ranks, and optionally extracts full-page content for each result.

Flag	Description
`--intent <text>`	AI intent to evaluate and rank result relevance
`--country <code>`	ISO country code (default: `US`)
`--city <name>`	City for localized results (e.g. `"New York"`)
`--language <code>`	Language code (default: `en`)
`--num-results <n>`	Number of results to return
`--filter-keywords <words>`	Comma-separated keywords that must appear in results
`--include-content`	Include full page content (markdown) in each result
`--no-remove-duplicates`	Keep duplicate results
`--start-date <date>`	Only content updated from date (`YYYY-MM-DD`)
`--end-date <date>`	Only content updated until date (`YYYY-MM-DD`)
`--timeout <seconds>`	Polling timeout (default: `600`)
`-o, --output <path>`	Write output to file
`--json` / `--pretty`	JSON output (raw / indented)

brightdata discover "AI trends"

For best results with --intent, use a structured formula: describe your persona, what to prioritize, the depth of analysis, and what to exclude. See the Discover API reference for detailed guidance.

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

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

Flag	Description
`--format <fmt>`	`json` (default), `csv`, `ndjson`, `jsonl`
`--timeout <seconds>`	Polling timeout (default: `600`)
`-o, --output <path>`	Write output to file
`--json`	Force JSON output
`--pretty`	Pretty-print JSON output

# List all available pipeline types
brightdata pipelines list

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

Supported platforms

E-Commerce

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

Professional Networks

Type	Platform	Parameters
`linkedin_person_profile`	LinkedIn person	`<url>`
`linkedin_company_profile`	LinkedIn company	`<url>`
`linkedin_job_listings`	LinkedIn jobs	`<url>`
`linkedin_posts`	LinkedIn posts	`<url>`
`linkedin_people_search`	LinkedIn people search	`<url> <first_name> <last_name>`
`crunchbase_company`	Crunchbase	`<url>`
`zoominfo_company_profile`	ZoomInfo	`<url>`

Social Media

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

Maps, Reviews & Other

Type	Platform	Parameters
`google_maps_reviews`	Google Maps reviews	`<url> [days_limit]`
`google_play_store`	Google Play	`<url>`
`apple_app_store`	Apple App Store	`<url>`
`github_repository_file`	GitHub repository files	`<url>`
`yahoo_finance_business`	Yahoo Finance	`<url>`
`zillow_properties_listing`	Zillow	`<url>`
`booking_hotel_listings`	Booking.com	`<url>`

Run brightdata pipelines list in your terminal to see all available types at any time.

`brightdata status <job-id>`

Check the status of an async snapshot job (from --async scrapes or pipeline collections).

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

brightdata status s_abc123xyz
brightdata status s_abc123xyz --wait --pretty
brightdata status s_abc123xyz --wait --timeout 300

`brightdata browser`

Control a real browser session powered by Bright Data’s Scraping Browser. A lightweight local daemon holds the browser connection open between commands, giving you persistent state without reconnecting on every call.

brightdata browser <subcommand> [options]

Global flags

These flags work with every browser subcommand:

Flag	Description
`--session <name>`	Session name for running multiple isolated sessions in parallel (default: `default`)
`--country <code>`	Geo-target by ISO country code. On `open`, changing country reconnects the browser
`--zone <name>`	Scraping Browser zone (default: `cli_browser`)
`--timeout <ms>`	IPC command timeout in milliseconds (default: `30000`)
`--idle-timeout <ms>`	Daemon auto-shutdown after idle (default: `600000` / 10 min)
`--json` / `--pretty`	JSON output
`-o, --output <path>`	Write output to file

Subcommands

browser open

Navigate to a URL. Starts the daemon and browser session automatically if not already running.

brightdata browser open <url>
brightdata browser open https://amazon.com --country us --session shop

Flag	Description
`--country <code>`	Geo-targeting. Reconnects the browser if the country changes on an existing session
`--zone <name>`	Browser zone name
`--idle-timeout <ms>`	Daemon idle timeout for this session

browser snapshot

Capture the page as a text accessibility tree. This is the primary way AI agents read page content - far more token-efficient than raw HTML.Each interactive element gets a ref (e.g. e1, e2) that you pass to click, type, fill, and other interaction commands.

brightdata browser snapshot
brightdata browser snapshot --compact          # Interactive elements + ancestors only
brightdata browser snapshot --interactive      # Interactive elements as a flat list
brightdata browser snapshot --depth 3          # Limit tree depth
brightdata browser snapshot --selector "main"  # Scope to a CSS subtree

Example output:

Page: Example Domain
URL: https://example.com

- heading "Example Domain" [level=1]
- paragraph "This domain is for use in illustrative examples."
- link "More information..." [ref=e1]

Flag	Description
`--compact`	Only interactive elements and their ancestors (70-90% fewer tokens)
`--interactive`	Only interactive elements, as a flat list
`--depth <n>`	Limit tree depth
`--selector <sel>`	Scope snapshot to elements matching a CSS selector
`--wrap`	Wrap output in content boundaries (useful for AI agent prompt injection safety)

browser screenshot

Capture a PNG screenshot of the current viewport.

brightdata browser screenshot
brightdata browser screenshot ./result.png
brightdata browser screenshot --full-page -o page.png
brightdata browser screenshot --base64

Flag	Description
`[path]`	Where to save the PNG (default: temp directory)
`--full-page`	Capture the full scrollable page, not just the viewport
`--base64`	Output base64-encoded PNG data instead of saving to a file

browser click / type / fill

Interact with elements using their snapshot ref values.

# Click an element
brightdata browser click e3

# Type text into a field (clears first by default)
brightdata browser type e5 "search query"
brightdata browser type e5 " more text" --append    # Append to existing value
brightdata browser type e5 "search query" --submit  # Press Enter after typing

# Fill a form field directly (no keyboard simulation)
brightdata browser fill e2 "user@example.com"

# Select a dropdown option by visible label
brightdata browser select e4 "United States"

# Check / uncheck a checkbox or radio button
brightdata browser check e7
brightdata browser uncheck e7

# Hover over an element
brightdata browser hover e2

Flag (for `type`)	Description
`--append`	Append to existing value using key-by-key simulation
`--submit`	Press Enter after typing

browser scroll

Scroll the viewport or scroll an element into view.

brightdata browser scroll                          # Scroll down 300px (default)
brightdata browser scroll --direction up
brightdata browser scroll --direction down --distance 600
brightdata browser scroll --ref e10                # Scroll element into view

Flag	Description
`--direction <dir>`	`up`, `down`, `left`, `right` (default: `down`)
`--distance <px>`	Pixels to scroll (default: `300`)
`--ref <ref>`	Scroll this element into view instead of the viewport

browser get text / get html

Get text or HTML content from the page or a specific element.

# Text content
brightdata browser get text            # Full page text
brightdata browser get text "h1"       # Text of the first h1
brightdata browser get text "#price"   # Text inside #price

# HTML content
brightdata browser get html              # Full page outer HTML
brightdata browser get html ".product"   # innerHTML of .product

browser network / cookies / status

Inspect session state.

# HTTP requests captured since last navigation
brightdata browser network

# Cookies for the active session
brightdata browser cookies

# Current session state
brightdata browser status
brightdata browser status --session shop --pretty

# List all active sessions
brightdata browser sessions

browser back / forward / reload

Navigation controls.

brightdata browser back
brightdata browser forward
brightdata browser reload

browser close

Close a session and stop its daemon.

brightdata browser close                    # Close the default session
brightdata browser close --session shop     # Close a named session
brightdata browser close --all              # Close all active sessions

Element ref values (e.g. e1, e3) are re-assigned on every snapshot call. After navigating or clicking, take a fresh snapshot before using refs again.

`brightdata zones`

List and inspect Bright Data proxy zones.

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

`brightdata budget`

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

Subcommand	Description
(none)	Quick account balance
`balance`	Balance + pending charges
`zones`	Cost & bandwidth table for all zones
`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

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

`brightdata config`

View and manage CLI configuration.

Subcommand	Description
(none)	Show all config
`get <key>`	Get a single value
`set <key> <value>`	Set a value

Config Key	Description
`default_zone_unlocker`	Default zone for `scrape` and `search`
`default_zone_serp`	Override zone for `search` only
`default_format`	Default output format: `markdown` or `json`
`api_url`	Override API base URL

brightdata config
brightdata config set default_zone_unlocker my_zone
brightdata config set default_format json
brightdata config get default_zone_unlocker

`brightdata init`

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

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

brightdata init

`brightdata skill`

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

Subcommand	Description
`add`	Interactive picker - choose skills + target agents
`add <name>`	Install a specific skill directly
`list`	List all available skills

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

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

`brightdata add mcp`

Add the Bright Data MCP server to Claude Code, Cursor, or Codex. Uses the API key stored by brightdata login.

brightdata add mcp                               # Interactive agent + scope prompts
brightdata add mcp --agent claude-code --global
brightdata add mcp --agent claude-code,cursor --project
brightdata add mcp --agent codex --global

Flag	Description
`--agent <agents>`	Comma-separated targets: `claude-code`, `cursor`, `codex`
`--global`	Install to the agent’s global config file
`--project`	Install to the current project’s config file

Config file locations

Agent	Global path	Project path
Claude Code	`~/.claude.json`	`.claude/settings.json`
Cursor	`~/.cursor/mcp.json`	`.cursor/mcp.json`
Codex	`$CODEX_HOME/mcp.json` or `~/.codex/mcp.json`	Not supported

The command writes the MCP server entry under mcpServers["bright-data"]. Existing config is preserved - only the bright-data key is added or replaced.

brightdata add mcp uses the API key stored by brightdata login. It does not read BRIGHTDATA_API_KEY or the --api-key flag, so run brightdata login first.

Overview

Products

Administrative API

Global options

`brightdata logout`

`brightdata scrape <url>`

`brightdata search <query>`

`brightdata discover <query>`

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

Supported platforms

`brightdata status <job-id>`

`brightdata browser`

Global flags

Subcommands

`brightdata zones`

`brightdata budget`

`brightdata config`

`brightdata init`

`brightdata skill`

`brightdata add mcp`

Config file locations

Overview

Products

Administrative API

​Global options

​brightdata login

​brightdata logout

​brightdata scrape <url>

​brightdata search <query>

​brightdata discover <query>

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

​Supported platforms

​brightdata status <job-id>

​brightdata browser

​Global flags

​Subcommands

​brightdata zones

​brightdata budget

​brightdata config

​brightdata init

​brightdata skill

​brightdata add mcp

​Config file locations

Global options

`brightdata login`

`brightdata logout`

`brightdata scrape <url>`

`brightdata search <query>`

`brightdata discover <query>`

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

Supported platforms

`brightdata status <job-id>`

`brightdata browser`

Global flags

Subcommands

`brightdata zones`

`brightdata budget`

`brightdata config`

`brightdata init`

`brightdata skill`

`brightdata add mcp`

Config file locations