Skip to content

Quick Reference

Jump to bottom
Kumak edited this page Nov 27, 2025 · 7 revisions

Quick Reference

Fast lookup for common tasks, exit codes, and troubleshooting.

Common Command Patterns

Session Management

bdg <url> # Start bdg status # Check status bdg stop # Stop gracefully bdg cleanup --force # Force cleanup

Discovery

bdg cdp --list # List all 53 domains bdg cdp Network --list # List methods in domain bdg cdp --search <keyword> # Search by keyword bdg cdp <Method> --describe # Get method details

DOM Interaction

bdg dom query "button" # Find elements bdg dom get 0 # Get semantic info bdg dom fill 0 "value" # Fill input bdg dom click 0 # Click element

Screenshots

bdg dom screenshot out.png # Auto-resize for Claude Vision (~3k tokens) bdg dom screenshot out.png --no-resize # Full resolution (may be 300k+ tokens) bdg dom screenshot out.png --scroll "#footer" # Scroll to element, capture viewport bdg dom screenshot out.png --no-full-page # Viewport only (no scroll)

Auto-resize behavior:

  • Scales to 1568px max edge (Claude Vision optimal)
  • Tall pages (>3:1 aspect ratio) → viewport fallback with warning field
  • Token estimate included in JSON output (finalTokens)

Footer selectors vary by site:

  • Wikipedia: #footer
  • Amazon: #navFooter
  • Generic: footer

Monitoring

bdg peek # Quick snapshot bdg peek --network # Network only (deprecated) bdg tail # Live updates

Network Filtering

bdg network list # List all requests bdg network list --filter "status-code:>=400" # Failed requests bdg network list --filter "domain:api.*" # Filter by domain bdg network list --filter "method:POST" # Filter by method bdg network list --preset errors # Use preset bdg network list --preset api # XHR/Fetch only bdg network list --follow # Live streaming bdg network har out.har --filter "status-code:>=400" # Export filtered

Filter Syntax

# Filter types status-code:>=400 # HTTP status (=, >=, <=, >, <) domain:api.* # Domain with wildcards method:POST # HTTP method mime-type:application/json # MIME type resource-type:XHR,Fetch # CDP resource type larger-than:100KB # Size threshold has-response-header:cookie # Header presence is:from-cache # Cached responses is:running # Pending requests scheme:https # URL scheme # Negation (use = syntax to avoid CLI conflicts) --filter="-domain:cdn.*" # Exclude domain --filter="!method:GET" # Exclude method # Combined (AND logic) --filter="domain:api.* status-code:>=400"

Presets

Preset Filter
errors status-code:>=400
api resource-type:XHR,Fetch
large larger-than:1MB
cached is:from-cache
documents resource-type:Document
media resource-type:Image,Media
scripts resource-type:Script
pending is:running

Console

bdg console # Current page: errors/warnings deduplicated bdg console --list # All messages chronologically bdg console --history # All page loads (not just current) bdg console --follow # Live streaming

Object Expansion: Objects in console output are automatically expanded:

# Instead of: User: [object Object] # You get: User: {name: "John", roles: ["admin", "user"]}
  • Nested objects expanded up to 3 levels deep
  • Arrays show contents: [1, 2, 3] instead of Array(3)
  • Special types: Date, RegExp, Error, Map, Set

Output

bdg <command> --json # JSON output bdg <command> | jq '.data' # Pipe to jq

Exit Codes (Complete Reference)

Code Category Meaning Retry? Action
0 Success Operation completed N/A Continue
1 Generic Unspecified failure Maybe Check stderr
80-89 User Input Invalid input or state No Fix input
80 Invalid URL Malformed or unreachable URL No Fix URL format
81 Invalid Arguments Bad command arguments/flags No Check syntax
82 Permission Denied Insufficient file/dir permissions No Fix permissions
83 Resource Not Found Element/session/file missing No Verify exists
84 Resource Already Exists Duplicate resource No Remove or rename
85 Resource Busy Resource locked or in use Maybe Wait or cleanup
86 Daemon Already Running Session active No Run cleanup
100-119 Software External/internal errors Yes Retry/report
100 Chrome Launch Chrome failed to start Yes Check Chrome
101 CDP Connection WebSocket connection failed Yes Check Chrome alive
102 CDP Timeout Operation timed out Yes Increase timeout
103 Session File Error File I/O failed Maybe Check ~/.bdg/ perms
104 Unhandled Exception Internal bug No Report issue
105 Signal Handler Error Signal handling failed Maybe Restart session
110 Software Error Generic internal error Maybe Check logs/report

