Bright Data CLI

直接从终端抓取、搜索并提取结构化网页数据。

概述

@brightdata/cli 是 Bright Data CLI 的官方 npm 软件包。它会安装 brightdata 命令（bdata 是其简写别名），让你可以访问完整的 Bright Data API：

命令	功能
`brightdata scrape`	抓取任意 URL：绕过 CAPTCHA、JS 渲染和反爬虫保护
`brightdata search`	通过 Google / Bing / Yandex 搜索并输出结构化 JSON
`brightdata discover`	由 AI 驱动的网页发现：根据意图查找结果并进行排名，还可选择获取完整页面内容
`brightdata scraper create`	使用 AI 根据自然语言描述构建 Bright Data 爬虫工具
`brightdata scraper run`	在 URL 上运行 Bright Data 抓取工具并返回数据
`brightdata scraper heal`	通过 AI 自修复原地修复现有爬虫工具（在审批关卡停止）
`brightdata scraper approve`	批准（或拒绝）正在等待审批的自修复方案
`brightdata pipelines`	搜索并运行数千个预构建爬虫工具（Amazon、LinkedIn、TikTok……），获取结构化数据
`brightdata browser`	通过 Bright Data 的抓取浏览器控制真实浏览器：导航、生成快照、点击、输入等
`brightdata zones`	列出并检查你的 Bright Data 代理区域
`brightdata budget`	查看账户余额以及各区域的费用和带宽
`brightdata skill`	将 Bright Data AI 智能体技能安装到你的编码智能体中
`brightdata add mcp`	将 Bright Data MCP 服务器添加到 Claude Code、Cursor 或 Codex
`brightdata config`	管理 CLI 配置
`brightdata init`	交互式设置向导

安装
快速开始
身份验证
免费套餐
命令
- init
- scrape
- search
- discover
- 创建抓取工具
- 运行爬虫工具
- 修复抓取工具
- 批准爬虫
- pipelines
- browser
- zones
- budget
- skill
- 添加 MCP
- config
- 登录 / 退出登录
配置
环境变量
输出模式
管道友好用法
故障排除

安装

需要 Node.js ≥ 20

macOS / Linux

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

Windows

npm install -g @brightdata/cli

或在任意平台上手动安装

npm install -g @brightdata/cli

你也可以不安装直接运行：

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

快速开始

# 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

身份验证

从 www.bright.cn/cp/setting/users 获取你的 API 密钥。

# 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

首次登录时，CLI 会检查所需区域（cli_unlocker、cli_browser），如果缺失则自动创建。

# Clear saved credentials
brightdata logout

brightdata add mcp 使用由 brightdata login 存储的 API 密钥。目前它不会读取 BRIGHTDATA_API_KEY 或全局 --api-key 标志，因此请先登录再使用。

免费套餐

每个新的 Bright Data 账户都包含按月续期的免费套餐：开始使用无需信用卡，也无需承诺。完整详情请参阅免费套餐文档。

每月 5,000 个免费积分（约 7.50 美元），每月 1 日续期。未使用的积分不会结转。

这些积分适用于大多数 CLI 命令所使用的产品：

产品	CLI 命令	积分成本
网络解锁器 API	`scrape`	1 个积分 / 请求
搜索引擎 API	`search`	1 个积分 / 请求
网页爬虫工具 API	`pipelines`	1 个积分 / 请求
爬虫工作室	`scraper create` / `run` / `heal`	1 个积分 / 页面加载（共享额度池，并非按记录计费）

每月免费积分不包括代理产品（数据中心代理、ISP 代理、住宅代理）和浏览器 API（brightdata browser）。这些产品另有一次性 2 美元试用额度（有效期 7 天），添加付款方式后还可获得 5 美元奖励额度（有效期 30 天）。

添加信用卡仅用于验证：除非你的免费积分已用尽且账户中有预存资金，否则不会向你收费。采用自定义按量付费或预付费订阅方案的账户无法获得按月续期的免费积分。

随时使用 brightdata budget 查看剩余余额。

命令

`init`

交互式设置向导。推荐使用此方式开始。

brightdata init

引导流程：检测 API 密钥 → 选择区域 → 设置默认输出格式 → 快速入门示例。

标志	说明
`--skip-auth`	跳过身份验证步骤
`-k, --api-key <key>`	直接提供 API 密钥

`scrape`

使用 Bright Data 的网络解锁器抓取任意 URL。自动处理 CAPTCHA、JavaScript 渲染和反爬虫保护。

brightdata scrape <url> [options]

