brightdata-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bright Data CLI

The Bright Data CLI (

brightdata

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.

Bright Data CLI（

brightdata

或

bdata

）让你可以通过终端全面访问Bright Data的网页数据平台。它会自动处理身份验证、代理区域、反机器人绕过、CAPTCHA破解以及JavaScript渲染——用户只需登录一次即可。

Installation

安装

If the CLI is not installed yet, guide the user:

macOS / Linux:

bash

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

Windows or manual install (any platform):

bash

npm install -g @brightdata/cli

Without installing (one-off usage):

bash

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

Requires Node.js >= 20. After install, both

brightdata

and

bdata

(shorthand) are available.

如果尚未安装CLI，请引导用户按照以下步骤操作：

macOS / Linux：

bash

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

Windows或手动安装（任意平台）：

bash

npm install -g @brightdata/cli

无需安装（一次性使用）：

bash

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

要求Node.js版本 >= 20。安装完成后，

brightdata

和简写形式

bdata

均可使用。

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:

bash

undefined

在进行任何操作之前，请检查用户是否已完成身份验证。如果尚未登录，请引导他们完成一次性设置：

bash

undefined

One-time login — opens the browser for OAuth, then everything is automatic

一次性登录——打开浏览器进行OAuth认证，之后所有操作均自动完成

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:
```bash
bdata login --device

For direct API key authentication (non-interactive):

bash

bdata login --api-key <key>

To verify setup is complete, run:

bash

bdata config

bdata login


这一条命令可完成以下操作：
1. 打开浏览器进行安全的OAuth认证
2. 在本地保存API密钥（无需再次手动输入）
3. 自动创建所需的代理区域（`cli_unlocker`、`cli_browser`）
4. 设置默认配置

登录后，后续所有命令均可无需手动干预直接运行。

对于无浏览器的无头/SSH环境：
```bash
bdata login --device

直接使用API密钥认证（非交互式）：

bash

bdata login --api-key <key>

要验证设置是否完成，请运行：

bash

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.

查看references/commands.md获取完整的命令参考，包含所有命令的标志、选项及示例。

查看references/pipelines.md获取40+管道类型的完整列表（包括Amazon、LinkedIn、Instagram、TikTok、YouTube、Reddit等）及其特定参数。

Quick Command Overview

快速命令概览

bdata

is the shorthand for

brightdata

. Both work identically.

Command	Purpose
`bdata scrape <url>`	Scrape any URL as markdown, HTML, JSON, or screenshot
`bdata search "<query>"`	Search Google/Bing/Yandex with structured results
`bdata pipelines <type> [params]`	Extract structured data from 40+ platforms
`bdata pipelines list`	List all 40+ available pipeline types
`bdata status <job-id>`	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

bdata

是

brightdata

的简写形式，二者功能完全相同。

命令	用途
`bdata scrape <url>`	以markdown、HTML、JSON或截图形式抓取任意URL
`bdata search "<query>"`	搜索Google/Bing/Yandex并获取结构化结果
`bdata pipelines <type> [params]`	从40+平台提取结构化数据
`bdata pipelines list`	列出所有40+可用管道类型
`bdata status <job-id>`	检查异步任务状态
`bdata zones`	列出代理区域
`bdata budget`	查看账户余额及消费情况
`bdata skill add`	安装AI Agent技能
`bdata skill list`	列出可用技能
`bdata config`	查看/设置配置
`bdata login`	通过Bright Data进行身份认证
`bdata version`	显示CLI版本及系统信息

How to Use Each Command

各命令使用方法

Scraping

网页抓取

Scrape any URL with automatic bot bypass, CAPTCHA handling, and JS rendering:

bash

undefined

自动绕过机器人验证、处理CAPTCHA并渲染JavaScript，抓取任意URL：

bash

undefined

Default: returns clean markdown

默认：返回整洁的markdown格式

bdata scrape https://example.com

Get raw HTML

获取原始HTML

bdata scrape https://example.com -f html

Get structured JSON

获取结构化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

undefined

bdata scrape https://example.com --async

undefined

Searching

网页搜索

Search engines with structured JSON output (Google returns parsed organic results, ads, People Also Ask, and related searches):

bash

undefined

搜索搜索引擎并获取结构化JSON输出（Google会返回解析后的自然搜索结果、广告、“人们还在问”及相关搜索内容）：

bash

undefined

Google search with formatted table

Google搜索并显示格式化表格

bdata search "web scraping best practices"

Get raw JSON for piping

获取原始JSON以便管道传输

bdata search "typescript tutorials" --json

Search Bing

搜索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

仅提取URL

bdata search "open source tools" --json | jq -r '.organic[].link'

undefined

bdata search "open source tools" --json | jq -r '.organic[].link'

undefined

Pipelines (Structured Data Extraction)

管道（结构化数据提取）

Extract structured data from 40+ platforms. These trigger async jobs that poll until results are ready:

bash

undefined

从40+平台提取结构化数据。这些操作会触发异步任务，轮询直至结果就绪：

bash

undefined

LinkedIn profile

LinkedIn个人资料

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

Amazon product

Amazon产品

bdata pipelines amazon_product "https://amazon.com/dp/B09V3KXJPB"

Instagram profile

Instagram个人资料

bdata pipelines instagram_profiles "https://instagram.com/username"

Amazon search

Amazon搜索

bdata pipelines amazon_product_search "laptop" "https://amazon.com"

YouTube comments (top 50)

YouTube评论（前50条）

bdata pipelines youtube_comments "https://youtube.com/watch?v=..." 50

Google Maps reviews (last 7 days)

Google地图评论（过去7天）

bdata pipelines google_maps_reviews "https://maps.google.com/..." 7

Output as CSV

输出为CSV格式

bdata pipelines amazon_product "https://amazon.com/dp/..." --format csv -o product.csv

List all available pipeline types

列出所有可用管道类型

bdata pipelines list

undefined

bdata pipelines list

undefined

Checking Status

状态检查

For async jobs (from

--async

scrapes or pipelines):

bash

undefined

针对异步任务（来自

--async

抓取或管道操作）：

bash

undefined

Quick status check

快速检查状态

bdata status <job-id>

Wait until complete

等待任务完成

bdata status <job-id> --wait

With custom timeout

设置自定义超时时间

bdata status <job-id> --wait --timeout 300

undefined

bdata status <job-id> --wait --timeout 300

undefined

Budget & Zones

预算与代理区域

bash

undefined

bash

undefined

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

undefined

bdata zones info cli_unlocker

undefined

Configuration

配置

bash

undefined

bash

undefined

View all config

查看所有配置

bdata config

Set defaults

设置默认值

bdata config set default_zone_unlocker my_zone bdata config set default_format json

undefined

bdata config set default_zone_unlocker my_zone bdata config set default_format json

undefined

Installing AI Agent Skills

安装AI Agent技能

bash

undefined

bash

undefined

Interactive picker — choose skills and target agents

交互式选择器——选择技能并指定目标Agent

bdata skill add

Install a specific skill

安装特定技能

bdata skill add scrape

List available skills

列出可用技能

bdata skill list

undefined

bdata skill list

undefined

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 <path>`	Write to file (format auto-detected from extension)

When piped (stdout is not a TTY), colors and spinners are automatically disabled.

每个命令都支持多种输出格式：

标志	效果
（无）	带颜色的人类可读格式化输出
`--json`	紧凑JSON输出到标准输出
`--pretty`	缩进格式的JSON输出到标准输出
`-o <path>`	写入文件（格式从文件扩展名自动检测）

当通过管道传输时（标准输出不是TTY），颜色和加载动画会自动禁用。

Chaining Commands

命令链式调用

The CLI is pipe-friendly:

bash

undefined

CLI支持管道操作：

bash

undefined

Search → extract first URL → scrape it

搜索 → 提取第一个URL → 抓取该页面

bdata search "top open source projects" --json
| jq -r '.organic[0].link'
| xargs bdata scrape

Scrape and view with markdown reader

抓取页面并使用markdown阅读器查看

bdata scrape https://docs.github.com | glow -

Amazon product data to CSV

将Amazon产品数据导出为CSV

bdata pipelines amazon_product "https://amazon.com/dp/xxx" --format csv > product.csv

undefined

bdata pipelines amazon_product "https://amazon.com/dp/xxx" --format csv > product.csv

undefined

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

这些变量会覆盖已存储的配置：

变量	用途
`BRIGHTDATA_API_KEY`	API密钥（完全跳过登录步骤）
`BRIGHTDATA_UNLOCKER_ZONE`	默认Web Unlocker代理区域
`BRIGHTDATA_SERP_ZONE`	默认SERP代理区域
`BRIGHTDATA_POLLING_TIMEOUT`	轮询超时时间（秒）

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 <zone>` 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`

错误	解决方法
CLI未找到	使用 `npm i -g @brightdata/cli` 或 `curl -fsSL https://cli.brightdata.com/install.sh \| bash` 进行安装
"No Web Unlocker zone specified"	运行 `bdata config set default_zone_unlocker <zone>` 或重新运行 `bdata login`
"Invalid or expired API key"	运行 `bdata login` 重新登录
"Access denied"	在Bright Data控制面板中检查代理区域权限
"Rate limit exceeded"	等待后重试，或对大型任务使用 `--async` 模式
异步任务超时	使用 `--timeout 1200` 或设置 `BRIGHTDATA_POLLING_TIMEOUT=1200` 增加超时时间

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
```
.

一次性认证：完成
```
bdata login
```
后，所有操作均自动进行。无需管理令牌，无需手动输入密钥。
自动创建代理区域：登录时会自动创建
```
cli_unlocker
```
和
```
cli_browser
```
代理区域。
智能默认值：默认输出markdown格式，从文件扩展名自动检测格式，仅在TTY环境中显示颜色。
支持管道操作：JSON输出+jq实现自动化。管道传输时自动禁用颜色和加载动画。
异步支持：大型任务可通过
```
--async
```
+
```
status --wait
```
在后台运行。
npm包：
```
@brightdata/cli
```
——可全局安装或通过
```
npx
```
使用。