bdg - Browser Debug Gateway

Browser telemetry via Chrome DevTools Protocol for testing the Astro dev server.

Quick Start

# Start session on Astro dev server
bdg http://localhost:4321/

# Check status
bdg status

# Preview collected data
bdg peek

# Stop and save session
bdg stop

Session Management

| Command | Description | |---------|-------------| | bdg http://localhost:4321/ | Start session on dev server | | bdg status | Show session status | | bdg stop | Stop and save to ~/.bdg/session.json | | bdg stop --kill-chrome | Stop and close Chrome | | bdg cleanup | Clean stale sessions | | bdg cleanup --aggressive | Force kill all Chrome instances |

Data Inspection

Peek (non-destructive preview)

bdg peek                    # Summary of all data
bdg peek -n                 # Network requests only
bdg peek -c                 # Console messages only
bdg peek -d                 # DOM/A11y tree
bdg peek -f                 # Follow mode (like tail -f)
bdg peek --last 20          # Last 20 items
bdg peek -j                 # JSON output

Network

bdg network list            # List all requests
bdg network list --failed   # Failed requests only
bdg network list --type XHR # Filter by type
bdg network headers         # Main document headers
bdg network headers <id>    # Specific request headers
bdg network getCookies      # List cookies
bdg network har             # Export as HAR file

Console

bdg console -l              # List all messages
bdg console --level error   # Errors only
bdg console --level warning # Warnings only
bdg console -f              # Follow in real-time
bdg console --last 50       # Last 50 messages

Details

bdg details request <id>    # Full request details
bdg details console <id>    # Full console message

DOM Interaction

Inspection

bdg dom a11y                # Accessibility tree
bdg dom a11y "button"       # Search a11y tree
bdg dom query "nav a"       # CSS selector query
bdg dom get "header"        # Get element structure
bdg dom get "article" --raw # Get raw HTML

Actions

bdg dom click "button.submit"           # Click element
bdg dom fill "input[name=email]" "test" # Fill input
bdg dom submit "form"                   # Submit form
bdg dom pressKey "input" "Enter"        # Press key
bdg dom eval "document.title"           # Evaluate JS

Screenshots

bdg dom screenshot ./shot.png           # Full page
bdg dom screenshot ./el.png -s "header" # Element only

CDP Protocol Access

bdg cdp --list              # List 53 domains
bdg cdp --search cookie     # Search methods
bdg cdp --describe Network.getCookies  # Method details
bdg cdp Network.getCookies  # Execute CDP method

Common Workflows

Test page load performance

bdg http://localhost:4321/
# Browse the site...
bdg peek -n                 # Check network requests
bdg network list --failed   # Any failed requests?
bdg stop

Debug console errors

bdg http://localhost:4321/
bdg console --level error   # Check for errors
bdg console -f              # Monitor in real-time

Inspect accessibility

bdg http://localhost:4321/
bdg dom a11y                # Full a11y tree
bdg dom a11y "navigation"   # Find nav elements

Capture visual state

bdg http://localhost:4321/
bdg dom screenshot ./screenshots/home.png
bdg dom screenshot ./screenshots/header.png -s "header"

Options Reference

| Flag | Description | |------|-------------| | -q, --quiet | Minimal output for AI agents | | -j, --json | JSON output (most commands) | | --headless | No visible browser window | | -t, --timeout <s> | Auto-stop after N seconds | | -p, --port <n> | Chrome debug port (default: 9222) | | --debug | Verbose logging |

Output Files

• Session data: ~/.bdg/session.json
• Chrome profile: ~/.bdg/chrome-profile/