标志	说明
`-f, --format <fmt>`	`markdown` · `html` · `screenshot` · `json`（默认值：`markdown`）
`--country <code>`	通过 ISO 国家/地区代码进行地理定位（例如 `us`、`de`、`jp`）
`--zone <name>`	网络解锁器区域名称
`--mobile`	使用移动端 User-Agent
`--async`	提交异步任务并返回响应 ID
`-o, --output <path>`	将输出写入文件
`--json` / `--pretty`	JSON 输出（原始 / 缩进）
`-k, --api-key <key>`	覆盖 API 密钥

示例

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

通过 Bright Data 的搜索引擎 API 搜索 Google、Bing 或 Yandex。Google 结果包含结构化数据（自然搜索结果、广告、其他用户还问了、相关搜索）。

brightdata search <query> [options]

标志	说明
`--engine <name>`	`google` · `bing` · `yandex`（默认值：`google`）
`--country <code>`	本地化结果（例如 `us`、`de`）
`--language <code>`	语言代码（例如 `en`、`fr`）
`--page <n>`	页码，从 0 开始（默认值：`0`）
`--type <type>`	`web` · `news` · `images` · `shopping`（默认值：`web`）
`--device <type>`	`desktop` · `mobile`
`--zone <name>`	SERP 区域名称
`-o, --output <path>`	将输出写入文件
`--json` / `--pretty`	JSON 输出（原始 / 缩进）
`-k, --api-key <key>`	覆盖 API 密钥

示例

# 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 驱动的网页发现。提交查询及可选意图，Bright Data 会查找结果、进行排名，并可选择为每个结果提取完整页面内容。

brightdata discover <query> [options]

标志	说明
`--intent <text>`	用于评估结果相关性并进行排名的 AI 意图
`--country <code>`	ISO 国家/地区代码（默认值：`US`）
`--city <name>`	用于本地化结果的城市（例如 `"New York"`）
`--language <code>`	语言代码（默认值：`en`）
`--num-results <n>`	要返回的结果数量
`--filter-keywords <words>`	结果中必须包含的关键词，以逗号分隔
`--include-content`	在每个结果中包含完整页面内容
`--no-remove-duplicates`	保留重复结果
`--start-date <date>`	仅包含从指定日期起更新的内容（`YYYY-MM-DD`）
`--end-date <date>`	仅包含截至指定日期更新的内容（`YYYY-MM-DD`）
`--timeout <seconds>`	轮询超时时间（默认值：`600`）
`-o, --output <path>`	将输出写入文件
`--json` / `--pretty`	JSON 输出（原始 / 缩进）
`-k, --api-key <key>`	覆盖 API 密钥

示例

# 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 > results.json

`scraper create`

使用 AI 根据自然语言描述构建 Bright Data 爬虫工具。

brightdata scraper create <url> <description> [options]

标志	说明
`--name <name>`	爬虫模板名称（默认值：`cli-scraper-<timestamp>`）
`--deliver-webhook <url>`	用于交付存根的 Webhook URL（默认值：`https://example.com/webhook`）
`--timeout <seconds>`	轮询超时时间，以秒为单位（默认值：`600`）
`--max-retries <n>`	达到 AI-Flow 并发任务上限并返回 429 时的最大重试次数（默认值：`4`）。见下文。
`--no-retry`	遇到 429 时立即失败，不等待。等同于 `--max-retries 0`。
`-o, --output <path>`	将 JSON 封装写入文件（见下文）
`--json` / `--pretty`	JSON 输出（原始 / 缩进）
`--legacy-output`	将 v0.3 之前不带封装的 AI 进度负载写入 `-o`，而非封装。仅用于迁移。
`--timing`	显示请求耗时
`-k, --api-key <key>`	覆盖 API 密钥

注意：创建爬虫工具时会使用占位 Webhook 交付目标（https://example.com/webhook）。创建后，你可以在 Bright Data 网页界面中重新配置实际交付端点。

输出封装（`-o create.json`）

每种终止路径（无论成功还是失败）都会写入相同结构的 JSON 封装：

{
  "collector_id":    "c_mp7x8a9b2c0d1e2f",
  "name":            "my-product-scraper",
  "status":          "done",
  "completed_steps": ["prepare_intent_analyzer", "planner", "..."],
  "view_url":        "https://brightdata.com/cp/scrapers/c_mp7x8a9b2c0d1e2f",
  "created_at":      "2026-05-18T07:28:30Z"
}

在失败路径中，封装会添加 error 字段，并且 status 会反映失败类别（ai_trigger_failed、failed、poll_failed）。collector_id 和 view_url 仍会保留，以便你恢复或检查尚未构建完成的爬虫工具。

