Sean McGuire bf9d44989c
[chore]: bump ws dep (#2169)
# why
- bumps `ws` & a few other deps to versions with various security
patches
# what changed
- bumps direct `ws` dep from `^8.18.0` to `^8.21.0`
- bumps turbo from `^2.8.10` to `^2.9.15`
- adds monorepo-wide overrides for `qs` & `ws` which are transitive deps
brought in by mintlify & braintrust
- overrides were required here since a direct bump of braintrust &
mintlify did not resolve to upgraded `qs` & `ws` versions


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Upgrade `ws` to patched versions across the repo and add overrides for
transitive `ws` and `qs` to address security fixes. Also bump `turbo` to
the latest minor.

- **Dependencies**
  - `packages/cli` and `packages/core`: `ws` ^8.18.0 -> ^8.21.0
- Root overrides: `ws` ^8.20.1, `qs` ^6.15.2 (to override transitive
deps from `mintlify` and `braintrust`)
  - `turbo` ^2.8.10 -> ^2.9.15

<sup>Written for commit e8f6ff1f863aac475f754f7d80e83db0eea4ad09.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2169?utm_source=github">Review
in cubic</a></sup>

<!-- End of auto-generated description by cubic. -->
2026-05-27 11:50:35 -07:00
..
2026-05-27 11:50:35 -07:00

Browse CLI

Browser automation CLI for AI agents. Built on Stagehand, providing raw browser control without requiring LLM integration.

Installation

npm install -g @browserbasehq/browse-cli

Requires Chrome/Chromium installed on the system.

Quick Start

# Navigate to a URL (auto-starts browser daemon)
browse open https://example.com

# Take a snapshot to get element refs
browse snapshot -c

# Click an element by ref
browse click @0-5

# Type text
browse type "Hello, world!"

# Take a screenshot
browse screenshot ./page.png

# Stop the browser
browse stop

How It Works

Browse uses a daemon architecture for fast, stateful interactions:

  1. First command auto-starts a Chrome browser daemon
  2. Subsequent commands reuse the same browser session
  3. State persists between commands (cookies, refs, etc.)
  4. Multiple sessions supported via --session or BROWSE_SESSION env var

Self-Healing Sessions

The CLI automatically recovers from stale sessions. If the daemon or Chrome crashes:

  1. Detects the failure
  2. Cleans up stale processes and files
  3. Restarts the daemon
  4. Retries the command

Agents don't need to handle recovery - commands "just work".

Commands

Navigation

browse open <url> [--wait load|domcontentloaded|networkidle] [-t|--timeout ms]
browse reload
browse back
browse forward

The --timeout flag (default: 30000ms) controls how long to wait for the page load state. Use longer timeouts for slow-loading pages:

browse open https://slow-site.com --timeout 60000

Click Actions

browse click <ref> [-b left|right|middle] [-c count]  # Click by ref (e.g., @0-5)
browse click_xy <x> <y> [--button] [--xpath]          # Click at coordinates

Coordinate Actions

browse hover <x> <y> [--xpath]
browse scroll <x> <y> <deltaX> <deltaY> [--xpath]
browse drag <fromX> <fromY> <toX> <toY> [--steps n] [--xpath]

Keyboard

browse type <text> [-d delay] [--mistakes]
browse press <key>  # e.g., Enter, Tab, Cmd+A

Forms

browse fill <selector> <value> [--no-press-enter]
browse select <selector> <values...>
browse highlight <selector> [-d duration]

Page Info

browse get url
browse get title
browse get text <selector>
browse get html <selector>
browse get value <selector>
browse get box <selector>  # Returns center coordinates

browse snapshot [-c|--compact]  # Accessibility tree with refs
browse screenshot [path] [-f|--full-page] [-t png|jpeg]

Waiting

browse wait load [state]
browse wait selector <selector> [-t timeout] [-s visible|hidden|attached|detached]
browse wait timeout <ms>

Multi-Tab

browse pages          # List all tabs
browse newpage [url]  # Open new tab
browse tab_switch <n> # Switch to tab by index
browse tab_close [n]  # Close tab (default: last)

Network Capture

Capture HTTP requests to the filesystem for inspection:

browse network on     # Start capturing requests
browse network off    # Stop capturing
browse network path   # Get capture directory path
browse network clear  # Clear captured requests

Captured requests are saved as directories:

/tmp/browse-default-network/
  001-GET-api.github.com-repos/
    request.json      # method, url, headers, body
    response.json     # status, headers, body, duration

Daemon Control

browse start          # Explicitly start daemon
browse stop [--force] # Stop daemon
browse status         # Check daemon status
browse env [target]   # Show or switch environment: local | remote

Environment Switching (Local vs Remote)

Use environment switching when an agent should keep the same command flow, but the browser runtime needs to change:

  • local runs Chrome on your machine (best for local debugging/dev loops)
  • remote runs a Browserbase session (best for anti-bot hardening and cloud runs)
# Show active environment (if running) and desired environment for next start
browse env

# Switch current session to Browserbase (restarts daemon if needed)
browse env remote

# Switch back to local Chrome (clean isolated browser by default)
browse env local

Local Browser Strategies

By default, browse env local launches a clean isolated local browser. Use browse env local --auto-connect to opt into reusing an already-running Chrome with remote debugging enabled. If no debuggable Chrome is found, it falls back to launching an isolated browser.

# Use a clean isolated browser (default)
browse env local

# Auto-discover local Chrome, fallback to isolated
browse env local --auto-connect

# Attach to a specific CDP target (port or URL)
browse env local 9222
browse env local ws://localhost:9222/devtools/browser/...

Auto-discovery checks:

  1. DevToolsActivePort files in well-known Chrome/Chromium/Brave user-data directories
  2. Common debugging ports (9222, 9229)

To make your Chrome discoverable:

  1. Open chrome://inspect/#remote-debugging
  2. Check the box "Allow remote debugging for this browser instance"

For more information, see the Chrome DevTools docs.

Use browse status to see which strategy was resolved:

browse status
# {"running":true,"session":"default","mode":"local","localStrategy":"isolated","localSource":"isolated"}

General Behavior

  • Environment is scoped per --session
  • browse env <target> persists an override and restarts the daemon
  • browse stop clears the override so next start falls back to env-var-based auto detection
  • Auto detection defaults to:
    • remote when BROWSERBASE_API_KEY is set
    • local otherwise

Global Options

Option Description
--session <name> Session name for multiple browsers (default: "default")
--headless Run Chrome in headless mode
--headed Run Chrome with visible window (default)
--ws <url|port> One-shot CDP connection (bypasses daemon)
--json Output as JSON

Environment Variables

Variable Description
BROWSE_SESSION Default session name (alternative to --session)
BROWSERBASE_API_KEY Browserbase API key (required for browse env remote)

Element References

After running browse snapshot, you can reference elements by their ref ID:

# Get snapshot with refs
browse snapshot -c

# Output includes refs like [0-5], [1-2], etc.
# RootWebArea "Example" url="https://example.com"
#   [0-0] link "Home"
#   [0-1] link "About"
#   [0-2] button "Sign In"

# Click using ref (multiple formats supported)
browse click @0-2       # @ prefix
browse click 0-2        # Plain ref
browse click ref=0-2    # Explicit prefix

The full snapshot output includes mappings:

  • xpathMap: Cross-frame XPath selectors
  • cssMap: Fast CSS selectors when available
  • urlMap: Extracted URLs from links

Multiple Sessions

Run multiple browser instances simultaneously:

# Terminal 1
BROWSE_SESSION=session1 browse open https://google.com

# Terminal 2
BROWSE_SESSION=session2 browse open https://github.com

# Or use --session flag
browse --session work open https://slack.com
browse --session personal open https://twitter.com

Direct CDP Connection

Opt into using an existing Chrome instance:

To make your Chrome discoverable:

  1. Open chrome://inspect/#remote-debugging
  2. Check the box "Allow remote debugging for this browser instance"
  3. Re-run the CLI with auto-connect enabled.

For more information, see the Chrome DevTools docs.

# Auto-discover Chrome with remote debugging enabled
browse env local --auto-connect
browse open https://example.com

# Or target a specific port / WebSocket URL
browse env local 9222
browse --ws ws://localhost:9222/devtools/browser/... open https://example.com

Optimal AI Workflow

  1. Navigate to target page (browser auto-starts)
  2. Snapshot to get the accessibility tree with refs
  3. Click/Fill using refs directly (e.g., @0-5)
  4. Re-snapshot after actions to verify state changes
  5. Stop when done
browse open https://example.com
browse snapshot -c
# [0-5] textbox: Search
# [0-8] button: Submit
browse fill @0-5 "my query"
browse click @0-8
browse snapshot -c  # Verify result
browse stop

Troubleshooting

Chrome not found

The CLI uses your system Chrome/Chromium. If not found:

# macOS - Install Chrome or set path
export CHROME_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome

# Linux - Install chromium
sudo apt install chromium-browser

Stale daemon

If the daemon becomes unresponsive:

browse stop --force

Permission denied on socket

# Clean up stale socket files
rm /tmp/browse-*.sock /tmp/browse-*.pid

Platform Support

  • macOS (Intel and Apple Silicon)
  • Linux (x64 and arm64)

Windows support requires WSL or TCP socket implementation.

Development

# Clone and setup (in monorepo)
cd packages/cli
pnpm install         # Install dependencies first!
pnpm run build       # Build the CLI

# Run without building (for development)
pnpm run dev -- <command>

# Or with tsx directly
npx tsx src/index.ts <command>

# Run linting and formatting
pnpm run lint
pnpm run format

License

MIT - see LICENSE