![\"Bright](\"https://raw.githubusercontent.com/brightdata/cli/main/assets/banner.gif\")
\n\n \n
\n Scrape, search, and extract structured web data — directly from your terminal.\n
\n\n\n ![\"npm](\"https://img.shields.io/npm/v/%40brightdata%2Fcli?color=black&label=npm\")
![\"node](\"https://img.shields.io/badge/node-%3E%3D20-black\"){kind=icon}
![\"license\"](\"https://img.shields.io/badge/license-MIT-black\"){kind=icon}
` | Geo-target by ISO country code (e.g. `us`, `de`, `jp`) |\n| `--zone ` | Web Unlocker zone name |\n| `--mobile` | Use a mobile user agent |\n| `--async` | Submit async job, return a snapshot ID |\n| `-o, --output ` | Write output to file |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `-k, --api-key ` | Override API key |\n\n**Examples**\n\n```bash\n# Scrape as markdown (default)\nbrightdata scrape https://news.ycombinator.com\n\n# Scrape as raw HTML\nbrightdata scrape https://example.com -f html\n\n# US geo-targeting, save to file\nbrightdata scrape https://amazon.com -f json --country us -o product.json\n\n# Pipe to a markdown viewer\nbrightdata scrape https://docs.github.com | glow -\n\n# Async — returns a snapshot ID you can poll with `status`\nbrightdata scrape https://example.com --async\n```\n\n---\n\n### `search`\n\nSearch Google, Bing, or Yandex via Bright Data's SERP API. Google results include structured data (organic results, ads, people-also-ask, related searches).\n\n```bash\nbrightdata search [options]\n```\n\n| Flag | Description |\n|---|---|\n| `--engine ` | `google` · `bing` · `yandex` (default: `google`) |\n| `--country ` | Localized results (e.g. `us`, `de`) |\n| `--language ` | Language code (e.g. `en`, `fr`) |\n| `--page ` | Page number, 0-indexed (default: `0`) |\n| `--type ` | `web` · `news` · `images` · `shopping` (default: `web`) |\n| `--device ` | `desktop` · `mobile` |\n| `--zone ` | SERP zone name |\n| `-o, --output ` | Write output to file |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `-k, --api-key ` | Override API key |\n\n**Examples**\n\n```bash\n# Formatted table output (default)\nbrightdata search \"typescript best practices\"\n\n# German localized results\nbrightdata search \"restaurants berlin\" --country de --language de\n\n# News search\nbrightdata search \"AI regulation\" --type news\n\n# Page 2 of results\nbrightdata search \"web scraping\" --page 1\n\n# Extract just the URLs\nbrightdata search \"open source scraping\" --json | jq -r '.organic[].link'\n\n# Search Bing\nbrightdata search \"bright data pricing\" --engine bing\n```\n\n---\n\n### `discover`\n\nAI-powered web discovery. Submit a query with optional intent, and Bright Data finds, ranks, and optionally extracts full-page content for each result.\n\n```bash\nbrightdata discover [options]\n```\n\n| Flag | Description |\n|---|---|\n| `--intent ` | AI intent to evaluate and rank result relevance |\n| `--country ` | ISO country code (default: `US`) |\n| `--city ` | City for localized results (e.g. `\"New York\"`) |\n| `--language ` | Language code (default: `en`) |\n| `--num-results ` | Number of results to return |\n| `--filter-keywords ` | Comma-separated keywords that must appear in results |\n| `--include-content` | Include full page content in each result |\n| `--no-remove-duplicates` | Keep duplicate results |\n| `--start-date ` | Only content updated from date (`YYYY-MM-DD`) |\n| `--end-date ` | Only content updated until date (`YYYY-MM-DD`) |\n| `--timeout ` | Polling timeout (default: `600`) |\n| `-o, --output ` | Write output to file |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `-k, --api-key ` | Override API key |\n\n**Examples**\n\n```bash\n# Basic discovery — table output\nbrightdata discover \"AI trends\"\n\n# With AI intent for relevance ranking\nbrightdata discover \"AI trends\" \\\n --intent \"Prioritize institutional reports for VC research\"\n\n# Include full page content as markdown\nbrightdata discover \"AI trends\" --include-content --num-results 5\n\n# Geo-targeted with date range\nbrightdata discover \"best restaurants\" --country US --city \"New York\" \\\n --start-date 2025-01-01 --end-date 2025-12-31\n\n# Filter results by keywords\nbrightdata discover \"generative AI SaaS\" --filter-keywords \"revenue,SaaS\"\n\n# JSON output to file\nbrightdata discover \"AI trends\" --num-results 10 --pretty -o results.json\n\n# Pipe-friendly — redirected stdout outputs JSON automatically\nbrightdata discover \"AI trends\" --include-content --num-results 3 > results.json\n```\n\n---\n\n### `scraper create`\n\nBuild a Bright Data scraper from a natural-language description using AI.\n\n```bash\nbrightdata scraper create [options]\n```\n\n| Flag | Description |\n|---|---|\n| `--name ` | Scraper template name (default: `cli-scraper-`) |\n| `--deliver-webhook ` | Webhook URL for the deliver stub (default: `https://example.com/webhook`) |\n| `--timeout ` | Polling timeout in seconds (default: `600`) |\n| `--max-retries ` | Max retries on the AI-Flow concurrent-job cap 429 (default: `4`). See below. |\n| `--no-retry` | Fail immediately on 429 instead of waiting. Same as `--max-retries 0`. |\n| `-o, --output ` | Write the JSON envelope to a file (see below) |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `--legacy-output` | Write the pre-v0.3 bare AI-progress payload to `-o` instead of the envelope. Migration only. |\n| `--timing` | Show request timing |\n| `-k, --api-key ` | Override API key |\n\n> **Note:** The scraper is created with a placeholder webhook delivery target (`https://example.com/webhook`). You can reconfigure the actual delivery endpoint in the [Bright Data web UI](https://brightdata.com/cp/scrapers) after creation.\n\n#### Output envelope (`-o create.json`)\n\nEvery termination path — success or failure — writes the same JSON envelope shape:\n\n```json\n{\n \"collector_id\": \"c_mp7x8a9b2c0d1e2f\",\n \"name\": \"my-product-scraper\",\n \"status\": \"done\",\n \"completed_steps\": [\"prepare_intent_analyzer\", \"planner\", \"...\"],\n \"view_url\": \"https://brightdata.com/cp/scrapers/c_mp7x8a9b2c0d1e2f\",\n \"created_at\": \"2026-05-18T07:28:30Z\"\n}\n```\n\nOn failure paths the envelope adds an `error` field and the `status` reflects the failure category (`ai_trigger_failed`, `failed`, `poll_failed`). The `collector_id` and `view_url` are still present so you can recover or inspect the half-built scraper.\n\nThis makes the documented chain in [recipes.md](https://github.com/brightdata/skills/blob/main/skills/scraper-studio/references/recipes.md) work as written:\n\n```bash\nbrightdata scraper create https://example.com/product/1 \"...\" \\\n -o create.json\nCOLLECTOR_ID=$(jq -r '.collector_id' create.json)\nbrightdata scraper run \"$COLLECTOR_ID\" https://example.com/product/2\n```\n\n> The file format follows the `-o` extension, so `.json` is written compact (ideal for `jq`). Use `--pretty` for indented JSON on stdout when you omit `-o`.\n\nUse `--legacy-output` if you have an existing script that depended on the pre-v0.3 bare-progress shape; the flag is supported for one minor version while you migrate.\n\n#### Concurrent-job cap & auto-backoff\n\nThe Bright Data AI Flow caps concurrent `scraper create` generations per account (currently 3). If you exceed it, the API returns `429 Cannot run more than N jobs in parallel`. The CLI handles this automatically: it waits with exponential backoff + jitter and retries up to `--max-retries` times (default 4). During the wait the CLI prints status lines so you know it isn't hung:\n\n```\nTriggering AI generation...\nHit AI-Flow concurrent-job cap (429). Waiting 32s before retry 1/4...\nHit AI-Flow concurrent-job cap (429). Waiting 67s before retry 2/4...\nGenerating scraper...\n```\n\nIf the cap is still hit after all retries, the CLI exits with a stderr note pointing at the half-built collector's dashboard URL so you can inspect or delete it manually (Bright Data does not yet expose programmatic collector deletion).\n\nUse `--no-retry` if you want the old fail-fast behavior — typically for scripts that prefer to handle backoff themselves.\n\n**Examples**\n\n```bash\n# Build a scraper for a product page\nbrightdata scraper create https://example.com/product/1 \\\n \"Extract title, price, and image URL from this product page\"\n\n# Name the scraper and save the envelope to a file\nbrightdata scraper create https://example.com/product/1 \\\n \"Extract title, price, and image URL from this product page\" \\\n --name my-product-scraper -o create.json\n\n# Capture the collector_id for chaining\nCOLLECTOR_ID=$(jq -r '.collector_id' create.json)\n\n# Fan out 10 parallel creates — the CLI serialises automatically via 429 backoff\nfor url in $(cat urls.txt); do\n brightdata scraper create \"$url\" \"Extract title, price, ...\" \\\n --name \"scraper-$(basename $url)\" &\ndone; wait\n\n# Disable the auto-backoff (fail fast on 429)\nbrightdata scraper create https://example.com/product/1 \\\n \"Extract title, price, and image URL from this product page\" \\\n --no-retry\n\n# Use a custom webhook delivery URL\nbrightdata scraper create https://example.com/product/1 \\\n \"Extract title, price, and image URL from this product page\" \\\n --deliver-webhook https://my-app.com/ingest\n```\n\n---\n\n### `scraper run`\n\nRun a scraper (built with `scraper create` or in the web UI) against one or more URLs and get the extracted data.\n\n```bash\nbrightdata scraper run [url] [options]\n```\n\nProvide URLs in exactly one of three ways:\n\n- Positional `` — single URL (legacy form, unchanged).\n- `--urls ` — comma-separated list.\n- `--input-file ` — file with one URL per line, **or** a JSON array of URL strings, **or** a JSON array of `{\"url\": \"...\"}` objects.\n\n| Flag | Description |\n|---|---|\n| `--urls ` | Comma-separated list of URLs (multi-URL batch path) |\n| `--input-file ` | File with URLs (txt one-per-line, or JSON array) |\n| `--sync` | Use the synchronous `/dca/crawl` endpoint (single-URL only, server-side cap of 25–50s) |\n| `--sync-timeout ` | Sync-mode server timeout, `25`–`50` (default: `50`) |\n| `--timeout ` | Polling timeout (default: `600` single-URL, `3600` batch) |\n| `--name ` | Human-readable job name |\n| `--version ` | Scraper version (e.g. `dev`) |\n| `-o, --output ` | Write output to file |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `--timing` | Show request timing |\n| `-k, --api-key ` | Override API key |\n\n**Routing**\n\n- **Single URL** (positional, or one entry via `--urls` / `--input-file`) → async flow: `/dca/trigger_immediate` → poll `/dca/get_result`. Use `--sync` for `/dca/crawl` (one-shot, 25–50s).\n- **Multiple URLs** (`--urls` / `--input-file` with 2+ entries) → single POST to `/dca/trigger` with an array body, one `collection_id`, polled via `/dca/dataset`. This mirrors the canonical batch shape used by the reference SDKs ([`triggerWithUrls`](https://github.com/brightdata/bright-data-scraper-studio-nodejs-project) / [`trigger_with_urls`](https://github.com/brightdata/bright-data-scraper-studio-python-project)). `--sync` is incompatible with multi-URL — `/dca/crawl` accepts only a single URL.\n\nIf a single URL expands to more pages than the realtime job limit allows (paginated listings, infinite scroll), the CLI automatically falls back to the batch endpoint and prints a one-line notice. No flag required.\n\n**Examples**\n\n```bash\n# Default: async + poll until results arrive\nbrightdata scraper run c_mp3tuab31lswoxvpws https://www.amazon.com/dp/B08N5WRWNW\n\n# Save pretty-printed results to a file\nbrightdata scraper run c_mp3tuab31lswoxvpws https://www.amazon.com/dp/B08N5WRWNW \\\n --pretty -o product.json\n\n# Sync mode for fast pages\nbrightdata scraper run c_mp3tuab31lswoxvpws https://example.com/p/1 --sync\n\n# Sync with a shorter server timeout and a job name\nbrightdata scraper run c_mp3tuab31lswoxvpws https://example.com/p/1 \\\n --sync --sync-timeout 30 --name first-test\n\n# Multi-URL batch — one API call, one snapshot, one merged result array\nbrightdata scraper run c_mp3tuab31lswoxvpws \\\n --urls \"https://example.com/p/1,https://example.com/p/2,https://example.com/p/3\" \\\n --pretty -o products.json\n\n# Multi-URL from a file (one URL per line; # comments and blank lines skipped)\nbrightdata scraper run c_mp3tuab31lswoxvpws --input-file urls.txt -o products.json\n\n# Multi-URL from a JSON array\necho '[\"https://example.com/p/1\",\"https://example.com/p/2\"]' > urls.json\nbrightdata scraper run c_mp3tuab31lswoxvpws --input-file urls.json\n```\n\n---\n\n### `scraper heal`\n\nFix an existing scraper **in place** when it ran but returned wrong, empty, or partial data. The `collector_id` stays the same — the scraper is improved, not replaced. This is the maintenance twin of `scraper create`: it triggers Bright Data's AI self-healing flow (`POST /dca/collectors/{id}/refactor_template`), then polls progress.\n\n```bash\nbrightdata scraper heal \"\" [options]\n```\n\n**You are the detector.** The CLI never decides on its own that a scraper is broken — you inspect the run output and decide. The `` is required (max 1000 chars); name exactly what is wrong and what the correct output should be. Vague prompts produce vague heals.\n\n| Flag | Description |\n|---|---|\n| `--url ` | Verify target woven into the success `next_step` hint (not sent to the heal call) |\n| `--auto-approve` | When the heal hits the approval gate, approve it automatically and poll through to `done` (default: stop and let you review) |\n| `--timeout ` | Polling timeout (default: `600`) |\n| `--max-retries ` | Max retries on the AI-Flow concurrent-job-cap `429` (default: `4`) |\n| `--no-retry` | Fail immediately on `429` instead of waiting through the cap |\n| `-o, --output ` | Write output to file |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `--legacy-output` | Emit the bare AI-progress payload instead of the envelope |\n| `--timing` | Show request timing |\n| `-k, --api-key ` | Override API key |\n\n**The approval gate**\n\nSelf-healing is human-in-the-loop. Without `--auto-approve`, `heal` runs the fix and then **stops at an approval gate** rather than committing it, exiting `0` with a `status: \"awaiting_approval\"` envelope:\n\n```json\n{\n \"collector_id\": \"c_mp3tuab31lswoxvpws\",\n \"status\": \"awaiting_approval\",\n \"prompt\": \"Price returns null — the selector moved …\",\n \"preview_result\": [ { \"title\": \"…\", \"price\": { \"value\": 51.77, \"currency\": \"GBP\" } }, … ],\n \"diff_summary\": \"proposed template has 1 step(s) — review at view_url\",\n \"view_url\": \"https://brightdata.com/cp/scrapers/c_mp3tuab31lswoxvpws\",\n \"next_step\": \"bdata scraper approve c_mp3tuab31lswoxvpws --url https://example.com/product/1\"\n}\n```\n\n`preview_result` shows the sample rows the fixed scraper would produce — review them, then run the `next_step` (`scraper approve`) to commit. `awaiting_approval` is **not** a failure; it means the fix is ready and waiting for your decision. A failed heal (`429` cap exhausted, timeout, terminal `failed`) is **non-destructive** — the existing scraper is unchanged and still works as before.\n\n**Examples**\n\n```bash\n# Heal a scraper, stop at the gate, and get a ready-to-run verify command back\nbrightdata scraper heal c_mp3tuab31lswoxvpws \\\n \"The price field returns null — the selector moved into a span with \\\n data-testid. Capture price and currency again.\" \\\n --url https://example.com/product/1 --pretty -o heal.json\n\n# Fully autonomous: heal and approve in one command (no manual review)\nbrightdata scraper heal c_mp3tuab31lswoxvpws \\\n \"Reviews stopped extracting after the page redesign\" --auto-approve\n```\n\n---\n\n### `scraper approve`\n\nCommit (or reject) a self-healing fix that `scraper heal` left **awaiting approval**. Calls `POST /dca/collectors/{id}/resume_automation_job`, then polls the refactor job to `done`.\n\n```bash\nbrightdata scraper approve [options]\n```\n\n| Flag | Description |\n|---|---|\n| `--reject` | Reject the proposed fix instead of approving it |\n| `--url ` | Verify target woven into the success `next_step` hint |\n| `--timeout ` | Polling timeout (default: `600`) |\n| `-o, --output ` | Write output to file |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `--legacy-output` | Emit the bare AI-progress payload instead of the envelope |\n| `--timing` | Show request timing |\n| `-k, --api-key ` | Override API key |\n\nOn success the job advances to `status: \"done\"` and the envelope hands back a `next_step` = `scraper run ` so you can verify the committed fix. `--reject` discards the proposed fix (`status: \"rejected\"`) — re-run `scraper heal` with a sharper prompt to try again. If a heal needs multiple approvals, `approve` may stop at `awaiting_approval` again — just run it once more.\n\n**The self-healing loop**\n\n```bash\n# 1. Run and inspect the data\nbrightdata scraper run c_mp3tuab31lswoxvpws https://example.com/product/1 --json -o out.json\n\n# 2. If the data is wrong, heal (stops at the approval gate)\nbrightdata scraper heal c_mp3tuab31lswoxvpws \\\n \"Price returns null — the selector moved; capture price + currency.\" \\\n --url https://example.com/product/1 --pretty -o heal.json\n\n# 3. Review heal.json's preview_result, then approve\nbrightdata scraper approve c_mp3tuab31lswoxvpws \\\n --url https://example.com/product/1 --pretty -o approve.json\n\n# 4. Verify the committed fix\nbrightdata scraper run c_mp3tuab31lswoxvpws https://example.com/product/1 --pretty\n```\n\n---\n\n### `pipelines`\n\nExtract structured data from 40+ platforms using Bright Data's Web Scraper API. Triggers an async collection job, polls until ready, and returns results.\n\n```bash\nbrightdata pipelines [params...] [options]\n```\n\n| Flag | Description |\n|---|---|\n| `--format ` | `json` · `csv` · `ndjson` · `jsonl` (default: `json`) |\n| `--timeout ` | Polling timeout (default: `600`) |\n| `-o, --output ` | Write output to file |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `-k, --api-key ` | Override API key |\n\n```bash\n# List all available dataset types\nbrightdata pipelines list\n```\n\n**Examples**\n\n```bash\n# LinkedIn profile\nbrightdata pipelines linkedin_person_profile \"https://linkedin.com/in/username\"\n\n# Amazon product → CSV\nbrightdata pipelines amazon_product \"https://amazon.com/dp/B09V3KXJPB\" \\\n --format csv -o product.csv\n\n# Instagram profile\nbrightdata pipelines instagram_profiles \"https://instagram.com/username\"\n\n# Amazon search by keyword\nbrightdata pipelines amazon_product_search \"laptop\" \"https://amazon.com\"\n\n# Google Maps reviews\nbrightdata pipelines google_maps_reviews \"https://maps.google.com/...\" 7\n\n# YouTube comments (top 50)\nbrightdata pipelines youtube_comments \"https://youtube.com/watch?v=...\" 50\n```\n\nSee [Dataset Types Reference](#dataset-types-reference) for the full list.\n\n---\n\n### `browser`\n\nControl a real browser session powered by [Bright Data's Scraping Browser](https://brightdata.com/products/scraping-browser). A lightweight local daemon holds the browser connection open between commands, giving you persistent state without reconnecting on every call.\n\n```bash\nbrightdata browser open # Start a session and navigate\nbrightdata browser snapshot # Get an accessibility tree of the page\nbrightdata browser screenshot [path] # Take a PNG screenshot\nbrightdata browser click # Click an element\nbrightdata browser type # Type into an element\nbrightdata browser fill # Fill a form field\nbrightdata browser select # Select a dropdown option\nbrightdata browser check # Check a checkbox / radio\nbrightdata browser uncheck # Uncheck a checkbox\nbrightdata browser hover # Hover over an element\nbrightdata browser scroll # Scroll the page\nbrightdata browser get text [selector] # Get text content\nbrightdata browser get html [selector] # Get HTML content\nbrightdata browser back # Navigate back\nbrightdata browser forward # Navigate forward\nbrightdata browser reload # Reload the page\nbrightdata browser network # Show captured network requests\nbrightdata browser cookies # Show cookies\nbrightdata browser status # Show session state\nbrightdata browser sessions # List all active sessions\nbrightdata browser close # Close session and stop daemon\n```\n\n**Global flags** (work with every subcommand)\n\n| Flag | Description |\n|---|---|\n| `--session ` | Session name — run multiple isolated sessions in parallel (default: `default`) |\n| `--country ` | Geo-target by ISO country code (e.g. `us`, `de`). On `open`, changing country reconnects the browser |\n| `--zone ` | Scraping Browser zone (default: `cli_browser`) |\n| `--timeout ` | IPC command timeout in milliseconds (default: `30000`) |\n| `--idle-timeout ` | Daemon auto-shutdown after idle (default: `600000` = 10 min) |\n| `--json` / `--pretty` | JSON output |\n| `-o, --output ` | Write output to file |\n| `-k, --api-key ` | Override API key |\n\n---\n\n#### `browser open `\n\nNavigate to a URL. Starts the daemon and browser session automatically if not already running.\n\n```bash\nbrightdata browser open https://example.com\nbrightdata browser open https://amazon.com --country us --session shop\n```\n\n| Flag | Description |\n|---|---|\n| `--country ` | Geo-targeting. Reconnects the browser if the country changes on an existing session |\n| `--zone ` | Browser zone name |\n| `--idle-timeout ` | Daemon idle timeout for this session |\n\n---\n\n#### `browser snapshot`\n\nCapture the page as a text accessibility tree. This is the primary way AI agents read page content — far more token-efficient than raw HTML.\n\n```bash\nbrightdata browser snapshot\nbrightdata browser snapshot --compact # Interactive elements + ancestors only\nbrightdata browser snapshot --interactive # Interactive elements as a flat list\nbrightdata browser snapshot --depth 3 # Limit tree depth\nbrightdata browser snapshot --selector \"main\" # Scope to a CSS subtree\nbrightdata browser snapshot --wrap # Wrap output in AI-safe content boundaries\n```\n\n**Output format:**\n```\nPage: Example Domain\nURL: https://example.com\n\n- heading \"Example Domain\" [level=1]\n- paragraph \"This domain is for use in illustrative examples.\"\n- link \"More information...\" [ref=e1]\n```\n\nEach interactive element gets a `ref` (e.g. `e1`, `e2`) that you pass to `click`, `type`, `fill`, etc.\n\n| Flag | Description |\n|---|---|\n| `--compact` | Only interactive elements and their ancestors (70–90% fewer tokens) |\n| `--interactive` | Only interactive elements, as a flat list |\n| `--depth ` | Limit tree depth to a non-negative integer |\n| `--selector ` | Scope snapshot to elements matching a CSS selector |\n| `--wrap` | Wrap output in `--- BRIGHTDATA_BROWSER_CONTENT ... ---` boundaries (useful for AI agent prompt injection safety) |\n\n---\n\n#### `browser screenshot [path]`\n\nCapture a PNG screenshot of the current viewport.\n\n```bash\nbrightdata browser screenshot\nbrightdata browser screenshot ./result.png\nbrightdata browser screenshot --full-page -o page.png\nbrightdata browser screenshot --base64\n```\n\n| Flag | Description |\n|---|---|\n| `[path]` | Where to save the PNG (default: temp directory) |\n| `--full-page` | Capture the full scrollable page, not just the viewport |\n| `--base64` | Output base64-encoded PNG data instead of saving to a file |\n\n---\n\n#### `browser click `\n\nClick an element by its snapshot ref.\n\n```bash\nbrightdata browser click e3\nbrightdata browser click e3 --session shop\n```\n\n---\n\n#### `browser type `\n\nType text into an element. Clears the field first by default.\n\n```bash\nbrightdata browser type e5 \"search query\"\nbrightdata browser type e5 \" more text\" --append # Append to existing value\nbrightdata browser type e5 \"search query\" --submit # Press Enter after typing\n```\n\n| Flag | Description |\n|---|---|\n| `--append` | Append to existing value using key-by-key simulation |\n| `--submit` | Press Enter after typing |\n\n---\n\n#### `browser fill `\n\nFill a form field directly (no keyboard simulation). Use `type` if you need to trigger `keydown`/`keyup` events.\n\n```bash\nbrightdata browser fill e2 \"user@example.com\"\n```\n\n---\n\n#### `browser select `\n\nSelect a dropdown option by its visible label.\n\n```bash\nbrightdata browser select e4 \"United States\"\n```\n\n---\n\n#### `browser check ` / `browser uncheck `\n\nCheck or uncheck a checkbox or radio button.\n\n```bash\nbrightdata browser check e7\nbrightdata browser uncheck e7\n```\n\n---\n\n#### `browser hover `\n\nHover the mouse over an element (triggers hover states, tooltips, dropdowns).\n\n```bash\nbrightdata browser hover e2\n```\n\n---\n\n#### `browser scroll`\n\nScroll the viewport or scroll an element into view.\n\n```bash\nbrightdata browser scroll # Scroll down 300px (default)\nbrightdata browser scroll --direction up\nbrightdata browser scroll --direction down --distance 600\nbrightdata browser scroll --ref e10 # Scroll element e10 into view\n```\n\n| Flag | Description |\n|---|---|\n| `--direction ` | `up`, `down`, `left`, `right` (default: `down`) |\n| `--distance ` | Pixels to scroll (default: `300`) |\n| `--ref ` | Scroll this element into view instead of the viewport |\n\n---\n\n#### `browser get text [selector]`\n\nGet the text content of the page or a scoped element.\n\n```bash\nbrightdata browser get text # Full page text\nbrightdata browser get text \"h1\" # Text of the first h1\nbrightdata browser get text \"#price\" # Text inside #price\n```\n\n---\n\n#### `browser get html [selector]`\n\nGet the HTML of the page or a scoped element.\n\n```bash\nbrightdata browser get html # Full page outer HTML\nbrightdata browser get html \".product\" # innerHTML of .product\nbrightdata browser get html --pretty # JSON output with selector field\n```\n\n---\n\n#### `browser network`\n\nShow HTTP requests captured since the last navigation.\n\n```bash\nbrightdata browser network\nbrightdata browser network --json\n```\n\n**Example output:**\n```\nNetwork Requests (5 total):\n[GET] https://example.com/ => [200]\n[GET] https://example.com/style.css => [200]\n[POST] https://api.example.com/track => [204]\n```\n\n---\n\n#### `browser cookies`\n\nShow cookies for the active session.\n\n```bash\nbrightdata browser cookies\nbrightdata browser cookies --pretty\n```\n\n---\n\n#### `browser status`\n\nShow the current state of a browser session.\n\n```bash\nbrightdata browser status\nbrightdata browser status --session shop --pretty\n```\n\n---\n\n#### `browser sessions`\n\nList all active browser daemon sessions.\n\n```bash\nbrightdata browser sessions\nbrightdata browser sessions --pretty\n```\n\n---\n\n#### `browser close`\n\nClose a session and stop its daemon.\n\n```bash\nbrightdata browser close # Close the default session\nbrightdata browser close --session shop # Close a named session\nbrightdata browser close --all # Close all active sessions\n```\n\n---\n\n**Example: AI agent workflow**\n\n```bash\n# Open a US-targeted session\nbrightdata browser open https://example.com --country us\n\n# Read the page structure (compact for token efficiency)\nbrightdata browser snapshot --compact\n\n# Interact using refs from the snapshot\nbrightdata browser click e3\nbrightdata browser type e5 \"search query\" --submit\n\n# Get updated snapshot after interaction\nbrightdata browser snapshot --compact\n\n# Save a screenshot for visual verification\nbrightdata browser screenshot ./result.png\n\n# Done\nbrightdata browser close\n```\n\n**Example: multi-session comparison**\n\n```bash\nbrightdata browser open https://amazon.com --session us --country us\nbrightdata browser open https://amazon.com --session de --country de\n\nbrightdata browser snapshot --session us --json > us.json\nbrightdata browser snapshot --session de --json > de.json\n\nbrightdata browser close --all\n```\n\n---\n\n### `status`\n\nCheck the status of an async snapshot job (returned by `--async` or `pipelines`).\n\n```bash\nbrightdata status [options]\n```\n\n| Flag | Description |\n|---|---|\n| `--wait` | Poll until the job completes |\n| `--timeout ` | Polling timeout (default: `600`) |\n| `-o, --output ` | Write output to file |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `-k, --api-key ` | Override API key |\n\n```bash\n# Check current status\nbrightdata status s_abc123xyz\n\n# Block until complete\nbrightdata status s_abc123xyz --wait --pretty\n\n# Custom timeout (5 minutes)\nbrightdata status s_abc123xyz --wait --timeout 300\n```\n\n---\n\n### `zones`\n\nList and inspect your Bright Data proxy zones.\n\n```bash\nbrightdata zones # List all active zones\nbrightdata zones info # Show full details for a zone\n```\n\n```bash\n# Export all zones as JSON\nbrightdata zones --json -o zones.json\n\n# Inspect a specific zone\nbrightdata zones info my_unlocker_zone --pretty\n```\n\n---\n\n### `budget`\n\nView your account balance and per-zone cost and bandwidth usage. Read-only — no writes to the API.\n\n```bash\nbrightdata budget # Show account balance (quick view)\nbrightdata budget balance # Account balance + pending charges\nbrightdata budget zones # Cost & bandwidth table for all zones\nbrightdata budget zone # Detailed cost & bandwidth for one zone\n```\n\n| Flag | Description |\n|---|---|\n| `--from ` | Start of date range (e.g. `2024-01-01T00:00:00`) |\n| `--to ` | End of date range |\n| `--json` / `--pretty` | JSON output (raw / indented) |\n| `-k, --api-key ` | Override API key |\n\n```bash\n# Current account balance\nbrightdata budget\n\n# Zone costs for January 2024\nbrightdata budget zones --from 2024-01-01T00:00:00 --to 2024-02-01T00:00:00\n\n# Detailed view of a specific zone\nbrightdata budget zone my_unlocker_zone\n```\n\n---\n\n### `skill`\n\nInstall Bright Data AI agent skills into your coding agent (Claude Code, Cursor, Copilot, etc.). Skills provide your agent with context and instructions for using Bright Data APIs effectively.\n\n```bash\nbrightdata skill add # Interactive picker — choose skill + agent\nbrightdata skill add # Install a specific skill directly\nbrightdata skill list # List all available Bright Data skills\n```\n\n**Available skills**\n\n| Skill | Description |\n|---|---|\n| `search` | Search Google and get structured JSON results |\n| `scrape` | Scrape any webpage as clean markdown with bot bypass |\n| `data-feeds` | Extract structured data from 40+ websites |\n| `bright-data-mcp` | Orchestrate 60+ Bright Data MCP tools |\n| `bright-data-best-practices` | Reference knowledge base for writing Bright Data code |\n\n```bash\n# Interactive — select skills and choose which agents to install to\nbrightdata skill add\n\n# Install the scrape skill directly\nbrightdata skill add scrape\n\n# See what's available\nbrightdata skill list\n```\n\n---\n\n### `add mcp`\n\nWrite a Bright Data MCP server entry into Claude Code, Cursor, or Codex config files using the API key already stored by `brightdata login`.\n\n```bash\nbrightdata add mcp # Interactive agent + scope prompts\nbrightdata add mcp --agent claude-code --global\nbrightdata add mcp --agent claude-code,cursor --project\nbrightdata add mcp --agent codex --global\n```\n\n| Flag | Description |\n|---|---|\n| `--agent ` | Comma-separated targets: `claude-code,cursor,codex` |\n| `--global` | Install to the agent's global config file |\n| `--project` | Install to the current project's config file |\n\n**Config targets**\n\n| Agent | Global path | Project path |\n|---|---|---|\n| Claude Code | `~/.claude.json` | `.claude/settings.json` |\n| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |\n| Codex | `$CODEX_HOME/mcp.json` or `~/.codex/mcp.json` | Not supported |\n\nThe command writes the MCP server under `mcpServers[\"bright-data\"]`:\n\n```json\n{\n \"mcpServers\": {\n \"bright-data\": {\n \"command\": \"npx\",\n \"args\": [\"@brightdata/mcp\"],\n \"env\": {\n \"API_TOKEN\": \"\"\n }\n }\n }\n}\n```\n\nBehavior notes:\n- Existing config is preserved; only `mcpServers[\"bright-data\"]` is added or replaced.\n- If the target config contains invalid JSON, the CLI warns and offers to overwrite it in interactive mode.\n- In non-interactive mode, pass both `--agent` and the appropriate scope flag to skip prompts.\n\n---\n\n### `config`\n\nView and manage CLI configuration.\n\n```bash\nbrightdata config # Show all config\nbrightdata config get # Get a single value\nbrightdata config set # Set a value\n```\n\n| Key | Description |\n|---|---|\n| `default_zone_unlocker` | Default zone for `scrape` and `search` |\n| `default_zone_serp` | Default zone for `search` (overrides unlocker zone) |\n| `default_format` | Default output format: `markdown` or `json` |\n| `api_url` | Override the Bright Data API base URL |\n\n```bash\nbrightdata config set default_zone_unlocker my_zone\nbrightdata config set default_format json\n```\n\n---\n\n### `login` / `logout`\n\n```bash\nbrightdata login # Interactive login\nbrightdata login --api-key # Non-interactive\nbrightdata logout # Clear saved credentials\n```\n\n---\n\n## Configuration\n\nConfig is stored in an OS-appropriate location:\n\n| OS | Path |\n|---|---|\n| macOS | `~/Library/Application Support/brightdata-cli/` |\n| Linux | `~/.config/brightdata-cli/` |\n| Windows | `%APPDATA%\\brightdata-cli\\` |\n\nTwo files are stored:\n- `credentials.json` — API key\n- `config.json` — zones, output format, preferences\n\n**Priority order** (highest → lowest):\n\n```\nCLI flags → Environment variables → config.json → Defaults\n```\n\n---\n\n## Environment Variables\n\n| Variable | Description |\n|---|---|\n| `BRIGHTDATA_API_KEY` | API key (overrides stored credentials) |\n| `BRIGHTDATA_UNLOCKER_ZONE` | Default Web Unlocker zone |\n| `BRIGHTDATA_SERP_ZONE` | Default SERP zone |\n| `BRIGHTDATA_POLLING_TIMEOUT` | Default polling timeout in seconds |\n| `BRIGHTDATA_BROWSER_ZONE` | Default Scraping Browser zone (default: `cli_browser`) |\n| `BRIGHTDATA_DAEMON_DIR` | Override the directory used for browser daemon socket, PID, and authentication token files |\n\n```bash\nBRIGHTDATA_API_KEY=xxx BRIGHTDATA_UNLOCKER_ZONE=my_zone \\\n brightdata scrape https://example.com\n```\n\n---\n\n## Output Modes\n\nEvery command supports:\n\n| Mode | Flag | Behavior |\n|---|---|---|\n| Human-readable | *(default)* | Formatted table or markdown, with colors |\n| JSON | `--json` | Compact JSON to stdout |\n| Pretty JSON | `--pretty` | Indented JSON to stdout |\n| File | `-o ` | Write to file; format inferred from extension |\n\n**Auto-detected file formats:**\n\n| Extension | Format |\n|---|---|\n| `.json` | JSON |\n| `.md` | Markdown |\n| `.html` | HTML |\n| `.csv` | CSV |\n\n---\n\n## Pipe-Friendly Usage\n\nWhen stdout is not a TTY, colors and spinners are automatically disabled. Errors go to `stderr`, data to `stdout`.\n\n```bash\n# Extract URLs from search results\nbrightdata search \"nodejs tutorials\" --json | jq -r '.organic[].link'\n\n# Scrape and view with a markdown reader\nbrightdata scrape https://docs.github.com | glow -\n\n# Save scraped content to a file\nbrightdata scrape https://example.com -f markdown > page.md\n\n# Amazon product data as CSV\nbrightdata pipelines amazon_product \"https://amazon.com/dp/xxx\" --format csv > product.csv\n\n# Chain search → scrape\nbrightdata search \"top open source projects\" --json \\\n | jq -r '.organic[0].link' \\\n | xargs brightdata scrape\n```\n\n---\n\n## Dataset Types Reference\n\n```bash\nbrightdata pipelines list # See all types in your terminal\n```\n\n### E-Commerce\n\n| Type | Platform |\n|---|---|\n| `amazon_product` | Amazon product page |\n| `amazon_product_reviews` | Amazon reviews |\n| `amazon_product_search` | Amazon search results |\n| `walmart_product` | Walmart product page |\n| `walmart_seller` | Walmart seller profile |\n| `ebay_product` | eBay listing |\n| `bestbuy_products` | Best Buy |\n| `etsy_products` | Etsy |\n| `homedepot_products` | Home Depot |\n| `zara_products` | Zara |\n| `google_shopping` | Google Shopping |\n\n### Professional Networks\n\n| Type | Platform |\n|---|---|\n| `linkedin_person_profile` | LinkedIn person |\n| `linkedin_company_profile` | LinkedIn company |\n| `linkedin_job_listings` | LinkedIn jobs |\n| `linkedin_posts` | LinkedIn posts |\n| `linkedin_people_search` | LinkedIn people search |\n| `crunchbase_company` | Crunchbase |\n| `zoominfo_company_profile` | ZoomInfo |\n\n### Social Media\n\n| Type | Platform |\n|---|---|\n| `instagram_profiles` | Instagram profiles |\n| `instagram_posts` | Instagram posts |\n| `instagram_reels` | Instagram reels |\n| `instagram_comments` | Instagram comments |\n| `facebook_posts` | Facebook posts |\n| `facebook_marketplace_listings` | Facebook Marketplace |\n| `facebook_company_reviews` | Facebook reviews |\n| `facebook_events` | Facebook events |\n| `tiktok_profiles` | TikTok profiles |\n| `tiktok_posts` | TikTok posts |\n| `tiktok_shop` | TikTok shop |\n| `tiktok_comments` | TikTok comments |\n| `x_posts` | X (Twitter) posts |\n| `youtube_profiles` | YouTube channels |\n| `youtube_videos` | YouTube videos |\n| `youtube_comments` | YouTube comments |\n| `reddit_posts` | Reddit posts |\n\n### Other\n\n| Type | Platform |\n|---|---|\n| `google_maps_reviews` | Google Maps reviews |\n| `google_play_store` | Google Play |\n| `apple_app_store` | Apple App Store |\n| `reuter_news` | Reuters news |\n| `github_repository_file` | GitHub repository files |\n| `yahoo_finance_business` | Yahoo Finance |\n| `zillow_properties_listing` | Zillow |\n| `booking_hotel_listings` | Booking.com |\n\n---\n\n## Troubleshooting\n\n**`Error: No Web Unlocker zone specified`**\n```bash\nbrightdata config set default_zone_unlocker \n# or\nexport BRIGHTDATA_UNLOCKER_ZONE=\n```\n\n**`Error: Invalid or expired API key`**\n```bash\nbrightdata login\n```\n\n**`Error: Access denied`**\n\nCheck zone permissions in the [Bright Data control panel](https://brightdata.com/cp).\n\n**`Error: Rate limit exceeded`**\n\nWait a moment and retry. Use `--async` for large jobs to avoid timeouts.\n\n**Async job is too slow**\n```bash\nbrightdata pipelines amazon_product --timeout 1200\n# or\nexport BRIGHTDATA_POLLING_TIMEOUT=1200\n```\n\n**`No active browser session \"default\"`**\n```bash\n# Start a session first\nbrightdata browser open https://example.com\n```\n\n**Browser daemon won't start**\n```bash\n# Check if a stale socket file exists and clear it\nbrightdata browser close\n# Then retry\nbrightdata browser open https://example.com\n```\n\n**Element ref not found after interaction**\n\nRefs are re-assigned on every `snapshot` call. If you navigate or click (which may cause the page to change), take a fresh snapshot before using refs again:\n```bash\nbrightdata browser click e3\nbrightdata browser snapshot --compact # refresh refs\nbrightdata browser type e5 \"text\"\n```\n\n**Garbled output in non-interactive terminal**\n\nColors and spinners are disabled automatically when not in a TTY. If you still see ANSI codes, add `| cat` at the end of your command.\n\n---\n\n## Links\n\n- [Bright Data Website](https://brightdata.com)\n- [Control Panel](https://brightdata.com/cp)\n- [API Key Settings](https://brightdata.com/cp/setting/users)\n- [API Reference](https://docs.brightdata.com/api-reference)\n- [Report an Issue](https://github.com/brightdata/cli/issues)\n\n---\n\n\n © Bright Data · ISC License\n
\n","readmeFilename":"README.md"}