这样，scraper-studio.md 中记录的命令链即可按原样运行：

brightdata scraper create https://example.com/product/1 "..." \
    -o create.json
COLLECTOR_ID=$(jq -r '.collector_id' create.json)
brightdata scraper run "$COLLECTOR_ID" https://example.com/product/2

文件格式取决于 -o 扩展名，因此 .json 会以紧凑格式写入（非常适合 jq）。如果省略 -o，可使用 --pretty 在 stdout 中输出缩进 JSON。

如果现有脚本依赖 v0.3 之前不带封装的进度结构，请使用 --legacy-output；在你迁移期间，此标志会继续支持一个次要版本。

并发任务上限与自动退避

Bright Data AI Flow 会限制每个账户并发的 scraper create 生成任务数（目前为 3 个）。如果超出限制，API 会返回 429 Cannot run more than N jobs in parallel。CLI 会自动处理：采用指数退避和抖动策略等待，并最多重试 --max-retries 次（默认 4 次）。等待期间，CLI 会输出状态行，让你知道它并未卡住：

Triggering AI generation...
Hit AI-Flow concurrent-job cap (429). Waiting 32s before retry 1/4...
Hit AI-Flow concurrent-job cap (429). Waiting 67s before retry 2/4...
Generating scraper...

如果重试全部用尽后仍达到上限，CLI 会退出，并在 stderr 中显示提示，指向未构建完成的采集器控制面板 URL，方便你手动检查或删除它（Bright Data 目前尚未提供以编程方式删除采集器的功能）。

如果你希望沿用旧的快速失败行为，请使用 --no-retry：这通常适用于希望自行处理退避的脚本。

示例

# Build a scraper for a product page
brightdata scraper create https://example.com/product/1 \
    "Extract title, price, and image URL from this product page"

# Name the scraper and save the envelope to a file
brightdata scraper create https://example.com/product/1 \
    "Extract title, price, and image URL from this product page" \
    --name my-product-scraper -o create.json

# Capture the collector_id for chaining
COLLECTOR_ID=$(jq -r '.collector_id' create.json)

# Fan out 10 parallel creates — the CLI serialises automatically via 429 backoff
for url in $(cat urls.txt); do
    brightdata scraper create "$url" "Extract title, price, ..." \
        --name "scraper-$(basename $url)" &
done; wait

# Disable the auto-backoff (fail fast on 429)
brightdata scraper create https://example.com/product/1 \
    "Extract title, price, and image URL from this product page" \
    --no-retry

# Use a custom webhook delivery URL
brightdata scraper create https://example.com/product/1 \
    "Extract title, price, and image URL from this product page" \
    --deliver-webhook https://my-app.com/ingest

`scraper run`

在一个或多个 URL 上运行爬虫工具（通过 scraper create 或网页界面构建），并获取提取的数据。

brightdata scraper run <collector_id> [url] [options]

请通过以下三种方式之一提供 URL：

位置参数 <url>：单个 URL（旧版形式，保持不变）。
--urls <u1,u2,...>：以逗号分隔的列表。
--input-file <path>：每行一个 URL 的文件、URL 字符串的 JSON 数组，或 {"url": "..."} 对象的 JSON 数组。

标志	说明
`--urls <list>`	以逗号分隔的 URL 列表（多 URL 批处理路径）
`--input-file <path>`	包含 URL 的文件（txt 每行一个，或 JSON 数组）
`--sync`	使用同步 `/dca/crawl` 端点（仅限单个 URL，服务端上限为 25–50 秒）
`--sync-timeout <seconds>`	同步模式服务器超时时间，`25`：`50`（默认值：`50`）
`--timeout <seconds>`	轮询超时时间（默认值：单个 URL 为 `600`，批处理为 `3600`）
`--name <name>`	便于阅读的任务名称
`--version <version>`	爬虫版本（例如 `dev`）
`-o, --output <path>`	将输出写入文件
`--json` / `--pretty`	JSON 输出（原始 / 缩进）
`--timing`	显示请求耗时
`-k, --api-key <key>`	覆盖 API 密钥

路由

单个 URL（位置参数，或通过 --urls / --input-file 提供一个条目）→ 异步流程：/dca/trigger_immediate → 轮询 /dca/get_result。使用 --sync 调用 /dca/crawl（单次请求，25–50 秒）。
多个 URL（--urls / --input-file 中包含 2 个以上条目）→ 使用数组请求体向 /dca/trigger 发送一次 POST，生成一个 collection_id，并通过 /dca/dataset 轮询。这与参考 SDK 使用的标准批处理结构一致（triggerWithUrls / trigger_with_urls）。--sync 与多 URL 不兼容：/dca/crawl 仅接受单个 URL。

