brightdata-cli

Bright Data CLI

Bright Data CLI（brightdata または bdata）を使うと、ターミナルから Bright Data のウェブデータプラットフォームにフルアクセスできます。認証、プロキシゾーン、アンチボット回避、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 エージェントのスキルをインストールする
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

レコードごとに課金されます。まずは入力を 1 件にしてください。不明な必須フィールドや不足している必須フィールドがある場合、実行開始前に失敗します。

ステータスの確認

--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 エージェントスキルのインストール

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

# Install a specific skill
bdata skill add scrape

# List available skills
bdata skill list

出力モード

すべてのコマンドで、複数の出力形式を利用できます。

フラグ	効果
(none)	色付きの読みやすい形式で出力する
--json	標準出力にコンパクトな JSON を出力する
--pretty	標準出力にインデント付き JSON を出力する
-o <path>	ファイルに書き込む（拡張子から形式を自動判定）

パイプで出力する場合（標準出力が 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 経由で使用できます。