Setting the file. One moment.
Subchapter 6.3
REFERENCE.mdMarkdown15 KBView on GitHub
The browse CLI is a daemon-based command-line tool:
browse open), persists across commands, and stops with browse stop.browse open <url> --local launches a clean isolated local browser. It is the default when BROWSERBASE_API_KEY is unset. Use browse open <url> --auto-connect to attach to an existing debuggable Chrome, or browse open <url> --cdp <port|url> to attach to a specific CDP target.BROWSERBASE_API_KEY is set.browse snapshot to get the page’s accessibility tree with element refs, then interact using those refs.Navigate to a URL. Auto-starts the daemon if not running.
browse open https://example.com
browse open https://example.com --wait networkidle # wait for all network requests to finish (useful for SPAs)
browse open https://example.com --wait domcontentloadedThe --wait flag controls when navigation is considered complete. Values: load (default), domcontentloaded, networkidle. Use networkidle for JavaScript-heavy pages that fetch data after initial load.
Create a Browserbase session with browse cloud sessions create --context-id <id>, then attach to its CDP endpoint with browse open <url> --cdp <connectUrl>. Add --persist to the cloud session if state changes should save back to the context.
SESSION_JSON="$(browse cloud sessions create --context-id ctx_abc123 --persist --keep-alive)"
SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"
browse open https://example.com --cdp "$CONNECT_URL"
# ...interact with the page...
browse stop
browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE--context-id <id> — Browserbase context ID to load when creating the cloud session.--persist — Save cookies/storage changes back to the context when the Browserbase session is released. Requires --context-id.--keep-alive — Keep the Browserbase session alive while the local browse daemon attaches and detaches.browse open ... --cdp "$CONNECT_URL", follow-up commands in that session do not repeat --cdp; the daemon remembers the attached target.Reload the current page.
browse reloadNavigate browser history.
browse back
browse forwardGet the accessibility tree with interactive element refs. This is the primary way to understand page structure.
browse snapshot
browse snapshot --compact # tree only, no ref mapsReturns a text representation of the page with refs like @0-5 that can be passed to click. Use --compact for shorter output when you only need the tree.
Take a visual screenshot. Slower than snapshot and uses vision tokens.
browse screenshot # print base64 JSON
browse screenshot --path ./capture.png # custom path
browse screenshot --full-page # capture entire scrollable pageGet page properties. Available properties: url, title, text, html, markdown, value, box, visible, checked.
browse get url # current URL
browse get title # page title
browse get text "body" # all visible text (selector required)
browse get text ".product-info" # text within a CSS selector
browse get html "#main" # inner HTML of an element
browse get markdown # full page body as markdown
browse get markdown ".article" # specific element as markdown
browse get value "#email-input" # value of a form field
browse get box "#header" # bounding box (centroid coordinates)
browse get visible ".modal" # check if element is visible
browse get checked "#agree" # check if checkbox/radio is checkedNote: get text and get html require a selector argument — use "body" for full page content. get markdown defaults to body when no selector is given.
Tip: Prefer get markdown over get text or get html when you need readable page content for analysis — it preserves links, headings, and structure without HTML noise.
Show the cached ref map from the last browse snapshot. Useful for looking up element refs without re-running a full snapshot.
browse refsClick an element by its ref from browse snapshot output.
browse click @0-5 # click element with ref 0-5Click at exact viewport coordinates.
browse click_xy 500 300Hover at viewport coordinates.
browse hover 500 300Type text into the currently focused element.
browse type "Hello, world!"
browse type "slow typing" --delay 100 # 100ms between keystrokes
browse type "human-like" --mistakes # simulate human typing with typosFill an input element matching a CSS selector. Add --press-enter when Enter is needed.
browse fill "#search" "browser automation"
browse fill "input[name=email]" "user@example.com"
browse fill "#search" "query" --press-enter # fill and press EnterSelect option(s) from a dropdown.
browse select "#country" "United States"
browse select "#tags" "javascript" "typescript" # multi-selectUpload file(s) to an <input type="file"> element. Works with both local and remote Browserbase sessions (remote uses base64 injection). Supports ref-based selectors from snapshot.
browse upload "#fileUpload" ./document.pdf # single file
browse upload @0-5 ./photo.png # using ref from snapshot
browse upload "#files" ./a.png ./b.png # multiple filesPress a keyboard key or key combination.
browse press Enter
browse press Tab
browse press Escape
browse press Cmd+A # select all (Mac)
browse press Ctrl+C # copy (Linux/Windows)Scroll at a given position by a given amount.
browse mouse scroll 500 300 0 -300 # scroll up at (500, 300)
browse mouse scroll 500 300 0 500 # scroll downDrag from one viewport coordinate to another.
browse mouse drag 80 80 310 100 # drag with default 10 steps
browse mouse drag 80 80 310 100 --steps 20 # more intermediate steps
browse mouse drag 80 80 310 100 --delay 50 # 50ms between steps
browse mouse drag 80 80 310 100 --button right # use right mouse button
browse mouse drag 80 80 310 100 --return-xpath # return source/target XPathsHighlight an element on the page for visual debugging.
browse highlight "#submit-btn" # highlight for 2 seconds (default)
browse highlight ".nav" -d 5000 # highlight for 5 secondsCheck element state. Available checks: visible, checked.
browse is visible ".modal" # returns { visible: true/false }
browse is checked "#agree" # returns { checked: true/false }Wait for a condition.
browse wait load # wait for page load
browse wait "selector" ".results" # wait for element to appear
browse wait timeout 3000 # wait 3 secondsStart the browser daemon manually. Usually not needed — the daemon auto-starts on first command.
browse startStop the browser daemon and close the browser.
browse stop
browse stop --force # force kill if daemon is unresponsiveCheck whether the daemon is running, its connection details, and current environment.
browse statusChoose the browser target on the command that starts the session:
browse open https://example.com --local
browse open https://example.com --local --headed
browse open https://example.com --auto-connect
browse open https://example.com --cdp 9222
browse open https://example.com --cdp ws://localhost:9222/devtools/browser/...
browse open https://example.com --remotebrowse status shows the resolved mode and active target once the daemon is running.browse stop closes the current daemon session; the next browse open chooses mode from its flags or environment.Create a new tab, optionally navigating to a URL.
browse tab new # open blank tab
browse tab new https://example.com # open tab with URLList all open tabs.
browse tab listSwitch to a tab by its index or target ID (from browse tab list).
browse tab switch 1Close a tab. Closes current tab if no index given. The CLI refuses to close the last remaining tab.
browse tab close # close current tab
browse tab close 2 # close tab at index 2Evaluate JavaScript in the page context.
browse eval "document.title"
browse eval "document.querySelectorAll('a').length"Set the browser viewport size.
browse viewport 1920 1080Capture network requests to the filesystem for inspection.
Enable network request capture. Creates a temp directory where requests and responses are saved as JSON files.
browse network onDisable network capture.
browse network offShow the capture directory path.
browse network pathClear all captured requests.
browse network clearAttach to any Chrome DevTools Protocol target and stream events as NDJSON (one JSON object per line). This command bypasses the daemon entirely — it opens a direct WebSocket connection and runs until interrupted.
browse cdp 9222 # bare port — auto-discovers via /json/version
browse cdp ws://127.0.0.1:9222/devtools/browser/... # full WebSocket URL
browse cdp wss://connect.browserbase.com/debug/... # remote Browserbase debug URLOptions:
| Flag | Description |
|---|---|
--domain <domains...> | CDP domains to enable (repeatable). Default: Network, Console, Runtime, Log, Page |
--pretty | Human-readable output instead of JSON. Auto-enabled for TTY |
Default domains: Network, Console, Runtime, Log, Page. To capture only specific domains:
browse cdp 9222 --domain Network # network events only
browse cdp 9222 --domain Network --domain Console # network + consolePiping and filtering:
browse cdp 9222 > events.jsonl # save to file
browse cdp 9222 | jq '.method' # extract method names
browse cdp 9222 | jq 'select(.method == "Network.requestWillBeSent") | .params.request.url'Pretty output shows compact one-line summaries:
[Target.attachedToTarget] [page] https://example.com
[Network.requestWillBeSent] GET https://example.com/api/data
[Network.responseReceived] 200 https://example.com/api/data
[Runtime.consoleAPICalled] [log] Hello world
[Page.frameNavigated] https://example.com/aboutWith Browserbase sessions: Use bb sessions debug <session-id> to get the wsUrl, then pass it to browse cdp:
# Get the debug WebSocket URL
bb sessions debug <session-id>
# Copy the wsUrl field and pass it to browse cdp
browse cdp wss://connect.browserbase.com/debug/<session-id>/devtools/browser/...Run commands against a named session, enabling multiple concurrent browsers.
browse open https://a.com --session work
browse open https://b.com --session personalContext flags such as --context-id and --persist live on browse cloud sessions create; attach to the resulting connectUrl with browse open ... --cdp <connectUrl>.
| Variable | Required | Description |
|---|---|---|
BROWSE_SESSION | No | Default session name (alternative to --session) |
BROWSERBASE_API_KEY | For remote mode | API key from https://browserbase.com/settings (opens in a new tab); makes Browserbase the default desired mode when no override is set |
BROWSERBASE_PROJECT_ID | No | Passed through to Browserbase when set |
Without an override, setting BROWSERBASE_API_KEY makes Browserbase the default desired mode. Otherwise the default desired mode is local. Use --local, --remote, --auto-connect, or --cdp <port|url> on browse open when you need an explicit target.
export BROWSERBASE_API_KEY="bb_live_..."Get these values from https://browserbase.com/settings (opens in a new tab).
“No active page”
browse open <url>. If the issue persists, run browse stop and retry. For zombie daemons: pkill -f "browse.*daemon".“Chrome not found” / “Could not find local Chrome installation”
browse open <url> --auto-connect if you already have a debuggable Chrome running, or switch to remote with browse open <url> --remote (no local browser needed).“Daemon not running”
snapshot, click, etc. require an active session.browse open <url> to start a session.Element ref not found (e.g., “@0-5”)
browse snapshot again to get fresh refs.Timeout errors
browse wait load before interacting, or increase wait time.Nearby