Skip to main content

​
Your First Session

Get started with bdg in three simple steps:
1

Start a debugging session

Launch Chrome and connect to any website:
bdg example.com
This will:
  • Launch Chrome in the background
  • Navigate to the URL
  • Establish a CDP connection
  • Start collecting telemetry data
The session runs in the background. Your terminal is free for other commands.
2

Inspect the page

Query DOM elements and check what’s on the page:
# Find all buttons
bdg dom query "button"

bdg dom query "button"
3

Stop the session

When you’re done, stop the session:
bdg stop
This will:
  • Close Chrome
  • Save collected data to ~/.bdg/session.json
  • Clean up session files

​
Common Commands

Here are the most frequently used commands to get you started:

​
Session Management

bdg localhost:3000

​
DOM Inspection

bdg dom query "button.submit"

​
Network Monitoring

bdg network list

​
Live Monitoring

bdg peek --last 20

​
Real-World Example

Let’s debug a real website and inspect its network activity:
1

Start session with a popular site

bdg https://news.ycombinator.com
Wait a moment for the page to load completely.
2

Check what loaded

View network requests:
bdg peek --network --last 50
This shows the most recent network requests with status codes and URLs.
3

Find all links

Query for links on the page:
bdg dom query "a.storylink"
You’ll see a list of all story links with their text content.
4

Extract article titles

Use JavaScript evaluation to get titles:
bdg dom eval "Array.from(document.querySelectorAll('a.storylink')).map(a => a.textContent)"
Returns a JSON array of all article titles.
5

Check for errors

Look for console errors or warnings:
bdg console
Shows any JavaScript errors or console messages.
6

Export network data

Save network activity for analysis:
bdg network har hn-capture.har
Creates a HAR file you can open in Chrome DevTools.
7

Clean up

bdg stop
Session data saved to ~/.bdg/session.json.

​
Advanced Options

​
Headless Mode

Run Chrome without a visible window: 
bdg example.com --headless
Perfect for CI/CD pipelines and automated testing.

​
Custom Chrome Flags

Pass flags to Chrome for special scenarios: 
bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"

​
Connect to Existing Chrome

Connect to a Chrome instance you already have running:
1

Launch Chrome with debugging enabled

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222
2

Connect bdg to it

bdg --chrome-ws-url ws://localhost:9222/devtools/browser/<id>
Get the WebSocket URL from http://localhost:9222/json.

​
Understanding Output

​
JSON Output

All commands support --json for programmatic use: 
bdg status --json

{
  "version": "0.7.2",
  "success": true,
  "data": {
    "active": true,
    "pid": 12345,
    "url": "https://example.com",
    "uptime": 42000
  }
}

​
Exit Codes

bdg uses semantic exit codes for error handling:
  • 0 — Success
  • 80-99 — User errors (invalid arguments, resources not found)
  • 100-119 — System errors (timeouts, connection failures)
Check exit codes in scripts: 
if bdg dom query "button"; then
  echo "Found buttons"
else
  echo "No buttons found (exit code: $?)"
fi
See the Exit Codes reference for complete details.

​
Working with Pipes

bdg works seamlessly with Unix pipes and jq: 
# Extract specific data with jq
bdg peek --json | jq '.data.preview.data.network[] | select(.status >= 400)'

# Count requests by status
bdg network list --json | jq '[.data[].status] | group_by(.) | map({status: .[0], count: length})'

# Get all console errors
bdg console --json | jq '.data.messages[] | select(.level == "error")'

​
Next Steps

Now that you’ve completed your first session, explore these topics:

Session Lifecycle

Learn how sessions work under the hood

DOM Inspection Guide

Deep dive into querying and inspecting elements

Network Monitoring

Master request filtering and HAR exports

CDP Access

Execute any Chrome DevTools Protocol method

For AI Agents

Discover agent-optimized features

Command Reference

Complete reference for all commands

​
Need Help?

If you run into issues:

Troubleshooting

Common problems and solutions

GitHub Issues

Report bugs or request features

GitHub Discussions

Ask questions and share ideas

Examples

Learn from real-world recipes

Build docs developers (and LLMs) love

Get started for freeTalk to us