bdg - Browser Automation CLI

Quick Start

bdg https://example.com # Start session (launches Chrome) bdg dom screenshot /tmp/page.png # Take screenshot bdg stop # End session

Session Management

bdg <url> # Start session (1920x1080, headless if no display) bdg <url> --headless # Force headless mode bdg <url> --no-headless # Force visible browser window bdg status # Check session status bdg peek # Preview collected telemetry bdg stop # End session (use sparingly) bdg cleanup --force # Kill stale session bdg cleanup --aggressive # Kill all Chrome processes

Sessions run indefinitely by default (no timeout). With HMR/hot-reload dev servers, keep the session running:

bdg http://localhost:5173 # Start once

... make code changes, HMR updates the page ...

bdg dom screenshot /tmp/s.png # Check anytime bdg peek # Preview collected data

No need to stop/restart - Chrome stays on the page

Don't stop sessions prematurely - use bdg peek to inspect data. Only call bdg stop when completely done with browser automation.

Screenshots

Always use bdg dom screenshot (raw CDP is blocked):

bdg dom screenshot /tmp/page.png # Full page bdg dom screenshot /tmp/viewport.png --no-full-page # Viewport only bdg dom screenshot /tmp/el.png --selector "#main" # Element only bdg dom screenshot /tmp/scroll.png --scroll "#target" # Scroll to element first

Form Interaction

Discover forms

bdg dom form --brief # Quick scan: field names, types, required

Fill and interact

bdg dom fill "input[name='user']" "myuser" # Fill by selector bdg dom fill 0 "value" # Fill by index (from query) bdg dom click "button.submit" # Click element bdg dom submit "form" --wait-navigation # Submit and wait for page load bdg dom pressKey "input" Enter # Press Enter key

Options

--no-wait # Skip network stability wait --wait-navigation # Wait for page navigation (traditional forms) --wait-network <ms> # Wait for network idle (SPA forms) --index <n> # Select nth element when multiple match

DOM Inspection

bdg dom query "selector" # Find elements, returns [0], [1], [2]... bdg dom get "selector" # Get semantic a11y info (token-efficient) bdg dom get "selector" --raw # Get full HTML bdg dom eval "js expression" # Run JavaScript

CDP Access

Direct access to Chrome DevTools Protocol:

Execute any CDP method

bdg cdp Runtime.evaluate --params '{"expression": "document.title", "returnByValue": true}' bdg cdp Page.navigate --params '{"url": "https://example.com"}' bdg cdp Page.reload --params '{"ignoreCache": true}'

Discovery

bdg cdp --list # List all 53 domains bdg cdp Network --list # List methods in domain bdg cdp Network.getCookies --describe # Show method schema bdg cdp --search cookie # Search methods

Important: Always use returnByValue: true for Runtime.evaluate to get serialized values.

Common Patterns

Login Flow

bdg https://example.com/login bdg dom form --brief bdg dom fill "input[name='username']" "$USER" bdg dom fill "input[name='password']" "$PASS" bdg dom submit "button[type='submit']" --wait-navigation bdg dom screenshot /tmp/result.png bdg stop

Wait for Element

for i in {1..20}; do EXISTS=$(bdg cdp Runtime.evaluate --params '{ "expression": "document.querySelector("#target") !== null", "returnByValue": true }' | jq -r '.result.value') [ "$EXISTS" = "true" ] && break sleep 0.5 done

Extract Data

bdg cdp Runtime.evaluate --params '{ "expression": "Array.from(document.querySelectorAll("a")).map(a => ({text: a.textContent, href: a.href}))", "returnByValue": true }' | jq '.result.value'

Exit Codes

Code Meaning Action

0 Success

1 Blocked command Read error message, use suggested alternative

81 Invalid arguments Check command syntax

83 Resource not found Element/session doesn't exist

101 CDP connection failure Run bdg cleanup --aggressive and retry

102 CDP timeout Increase timeout or check page load

Troubleshooting

bdg status --verbose # Full diagnostics bdg cleanup --force # Kill stale session bdg cleanup --aggressive # Kill all Chrome processes

Chrome won't launch? Run bdg cleanup --aggressive then retry.

Session stuck? Run bdg cleanup --force to reset.

Custom Chrome Flags

Use --chrome-flags or BDG_CHROME_FLAGS for self-signed certificates, CORS, etc.:

CLI option

bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"

Environment variable

BDG_CHROME_FLAGS="--ignore-certificate-errors" bdg https://localhost:5173

Multiple flags

bdg https://example.com --chrome-flags="--ignore-certificate-errors --disable-web-security"

Common flags for development:

• --ignore-certificate-errors

• Self-signed SSL certs

• --disable-web-security

• CORS issues in development

• --allow-insecure-localhost

• Insecure localhost

• --disable-features=IsolateOrigins,site-per-process

• Cross-origin iframes

Verification Best Practices

Prefer DOM queries over screenshots for verification:

GOOD: Fast, precise, scriptable

bdg cdp Runtime.evaluate --params '{ "expression": "document.querySelector(".error-message")?.textContent", "returnByValue": true }'

GOOD: Check element exists

bdg dom query ".submit-btn"

GOOD: Check text content

bdg cdp Runtime.evaluate --params '{ "expression": "document.body.innerText.includes("Success")", "returnByValue": true }'

AVOID: Screenshots for simple verification (slow, requires visual inspection)

bdg dom screenshot /tmp/check.png # Only use when you need visual proof

When to use screenshots:

• Visual regression testing

• Capturing proof for user review

• Debugging layout issues

• When DOM structure is unknown

When to use DOM queries:

• Verifying text content appeared

• Checking element exists/visible

• Validating form state

• Counting elements

• Any programmatic assertion

When NOT to Use bdg

• Static HTML - Use curl

• htmlq /pq

• API calls - Use curl

• jq

• Simple HTTP - Use wget /curl

Use bdg when you need: JavaScript execution, dynamic content, browser APIs, screenshots, or network manipulation.