Skip to content

Getting Started

Jump to bottom
Kumak edited this page Nov 22, 2025 · 2 revisions

Getting Started

Installation

Requirements

  • Node.js: 20.0.0 or higher
  • Chrome/Chromium: Latest stable version recommended
npm install -g browser-debugger-cli@alpha

Platform Support

Platform Status Notes
macOS Native Full support
Linux Native Full support
Windows WSL Supported Run inside WSL
PowerShell Not yet Use WSL instead
Git Bash Not yet Use WSL instead

The CLI uses Unix domain sockets for inter-process communication. Windows users should run bdg inside WSL for full compatibility.

Your First Session

1. Start a Session

bdg example.com

This:

  • Launches Chrome with DevTools Protocol enabled
  • Starts a background daemon for persistent connections
  • Opens the target URL

2. Explore CDP Capabilities

# List all 53 CDP domains
bdg cdp --list

# List methods in a domain
bdg cdp Network --list

# Search for methods by keyword
bdg cdp --search cookie

# Get full details about a method
bdg cdp Network.getCookies --describe

3. Run CDP Commands

# Get cookies
bdg cdp Network.getCookies

# Execute JavaScript
bdg cdp Runtime.evaluate --params '{"expression":"document.title","returnByValue":true}'

# Take screenshot
bdg cdp Page.captureScreenshot | jq -r '.data' | base64 -d > screenshot.png

4. Use High-Level Helpers

# Query DOM
bdg dom query "button"        # Find all buttons
bdg dom get "button"          # Get semantic info
bdg dom get "button" --raw    # Get raw HTML

# Monitor activity
bdg peek                      # Quick snapshot
bdg peek --network            # Network only
bdg tail                      # Live updates

5. Stop the Session

bdg stop

Session Management

Check Status

bdg status                    # Basic info
bdg status --verbose          # Include Chrome diagnostics

Clean Up

bdg cleanup                   # Remove stale files
bdg cleanup --force           # Force cleanup
bdg cleanup --aggressive      # Kill all Chrome processes

Page Readiness

By default, bdg waits for pages to fully load using three signals:

  1. Browser's window.onload fires
  2. Network goes quiet (200ms without new requests)
  3. DOM stops changing (300ms without mutations)

Skip waiting with --no-wait for immediate connection. Use this when:

  • Connecting to an already-loaded page
  • Testing static HTML files
  • You need immediate control without waiting for page load

Session Files

bdg stores data in ~/.bdg/:

File Purpose
daemon.pid Daemon process ID
daemon.sock Unix socket for IPC
session.meta.json Session metadata
session.json Final output (written on stop)
chrome-profile/ Chrome user data

Example session.json Structure

{
  "url": "https://example.com",
  "startTime": "2025-01-01T00:00:00.000Z",
  "endTime": "2025-01-01T00:05:30.000Z",
  "network": {
    "requests": [...],
    "summary": { "total": 42, "failed": 0 }
  },
  "console": { "messages": [...] },
  "performance": { "metrics": {...} }
}

Next Steps

Clone this wiki locally