Exit Code Ranges

  • 0: Success
  • 1: Generic failure
  • 80-89: User errors (don't retry without fixing input)
  • 100-119: Software/external errors (safe to retry with backoff)

Agent Decision Tree

exit_code=$? if [ $exit_code -eq 0 ]; then # Success - continue continue_workflow elif [ $exit_code -ge 80 ] && [ $exit_code -le 89 ]; then # User error - fix input, don't retry blindly log_error "User error: $exit_code" exit 1 elif [ $exit_code -ge 100 ] && [ $exit_code -le 119 ]; then # Software error - retry with exponential backoff retry_count=$((retry_count + 1)) if [ $retry_count -lt 3 ]; then sleep $((2 ** retry_count)) retry_command fi else # Unknown error log_error "Unknown exit code: $exit_code" fi

Troubleshooting Flowchart

Command fails? ├─ Exit code 86 → bdg cleanup --force ├─ Exit code 85 → Start session: bdg <url> ├─ Exit code 83 → Check selector: bdg dom query "*" ├─ Exit code 100 → Check Chrome: which google-chrome ├─ Exit code 101 → Check session: bdg status --verbose └─ Exit code 102 → Increase timeout: bdg <url> --timeout 60

Common Issues Quick Fix

Symptom Quick Fix
"Daemon already running" bdg cleanup --force
"Session not found" bdg <url> first
"Element not found" bdg dom query "*" --json to debug
Chrome won't start brew install --cask google-chrome
Stale session bdg cleanup --aggressive
Slow page load bdg <url> --no-wait
Missing network data bdg cdp Page.reload
Screenshot too many tokens Use default (auto-resize) not --no-resize
Scroll selector not found Check site-specific ID (e.g., #footer vs #navFooter)

Discovery Workflow

# 1. What domains exist? bdg cdp --list | jq '.domains[].name' # 2. What can Network do? bdg cdp Network --list # 3. Find cookie methods bdg cdp --search cookie # 4. Learn how to use it bdg cdp Network.getCookies --describe # 5. Execute bdg cdp Network.getCookies

Output Format Quick Reference

Success Response

{ "version": "0.6.0", "success": true, "timestamp": "2025-11-22T00:00:00.000Z", "duration": 123, "target": { "url": "...", "title": "..." }, "data": { /* command-specific data */ } }

Error Response

{ "success": false, "error": "Error message" }

jq Patterns

# Extract cookies bdg cdp Network.getCookies | jq '.cookies[]' # Screenshot token cost bdg dom screenshot out.png --json | jq '{tokens: .finalTokens, size: .size, warning: .warning}' # Count elements bdg dom query "button" --json | jq '.count' # Filter by status (use network list instead) bdg network list --filter "status-code:>=400" --json | jq '.data[]' # Get all URLs bdg network list --json | jq '.data[].url' # Extract specific field bdg status --json | jq '.data.chrome.wsUrl'

Performance Tips

  1. Use indices: Query once, then use indices (0, 1, 2...) for fast access
  2. JSON output: Always use --json for programmatic parsing
  3. Filter early: Use --network, --console to reduce data
  4. Headless mode: Use --headless for faster, lighter sessions
  5. Skip waiting: Use --no-wait when page is pre-loaded

Platform-Specific Notes

macOS

  • Chrome path: /Applications/Google Chrome.app/
  • Install: brew install --cask google-chrome

Linux

  • Chrome path: /usr/bin/google-chrome
  • Install: sudo apt install google-chrome-stable

Windows (WSL)

  • Run inside WSL, not native Windows
  • Chrome must be WSL-installed, not Windows Chrome

Session Files Location

All files in ~/.bdg/:

  • daemon.pid - Daemon process ID
  • daemon.sock - Unix socket
  • session.meta.json - Active session metadata
  • session.json - Final output (after bdg stop)
  • chrome-profile/ - Chrome user data

Related Pages

Clone this wiki locally