跳转到主要内容

​
安装 CLI

运行 Bright Data CLI 最快的方式是使用 npx，它会执行最新版本，无需全局安装： 
npx -p @brightdata/cli brightdata --version
在本文档的任意命令前加上 npx -p @brightdata/cli 即可以同样的方式运行，无需维护任何全局依赖。Bright Data CLI 需要 Node.js 20 或更高版本。 如果希望获得持久可用的 brightdata 命令和更快的启动速度，请改为全局安装 CLI： 
npm install -g @brightdata/cli
验证全局安装： 
brightdata --version
快捷别名 bdata 同样可用，既可通过 npx -p @brightdata/cli bdata 使用，也可在全局安装后使用 - 使用您喜欢的任何一个。

​
更新 CLI

使用与安装时相同的包管理器升级到最新版本： 
npm install -g @brightdata/cli@latest
将已安装版本与 npm 上发布的最新版本进行对比： 
brightdata --version               # 您已安装的版本
npm view @brightdata/cli version   # npm 上的最新版本
新命令会随 CLI 版本发布。例如，scraper heal 和 scraper approve 在 v0.3.1 中加入。运行上面的更新命令即可获取它们。各版本的变更详情参见发布说明。

​
身份验证

运行登录命令以连接您的 Bright Data 帐户： 
brightdata login
这将打开您的浏览器进行安全的 OAuth 身份验证。完成后，CLI 将：
  1. 验证并在本地存储您的 API 密钥
  2. 自动创建所需的代理区域（cli_unlocker、cli_browser）
  3. 设置合理的默认值，以便您立即开始
您只需登录一次。所有后续命令都会自动进行身份验证。

​
替代身份验证方法

当没有可用的浏览器时，使用设备流：
brightdata login --device
这会打印一个 URL 和一个代码。在任何设备上打开该 URL，输入代码，CLI 即可完成身份验证。
对于 CI/CD 管道或非交互式环境，直接传递您的 API 密钥：
brightdata login --api-key YOUR_API_KEY
您可以在 Bright Data 控制面板 中找到您的 API 密钥。
设置 BRIGHTDATA_API_KEY 环境变量以完全跳过登录：
export BRIGHTDATA_API_KEY=YOUR_API_KEY
这对 Docker 容器、GitHub Actions 和其他自动化环境很有用。

​
交互式设置向导

为了获得引导式的首次体验，请使用 init 命令： 
brightdata init
这将逐步引导您完成身份验证、区域选择和默认配置。
标志描述
--skip-auth跳过身份验证步骤（如果已登录）
-k, --api-key <key>直接提供 API 密钥

​
验证您的设置

登录后，确认一切正常工作： 
# 检查您的配置
brightdata config

# 验证 API 连接
brightdata budget

# 尝试快��抓取
brightdata scrape https://example.com

​
配置存储

CLI 在本地存储凭证和配置：
操作系统路径
macOS~/Library/Application Support/brightdata-cli/
Linux~/.config/brightdata-cli/
Windows%APPDATA%\brightdata-cli\
创建两个文件：
文件用途权限
credentials.jsonAPI 密钥0o600（仅限所有者）
config.json区域、输出格式、偏好设置标准
配置的优先级顺序： CLI 标志 → 环境变量 → config.json → 默认值。您始终可以逐个命令覆盖任何设置。

​
后续步骤

命令

探索完整的命令参考。

使用示例

跳转到真实工作流和配方。