如果单个 URL 展开的页面数超过实时任务限制（分页列表、无限滚动），CLI 会自动回退到批处理端点，并输出一行提示。无需标志。

示例

# Default: async + poll until results arrive
brightdata scraper run c_mp3tuab31lswoxvpws https://www.amazon.com/dp/B08N5WRWNW

# Save pretty-printed results to a file
brightdata scraper run c_mp3tuab31lswoxvpws https://www.amazon.com/dp/B08N5WRWNW \
    --pretty -o product.json

# Sync mode for fast pages
brightdata scraper run c_mp3tuab31lswoxvpws https://example.com/p/1 --sync

# Sync with a shorter server timeout and a job name
brightdata scraper run c_mp3tuab31lswoxvpws https://example.com/p/1 \
    --sync --sync-timeout 30 --name first-test

# Multi-URL batch — one API call, one snapshot, one merged result array
brightdata scraper run c_mp3tuab31lswoxvpws \
    --urls "https://example.com/p/1,https://example.com/p/2,https://example.com/p/3" \
    --pretty -o products.json

# Multi-URL from a file (one URL per line; # comments and blank lines skipped)
brightdata scraper run c_mp3tuab31lswoxvpws --input-file urls.txt -o products.json

# Multi-URL from a JSON array
echo '["https://example.com/p/1","https://example.com/p/2"]' > urls.json
brightdata scraper run c_mp3tuab31lswoxvpws --input-file urls.json

`scraper heal`

当现有爬虫工具可以运行但返回错误、空白或不完整的数据时，对其进行原地修复。collector_id 保持不变：爬虫工具会得到改进，而不是被替换。这是 scraper create 的维护对应功能：它会触发 Bright Data 的 AI 自修复流程（POST /dca/collectors/{id}/refactor_template），然后轮询进度。

brightdata scraper heal <collector_id> "<prompt>" [options]

由你负责检测。 CLI 永远不会自行判断爬虫工具是否损坏：你需要检查运行输出并作出判断。<prompt> 为必填项（最多 1000 个字符）；请准确说明问题所在以及正确输出应是什么。模糊的提示会产生模糊的修复结果。

标志	说明
`--url <url>`	嵌入成功 `next_step` 提示中的验证目标（不会发送给修复调用）
`--auto-approve`	修复到达审批关卡时自动批准，并持续轮询至 `done`（默认：停止并等待你审核）
`--timeout <seconds>`	轮询超时时间（默认值：`600`）
`--max-retries <n>`	达到 AI-Flow 并发任务上限 `429` 时的最大重试次数（默认值：`4`）
`--no-retry`	遇到 `429` 时立即失败，不等待并发上限解除
`-o, --output <path>`	将输出写入文件
`--json` / `--pretty`	JSON 输出（原始 / 缩进）
`--legacy-output`	输出不带封装的 AI 进度负载
`--timing`	显示请求耗时
`-k, --api-key <key>`	覆盖 API 密钥

审批关卡

自修复采用人工介入机制。如果不使用 --auto-approve，heal 会执行修复，然后在提交前停在审批关卡，以 0 退出并生成 status: "awaiting_approval" 封装：

{
  "collector_id": "c_mp3tuab31lswoxvpws",
  "status":       "awaiting_approval",
  "prompt":       "Price returns null — the selector moved …",
  "preview_result": [ { "title": "…", "price": { "value": 51.77, "currency": "GBP" } }, … ],
  "diff_summary": "proposed template has 1 step(s) — review at view_url",
  "view_url":     "https://brightdata.com/cp/scrapers/c_mp3tuab31lswoxvpws",
  "next_step":    "bdata scraper approve c_mp3tuab31lswoxvpws --url https://example.com/product/1"
}

preview_result 会显示修复后的爬虫工具将生成的示例行：请审核这些内容，然后运行 next_step（scraper approve）进行提交。awaiting_approval 并不表示失败；它表示修复方案已就绪，正在等待你的决定。修复失败（429 上限重试耗尽、超时、终止状态 failed）是非破坏性的，现有爬虫工具不会改变，仍可像以前一样运行。

示例

# Heal a scraper, stop at the gate, and get a ready-to-run verify command back
brightdata scraper heal c_mp3tuab31lswoxvpws \
    "The price field returns null — the selector moved into a span with \
     data-testid. Capture price and currency again." \
    --url https://example.com/product/1 --pretty -o heal.json

