Skip to content

v0.1.5

Choose a tag to compare

View all tags
@meirk-brd meirk-brd released this 26 Mar 16:12
· 7 commits to main since this release
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.

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