Skip to content

Releases: brightdata/cli

v0.1.5

26 Mar 16:12
@meirk-brd meirk-brd
v0.1.5
5cad863
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v0.1.5 Latest
Latest

Bright Data Browser API

This release introduces brightdata browser - a full browser automation command group powered by Bright Data's Browser API. Control a real Chromium browser from your terminal or AI agent, with persistent sessions, geo-targeting, and a token-efficient accessibility tree snapshot system.

What's New

Browser Sessions

Start a browser session with a single command. A lightweight local daemon manages the connection so subsequent commands are instant — no reconnecting on every call.

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

Sessions are named, isolated, and auto-shutdown after 10 minutes of inactivity (configurable). Run as many sessions in parallel as you need.

# Two sessions, two countries, running simultaneously
brightdata browser open https://amazon.com --session us --country us
brightdata browser open https://amazon.com --session de --country de

Accessibility Tree Snapshots

The primary way to read a page — far more token-efficient than raw HTML. Each interactive element is assigned a short ref (e1, e2, …) that you use to interact with it.

brightdata browser snapshot              # Full tree
brightdata browser snapshot --compact    # Interactive elements + ancestors only
brightdata browser snapshot --depth 3    # Limit depth
brightdata browser snapshot --selector "main"  # Scope to a CSS subtree

Example output:

Page: Sign In — Example
URL: https://example.com/login

- heading "Sign In" [level=1]
- form
  - textbox "Email" [ref=e1, placeholder="you@example.com"]
  - textbox "Password" [ref=e2, placeholder="Password"]
  - button "Sign In" [ref=e3]
  - link "Forgot password?" [ref=e4]

Element Interaction

Interact with elements using the ref values from your snapshot:

brightdata browser type e1 "user@example.com"
brightdata browser type e2 "password" --submit   # types and hits Enter
brightdata browser click e3
brightdata browser fill e1 "user@example.com"    # direct fill, no key events
brightdata browser select e5 "United States"     # dropdown by label
brightdata browser check e6                      # checkbox / radio
brightdata browser hover e2                      # trigger hover states
brightdata browser scroll --direction down --distance 600
brightdata browser scroll --ref e10              # scroll element into view

Screenshots

brightdata browser screenshot ./result.png
brightdata browser screenshot --full-page
brightdata browser screenshot --base64          # inline base64 for AI agents

Content Extraction

brightdata browser get text             # full page text
brightdata browser get text "h1"        # scoped to CSS selector
brightdata browser get html ".product"  # innerHTML of an element

Network & Cookies

brightdata browser network    # requests captured since last navigation
brightdata browser cookies    # current session cookies

Network output:

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

Session Management

brightdata browser sessions              # list all active sessions
brightdata browser status                # current session state
brightdata browser close                 # close default session
brightdata browser close --session shop  # close named session
brightdata browser close --all           # close everything

Country Switching

Changing --country on an existing session automatically closes the browser, fetches a new geo-targeted endpoint, and reconnects — no manual close required.

brightdata browser open https://example.com --country us
# later...
brightdata browser open https://example.com --country de  # reconnects automatically

AI-Safe Content Boundaries

Wrap snapshot output in nonce-delimited boundaries to protect against prompt injection when feeding page content into an AI agent:

brightdata browser snapshot --wrap
--- BRIGHTDATA_BROWSER_CONTENT nonce=a3f8c2... origin=https://example.com ---
Page: Example
...
--- END_BRIGHTDATA_BROWSER_CONTENT nonce=a3f8c2... ---

New Flags

Flag Applies to Description
--session <name> all subcommands Named session (default: default)
--country <code> open ISO geo-targeting, auto-reconnects on change
--zone <name> open Scraping Browser zone (default: cli_browser)
--idle-timeout <ms> open Daemon auto-shutdown after idle (default: 10 min)
--timeout <ms> all subcommands IPC command timeout (default: 30s)
--compact snapshot Interactive elements + ancestors only
--interactive snapshot Interactive elements as a flat list
--depth <n> snapshot Limit tree depth
--selector <sel> snapshot Scope to CSS subtree
--wrap snapshot AI-safe content boundary wrapping
--full-page screenshot Full scrollable page capture
--base64 screenshot Output base64-encoded PNG
--append type Append to existing value
--submit type Press Enter after typing
--direction <dir> scroll up / down / left / right
--distance <px> scroll Pixels to scroll
--ref <ref> scroll Scroll element into view
--all close Close all active sessions

New Environment Variables