# Fully autonomous: heal and approve in one command (no manual review)
brightdata scraper heal c_mp3tuab31lswoxvpws \
    "Reviews stopped extracting after the page redesign" --auto-approve

`scraper approve`

提交（或拒绝）由 scraper heal 留在等待审批状态的自修复方案。调用 POST /dca/collectors/{id}/resume_automation_job，然后轮询重构任务直至 done。

brightdata scraper approve <collector_id> [options]

标志	说明
`--reject`	拒绝提议的修复方案，而不是批准
`--url <url>`	嵌入成功 `next_step` 提示中的验证目标
`--timeout <seconds>`	轮询超时时间（默认值：`600`）
`-o, --output <path>`	将输出写入文件
`--json` / `--pretty`	JSON 输出（原始 / 缩进）
`--legacy-output`	输出不带封装的 AI 进度负载
`--timing`	显示请求耗时
`-k, --api-key <key>`	覆盖 API 密钥

成功后，任务会推进至 status: "done"，封装会返回 next_step = scraper run <id> <url>，以便你验证已提交的修复。--reject 会丢弃提议的修复方案（status: "rejected"）：使用更明确的提示重新运行 scraper heal 即可再次尝试。如果一次修复需要多次审批，approve 可能会再次停在 awaiting_approval，再运行一次即可。

自修复循环

# 1. Run and inspect the data
brightdata scraper run c_mp3tuab31lswoxvpws https://example.com/product/1 --json -o out.json

# 2. If the data is wrong, heal (stops at the approval gate)
brightdata scraper heal c_mp3tuab31lswoxvpws \
    "Price returns null — the selector moved; capture price + currency." \
    --url https://example.com/product/1 --pretty -o heal.json

# 3. Review heal.json's preview_result, then approve
brightdata scraper approve c_mp3tuab31lswoxvpws \
    --url https://example.com/product/1 --pretty -o approve.json

# 4. Verify the committed fix
brightdata scraper run c_mp3tuab31lswoxvpws https://example.com/product/1 --pretty

`pipelines`

搜索并运行数千个预构建的爬虫工具 API 爬虫，并取回结构化数据。爬虫列表来自 Bright Data 文档，并会缓存 24 小时。

brightdata pipelines search <query...>               # find a scraper
brightdata pipelines info <dataset_id> [method]      # its methods, or one method's input fields
brightdata pipelines run <dataset_id> <method> [urls...] [--<field> <value>...]
brightdata pipelines status <snapshot_id> [--wait]   # progress of a run
brightdata pipelines results <snapshot_id>           # records of a finished run
brightdata pipelines refresh                         # reload the scraper list now

run 将爬虫工具的输入字段作为标志；info 列出的每个字段对应一个 --<field> <value>。值会根据字段类型进行转换（数字、true/false、以逗号分隔的数组）。每个 URL 参数都会成为一条输入记录。如果存在未知字段或缺少必填字段，命令会在触发任何任务或产生费用前停止。对于每条记录不同的值或嵌套数据，请使用 --input。

标志（`run`）	说明
`--<field> <value>`	该方法的输入字段（参见 `info`）
`--input <json\|@file>`	作为 JSON 的输入记录，或指向 JSON 文件的 `@path`
`--limit-per-input <n>`	仅限 `discover_by_*`：每个输入的最大记录数（默认值：`10`）。每条记录都会计费
`--async`	输出快照 ID，而不是等待
`--format <fmt>`	`json` · `csv` · `ndjson` · `jsonl`（默认值：`json`）
`--timeout <seconds>`	等待时长（默认值：`600`）
`-o, --output <path>`	将输出写入文件
`--json` / `--pretty`	JSON 输出（原始 / 缩进）
`-k, --api-key <key>`	覆盖 API 密钥

示例

# 1. Find a scraper
brightdata pipelines search amazon reviews

# 2. See its input fields, an example and a ready-to-run command
brightdata pipelines info gd_le8e811kzy4ggddlq collect_by_url

# 3. Run it on a URL
brightdata pipelines run gd_le8e811kzy4ggddlq collect_by_url \
  "https://www.amazon.com/dp/B09V3KXJPB" --max_reviews 20 --pretty

# Input fields as flags
brightdata pipelines run gd_lwdb4vjm1ehb499uxs collect_by_url \
  --keyword laptop --url https://www.amazon.com

# Discover method, capped at 5 records per input
brightdata pipelines run gd_l7q7dkf244hwjntr0 discover_by_keyword \
  --keyword "usb c hub" --limit-per-input 5

