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/