Variable Description
BRIGHTDATA_BROWSER_ZONE Default Scraping Browser zone
BRIGHTDATA_DAEMON_DIR Override daemon socket / PID file directory

Full AI Agent Workflow Example

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

# Read the page (compact = minimal tokens)
brightdata browser snapshot --compact

# Click the first story link (ref from snapshot)
brightdata browser click e1

# Read the new page
brightdata browser snapshot --compact

# Screenshot for visual verification
brightdata browser screenshot ./hn-story.png

# Done
brightdata browser close

Technical Notes

  • Uses playwright-core (no browser download — connects to Bright Data's remote Chromium via CDP)
  • Daemon communicates over Unix sockets on Linux/macOS, TCP on Windows
  • Daemon PID and socket files stored in ~/.brightdata-cli/ (Linux), ~/Library/Application Support/brightdata-cli/ (macOS), %APPDATA%\brightdata-cli\ (Windows)
  • The cli_browser zone is created automatically on first use if it doesn't exist

Upgrade

npm install -g @brightdata/cli@latest
Assets 2
Loading

v0.1.1

18 Mar 14:01
@meirk-brd meirk-brd
v0.1.1
5d0f3a0

Choose a tag to compare

View all tags
v0.1.1

Release Notes - @brightdata/cli v0.1.1

First official release of the Bright Data CLI.

What is it?

A command-line interface for the Bright Data platform. Scrape websites, search the web, and extract structured data from 40+ platforms — directly from your terminal.

npm i -g @brightdata/cli

Two commands are available after install: brightdata and bdata (shorthand).

Commands

Command Description
bdata scrape <url> Scrape any URL — bypasses CAPTCHAs, JS rendering, and anti-bot protections
bdata search <query> Search Google, Bing, or Yandex with structured JSON output
bdata pipelines <type> Extract structured data from 40+ platforms (Amazon, LinkedIn, TikTok, and more)
bdata zones List and inspect your Bright Data proxy zones
bdata budget View account balance and per-zone cost and bandwidth
bdata status <id> Check the status of an async job
bdata config Get or set CLI configuration
bdata init Interactive setup wizard
bdata login Authenticate with Bright Data
bdata logout Clear stored credentials
bdata skill Browse and install AI agent skills
bdata version Display version and environment info

Highlights

Scraping

  • Automatic CAPTCHA solving, JavaScript rendering, and anti-bot bypass
  • Output as markdown, HTML, JSON, or screenshot
  • Geo-targeting by country
  • Async job submission with polling

Web Search (SERP)

  • Google (structured results with organic, ads, knowledge graph, people-also-ask), Bing, and Yandex
  • Search types: web, news, images, shopping
  • Device targeting (desktop/mobile), country, and language localization
  • Pagination support

Structured Data Extraction (Pipelines)

42 dataset types across major platforms:

  • E-commerce — Amazon, Walmart, eBay, Best Buy, Etsy, Home Depot, Zara, Google Shopping
  • Professional — LinkedIn (profiles, companies, jobs, posts, people search), Crunchbase, ZoomInfo
  • Social — Instagram, Facebook, TikTok, X (Twitter), YouTube, Reddit
  • Other — Google Maps, Google Play, Apple App Store, Reuters, GitHub, Yahoo Finance, Zillow, Booking.com

Authentication

  • Browser-based OAuth for desktop environments
  • Device flow for headless/SSH sessions
  • Direct API key via flag or BRIGHTDATA_API_KEY env variable
  • Automatic zone provisioning on first login

AI Agent Skills

Install Bright Data capabilities into 45+ coding agents (Claude Code, Cursor, Windsurf, GitHub Copilot, and more):

  • search — structured Google search results
  • scrape — webpage scraping as clean markdown
  • data-feeds — structured data extraction from 40+ platforms
  • bright-data-mcp — 60+ MCP tools for search, scraping, and browser automation
  • bright-data-best-practices — reference knowledge base for writing Bright Data code

Output

  • Human-readable tables and markdown in TTY
  • JSON, pretty JSON, CSV, NDJSON for programmatic use
  • File output with auto-format detection (-o results.json)
  • Pipe-friendly — colors and spinners disabled automatically in non-TTY

Configuration

  • XDG-compliant config storage
  • CLI flags > environment variables > config file > defaults
  • Configurable default zones, output format, and API URL

Requirements

Install

# npm
npm i -g @brightdata/cli

# or one-liner
curl -fsSL https://raw.githubusercontent.com/brightdata/cli/main/install.sh | sh

Links

Loading