# Several records from a file → CSV
brightdata pipelines run gd_l7q7dkf244hwjntr0 collect_by_url \
  --input @urls.json --format csv -o products.csv

# Start without waiting, then check and fetch
brightdata pipelines run gd_le8e811kzy4ggddlq collect_by_url "<url>" --async
brightdata pipelines status s_abc123xyz --wait
brightdata pipelines results s_abc123xyz --pretty

带有 error 字段的记录会说明失败的输入，例如类型错误的 URL。

0.4.0 中的变更：已移除 43 种固定管道类型（pipelines amazon_product <url>、pipelines list）以及顶层 brightdata status 命令。旧命令会输出替代命令。迁移时，使用 brightdata pipelines search <site or data type> 查找爬虫工具，然后通过 pipelines run 运行。

`browser`

控制由 Bright Data 抓取浏览器驱动的真实浏览器会话。轻量级本地守护进程会在命令之间保持浏览器连接，让你无需每次调用都重新连接即可保留状态。

brightdata browser open <url>              # Start a session and navigate
brightdata browser snapshot                # Get an accessibility tree of the page
brightdata browser screenshot [path]       # Take a PNG screenshot
brightdata browser click <ref>             # Click an element
brightdata browser type <ref> <text>       # Type into an element
brightdata browser fill <ref> <value>      # Fill a form field
brightdata browser select <ref> <value>    # Select a dropdown option
brightdata browser check <ref>             # Check a checkbox / radio
brightdata browser uncheck <ref>           # Uncheck a checkbox
brightdata browser hover <ref>             # Hover over an element
brightdata browser scroll                  # Scroll the page
brightdata browser get text [selector]     # Get text content
brightdata browser get html [selector]     # Get HTML content
brightdata browser back                    # Navigate back
brightdata browser forward                 # Navigate forward
brightdata browser reload                  # Reload the page
brightdata browser network                 # Show captured network requests
brightdata browser cookies                 # Show cookies
brightdata browser status                  # Show session state
brightdata browser sessions                # List all active sessions
brightdata browser close                   # Close session and stop daemon

全局标志（适用于每个子命令）

标志	说明
`--session <name>`	会话名称：并行运行多个隔离会话（默认值：`default`）
`--country <code>`	通过 ISO 国家/地区代码进行地理定位（例如 `us`、`de`）。在 `open` 上，更改国家/地区会重新连接浏览器
`--zone <name>`	抓取浏览器区域（默认值：`cli_browser`）
`--timeout <ms>`	IPC 命令超时时间，以毫秒为单位（默认值：`30000`）
`--idle-timeout <ms>`	空闲后自动关闭守护进程（默认值：`600000` = 10 分钟）
`--json` / `--pretty`	JSON 输出
`-o, --output <path>`	将输出写入文件
`-k, --api-key <key>`	覆盖 API 密钥

`browser open <url>`

导航至 URL。如果守护进程和浏览器会话尚未运行，则自动启动。

brightdata browser open https://example.com
brightdata browser open https://amazon.com --country us --session shop

标志	说明
`--country <code>`	地理定位。如果现有会话的国家/地区发生变化，则重新连接浏览器
`--zone <name>`	浏览器区域名称
`--idle-timeout <ms>`	此会话的守护进程空闲超时时间

`browser snapshot`

将页面捕获为文本无障碍树。这是 AI 智能体读取页面内容的主要方式：与原始 HTML 相比，可大幅节省 token。

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
brightdata browser snapshot --wrap             # Wrap output in AI-safe content boundaries

输出格式：

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]

每个交互元素都会获得一个 ref（例如 e1、e2），你可以将其传递给 click、type、fill 等。

标志	说明
`--compact`	仅包含交互元素及其祖先元素（减少 70–90% 的 token）
`--interactive`	仅包含交互元素，以扁平列表呈现
`--depth <n>`	将树深度限制为非负整数
`--selector <sel>`	将快照范围限定为匹配 CSS 选择器的元素
`--wrap`	用 `--- BRIGHTDATA_BROWSER_CONTENT ... ---` 边界包裹输出（有助于防范针对 AI 智能体的提示词注入）

`browser screenshot [path]`

捕获当前视口的 PNG 屏幕截图。

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

标志	说明
`[path]`	PNG 保存位置（默认值：临时目录）
`--full-page`	捕获整个可滚动页面，而不仅是视口
`--base64`	输出 Base64 编码的 PNG 数据，而不是保存到文件

`browser click <ref>`

通过快照 ref 点击元素。

brightdata browser click e3
brightdata browser click e3 --session shop

`browser type <ref> <text>`

在元素中输入文本。默认先清空字段。

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

