brightdata-cli

Bright Data CLI

Bright Data CLI（brightdata 或 bdata）让你可以在终端中全面访问 Bright Data 的 Web 数据平台。它会自动处理身份验证、代理区域、反机器人绕过、CAPTCHA 求解和 JavaScript 渲染——用户只需登录一次。

安装

如果尚未安装 CLI，请引导用户完成安装：

macOS / Linux：

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

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

npm install -g @brightdata/cli

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

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

需要 Node.js >= 20。安装后，brightdata 和简写命令 bdata 均可使用。

首次设置

首先检查用户是否已通过身份验证。如果尚未登录，请引导他们完成一次性设置：

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

这条命令会：

1. 打开浏览器，通过安全的 OAuth 进行身份验证
2. 在本地保存 API 密钥（之后无需再次输入）
3. 自动创建所需的代理区域（cli_unlocker、cli_browser）
4. 设置默认配置

登录后，后续命令均可直接使用，无需任何手动操作。

对于无法使用浏览器的无头/SSH 环境：

bdata login --device

对于直接使用 API 密钥进行身份验证（非交互式）：

bdata login --api-key <key>

运行以下命令，确认设置已完成：

bdata config

命令参考

请阅读 references/commands.md，查看完整的命令参考，包括每条命令的所有标志、选项和示例。

请阅读 references/pipelines.md，了解管道工作流：查找抓取器、查看其输入字段并运行抓取器。

快速命令概览

bdata 是 brightdata 的简写。两者功能完全相同。

命令	用途
bdata scrape <url>	将任意 URL 抓取为 Markdown、HTML、JSON 或截图
bdata search "<query>"	使用结构化结果搜索 Google/Bing/Yandex
bdata pipelines search <query>	查找适用于某个网站或数据类型的预构建抓取器
bdata pipelines info <id> [method]	显示抓取器的方法和输入字段
bdata pipelines run <id> <method> ...	运行抓取器并获取结构化记录
bdata pipelines status <snapshot_id>	检查运行进度
bdata zones	列出代理区域
bdata budget	查看账户余额和费用
bdata skill add	安装 AI Agent 技能
bdata skill list	列出可用技能
bdata config	查看/设置配置
bdata login	使用 Bright Data 进行身份验证
bdata version	显示 CLI 版本和系统信息

各命令用法

抓取

使用自动反机器人绕过、CAPTCHA 处理和 JS 渲染功能抓取任意 URL：

# Default: returns clean markdown
bdata scrape https://example.com

# Get raw HTML
bdata scrape https://example.com -f html

# Get structured 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

搜索

使用结构化 JSON 输出搜索引擎（Google 会返回解析后的自然搜索结果、广告、“用户还问了”内容和相关搜索）：

# Google search with formatted table
bdata search "web scraping best practices"

# Get raw JSON for piping
bdata search "typescript tutorials" --json

# Search 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
bdata search "open source tools" --json | jq -r '.organic[].link'

管道（结构化数据提取）

运行数千种预构建抓取器中的任意一种。请务必先查找抓取器， 切勿猜测 dataset_id 或字段名称：

# 1. Find a scraper
bdata pipelines search <site or data type>

# 2. Its methods, then one method's input fields and a ready-to-run command
bdata pipelines info <dataset_id>
bdata pipelines info <dataset_id> <method>

# 3. Run it: URLs as arguments, other input fields as --<field> flags
bdata pipelines run <dataset_id> collect_by_url "<url>"
bdata pipelines run <dataset_id> <discover_method> --<field> <value> --limit-per-input 5

# Output as CSV
bdata pipelines run <dataset_id> <method> "<url>" --format csv -o out.csv

每条记录都会计费：请从一个输入开始。未知或缺失的必填字段会在运行开始前导致失败。

检查状态

对于使用 --async 启动的长时间运行任务：

bdata pipelines status <snapshot_id>
bdata pipelines status <snapshot_id> --wait --timeout 300
bdata pipelines results <snapshot_id>

预算和区域

# 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

配置

# View all config
bdata config

# Set defaults
bdata config set default_zone_unlocker my_zone
bdata config set default_format json

安装 AI Agent 技能

# Interactive picker — choose skills and target agents
bdata skill add

# Install a specific skill
bdata skill add scrape

# List available skills
bdata skill list

输出模式

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

标志	效果
(无)	带颜色的易读格式化输出
--json	将紧凑 JSON 输出到 stdout
--pretty	将缩进后的 JSON 输出到 stdout
-o <path>	写入文件（根据扩展名自动检测格式）

通过管道传输时（stdout 不是 TTY），颜色和旋转指示器会自动禁用。

命令串联

CLI 支持管道操作：

# Search → extract first URL → scrape it
bdata search "top open source projects" --json \
  | jq -r '.organic[0].link' \
  | xargs bdata scrape

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

# Scraper records to CSV
bdata pipelines run <dataset_id> collect_by_url "<url>" --format csv > out.csv

环境变量

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

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

故障排查

错误	解决方法
未找到 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 延长超时时间

核心设计原则

• 一次性身份验证：执行 bdata login 后，其他操作都会自动完成。无需管理令牌，也无需传入密钥。
• 自动创建区域：登录时会自动创建 cli_unlocker 和 cli_browser 区域。
• 智能默认值：输出为 Markdown，根据文件扩展名自动检测格式，仅在 TTY 中使用颜色。
• 适合管道操作：使用 JSON 输出和 jq 进行自动化。在管道中会禁用颜色和加载动画。
• 支持异步操作：繁重任务可通过 --async 在后台运行，并使用 pipelines status --wait 等待。
• npm 包：@brightdata/cli——可全局安装，也可通过 npx 使用。