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/