标志	说明
`--append`	通过逐键模拟追加到现有值
`--submit`	输入后按 Enter

`browser fill <ref> <value>`

直接填写表单字段（不模拟键盘）。如果需要触发 keydown/keyup 事件，请使用 type。

brightdata browser fill e2 "user@example.com"

`browser select <ref> <value>`

按可见标签选择下拉选项。

brightdata browser select e4 "United States"

`browser check <ref>` / `browser uncheck <ref>`

选中或取消选中复选框或单选按钮。

brightdata browser check e7
brightdata browser uncheck e7

`browser hover <ref>`

将鼠标悬停在元素上（触发悬停状态、工具提示、下拉菜单）。

brightdata browser hover e2

`browser scroll`

滚动视口，或将元素滚动到可见区域。

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 e10 into view

标志	说明
`--direction <dir>`	`up`、`down`、`left`、`right`（默认值：`down`）
`--distance <px>`	滚动像素数（默认值：`300`）
`--ref <ref>`	将此元素滚动到可见区域，而不是滚动视口

`browser get text [selector]`

获取页面或指定范围内元素的文本内容。

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

`browser get html [selector]`

获取页面或指定范围内元素的 HTML。

brightdata browser get html              # Full page outer HTML
brightdata browser get html ".product"   # innerHTML of .product
brightdata browser get html --pretty     # JSON output with selector field

`browser network`

显示自上次导航以来捕获的 HTTP 请求。

brightdata browser network
brightdata browser network --json

输出示例：

Network Requests (5 total):
[GET] https://example.com/ => [200]
[GET] https://example.com/style.css => [200]
[POST] https://api.example.com/track => [204]

`browser cookies`

显示活动会话的 Cookie。

brightdata browser cookies
brightdata browser cookies --pretty

`browser status`

显示浏览器会话的当前状态。

brightdata browser status
brightdata browser status --session shop --pretty

`browser sessions`

列出所有活动的浏览器守护进程会话。

brightdata browser sessions
brightdata browser sessions --pretty

`browser close`

关闭会话并停止其守护进程。

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

示例：AI 智能体工作流

# Open a US-targeted session
brightdata browser open https://example.com --country us

# Read the page structure (compact for token efficiency)
brightdata browser snapshot --compact

# Interact using refs from the snapshot
brightdata browser click e3
brightdata browser type e5 "search query" --submit

# Get updated snapshot after interaction
brightdata browser snapshot --compact

# Save a screenshot for visual verification
brightdata browser screenshot ./result.png

# Done
brightdata browser close

示例：多会话对比

brightdata browser open https://amazon.com --session us --country us
brightdata browser open https://amazon.com --session de --country de

brightdata browser snapshot --session us --json > us.json
brightdata browser snapshot --session de --json > de.json

brightdata browser close --all

`zones`

