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:

Table of Contents

• Installation
• Quick Start
• Authentication
• Free Tier
• Commands
• init
• scrape
• search
• discover
• scraper create
• scraper run
• scraper heal
• scraper approve
• pipelines
• browser
• zones
• budget
• skill
• add mcp
• config
• login / logout
• Configuration
• Environment Variables
• Output Modes
• Pipe-Friendly Usage
• Troubleshooting

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. Find a scraper and get structured data
brightdata pipelines search linkedin profiles

# 5. Check your account balance
brightdata budget

# 6. Install the Bright Data MCP server into your coding agent
brightdata add mcp

Authentication

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

# Interactive — opens browser, saves key automatically
brightdata login

# Via GitHub CLI — no browser needed (requires gh)
brightdata login --github

# 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

brightdata add mcp uses the API key stored by brightdata login. It does not currently read BRIGHTDATA_API_KEY or the global --api-key flag, so log in first before using it.

Free Tier

Every new Bright Data account includes a recurring monthly free tier — no credit card or commitment required to start. See the Free Tier docs for full details.

5,000 free credits per month (≈ $7.50), renewing on the 1st of each month. Unused credits don't roll over.

These credits cover the products most CLI commands use:

Not included in the monthly free credits: proxy products (Datacenter, ISP, Residential) and the Browser API (brightdata browser). These get a separate one-time $2 trial (valid 7 days), plus a $5 bonus when you add a payment method (valid 30 days).

Adding a credit card is a verification step only — you are not charged unless your free credits are exhausted and you have funds deposited. Accounts on custom pay-as-you-go or pre-commit subscription plans don't receive the recurring monthly free credits.

Check your remaining balance any time with brightdata budget.

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.

scrape

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

brightdata scrape <url> [options]

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 response ID
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]

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

discover

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

brightdata discover <query> [options]

Examples

```bash

Basic discovery — table output

brightdata discover "AI trends"

With AI intent for relevance ranking

brightdata discover "AI trends" \ --intent "Prioritize institutional reports for VC research"

Include full page content as markdown

brightdata discover "AI trends" --include-content --num-results 5

Geo-targeted with date range

brightdata discover "best restaurants" --country US --city "New York" \ --start-date 2025-01-01 --end-date 2025-12-31

Filter results by keywords

brightdata discover "generative AI SaaS" --filter-keywords "revenue,SaaS"

JSON output to file

brightdata discover "AI trends" --num-results 10 --pretty -o results.json

Pipe-friendly — redirected stdout outputs JSON automatically

brightdata discover "AI trends" --include-content --num-results 3 > re