列出并检查你的 Bright Data 代理区域。

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`

查看账户余额以及各区域的费用和带宽用量。只读：不会写入 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

标志	说明
`--from <datetime>`	日期范围开始时间（例如 `2024-01-01T00:00:00`）
`--to <datetime>`	日期范围结束时间
`--json` / `--pretty`	JSON 输出（原始 / 缩进）
`-k, --api-key <key>`	覆盖 API 密钥

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

将 Bright Data AI 智能体技能安装到你的编码智能体（Claude Code、Cursor、Copilot 等）。技能可为智能体提供上下文和说明，帮助其有效使用 Bright Data API。

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

可用技能

技能	说明
`search`	搜索 Google 并获取结构化 JSON 结果
`scrape`	绕过机器人检测，以干净的 Markdown 格式抓取任意网页
`data-feeds`	从 40 多个网站提取结构化数据
`bright-data-mcp`	编排 60 多个 Bright Data MCP 工具
`bright-data-best-practices`	用于编写 Bright Data 代码的参考知识库

# 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

`add mcp`

使用已由 brightdata login 存储的 API 密钥，将 Bright Data MCP 服务器条目写入 Claude Code、Cursor 或 Codex 配置文件。

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

标志	说明
`--agent <agents>`	以逗号分隔的目标：`claude-code,cursor,codex`
`--global`	安装到智能体的全局配置文件
`--project`	安装到当前项目的配置文件

配置目标

智能体	全局路径	项目路径
Claude Code	`~/.claude.json`	`.claude/settings.json`
Cursor	`~/.cursor/mcp.json`	`.cursor/mcp.json`
Codex	`$CODEX_HOME/mcp.json` 或 `~/.codex/mcp.json`	不支持

该命令会将 MCP 服务器写入 mcpServers["bright-data"]：

{
  "mcpServers": {
    "bright-data": {
      "command": "npx",
      "args": ["@brightdata/mcp"],
      "env": {
        "API_TOKEN": "<stored-api-key>"
      }
    }
  }
}

行为说明：

保留现有配置；仅添加或替换 mcpServers["bright-data"]。
如果目标配置包含无效 JSON，CLI 会发出警告，并在交互模式下询问是否覆盖。
在非交互模式下，请同时传递 --agent 和相应的作用域标志，以跳过提示。

`config`

查看和管理 CLI 配置。

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

键	说明
`default_zone_unlocker`	`scrape` 和 `search` 的默认区域
`default_zone_serp`	`search` 的默认区域（覆盖网络解锁器区域）
`default_format`	默认输出格式：`markdown` 或 `json`
`api_url`	覆盖 Bright Data API 基础 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

配置

配置存储在适合当前操作系统的位置：

操作系统	路径
macOS	`~/Library/Application Support/brightdata-cli/`
Linux	`~/.config/brightdata-cli/`
Windows	`%APPDATA%\brightdata-cli\`

会存储两个文件：

credentials.json：API 密钥
config.json：区域、输出格式、偏好设置

优先级顺序（从高到低）：

CLI flags  →  Environment variables  →  config.json  →  Defaults

环境变量

变量	说明
`BRIGHTDATA_API_KEY`	API 密钥（覆盖存储的凭据）
`BRIGHTDATA_UNLOCKER_ZONE`	默认网络解锁器区域
`BRIGHTDATA_SERP_ZONE`	默认 SERP 区域
`BRIGHTDATA_POLLING_TIMEOUT`	默认轮询超时时间，以秒为单位
`BRIGHTDATA_BROWSER_ZONE`	默认抓取浏览器区域（默认值：`cli_browser`）
`BRIGHTDATA_DAEMON_DIR`	覆盖浏览器守护进程套接字、PID 和身份验证令牌文件所使用的目录

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

输出模式

每个命令都支持：

模式	标志	行为
便于阅读	（默认）	带颜色的格式化表格或 Markdown
JSON	`--json`	将紧凑 JSON 输出到 stdout
美化 JSON	`--pretty`	将缩进 JSON 输出到 stdout
文件	`-o <path>`	写入文件；根据扩展名推断格式

自动检测的文件格式：

扩展名	格式
`.json`	JSON
`.md`	Markdown
`.html`	HTML
`.csv`	CSV

管道友好用法

当 stdout 不是 TTY 时，会自动禁用颜色和加载动画。错误输出到 stderr，数据输出到 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 run gd_l7q7dkf244hwjntr0 collect_by_url \
  "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

故障排除

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

在 Bright Data 控制面板中检查区域权限。

Error: Rate limit exceeded

稍等片刻后重试。对于大型任务，请使用 --async 以避免超时。

异步任务速度过慢

brightdata pipelines run <dataset_id> <method> <url> --timeout 1200
# or
export BRIGHTDATA_POLLING_TIMEOUT=1200

No active browser session "default"

# Start a session first
brightdata browser open https://example.com

浏览器守护进程无法启动

# Check if a stale socket file exists and clear it
brightdata browser close
# Then retry
brightdata browser open https://example.com

交互后找不到元素 ref

每次调用 snapshot 时都会重新分配 ref。如果你进行导航或点击（可能导致页面变化），请先获取新快照，再次使用 ref：

brightdata browser click e3
brightdata browser snapshot --compact   # refresh refs
brightdata browser type e5 "text"

非交互式终端中的输出乱码

非 TTY 环境会自动禁用颜色和加载动画。如果仍能看到 ANSI 代码，请在命令末尾添加 | cat。

Name		Name	Last commit message	Last commit date
.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

Latest commit

History

Folders and files

Repository files navigation

Bright Data CLI

概述

目录

安装

macOS / Linux

Windows

或在任意平台上手动安装

快速开始

身份验证

免费套餐

命令

init

scrape

search

discover

scraper create

输出封装（-o create.json）

并发任务上限与自动退避

scraper run

scraper heal

scraper approve

pipelines

browser

browser open <url>

browser snapshot

browser screenshot [path]

browser click <ref>

browser type <ref> <text>

browser fill <ref> <value>

browser select <ref> <value>

browser check <ref> / browser uncheck <ref>

browser hover <ref>

browser scroll

browser get text [selector]

browser get html [selector]

browser network

browser cookies

browser status

browser sessions

browser close

zones

budget

skill

add mcp

config

login / logout

配置