Skip to content

Quick Reference

Jump to bottom
Kumak edited this page Oct 22, 2026 · 17 revisions

Quick Reference

Fast lookup for common tasks, filters, exit codes, and quick fixes.

Common Command Patterns

Session Management

bdg <url>                    # Start (the only command that starts a session)
bdg status                   # Check status (why the last session ended, if it did)
bdg stop                     # Stop and close Chrome
bdg cleanup                  # Remove leftovers of a crashed session
bdg cleanup --force          # Kill a stuck session (daemon + its Chrome)
bdg <url> --session a1       # Named session (or BDG_SESSION=a1); every command takes --session
bdg sessions                 # List sessions (state, port, PID, URL)
bdg cleanup --session a1 --purge   # Remove a named session's directory

Start Options

bdg <url> --viewport 1280x800      # Exact viewport for the session
bdg <url> --color-scheme dark      # Emulate prefers-color-scheme
bdg <url> --mobile                 # Phone: 390x844 at 3x, touch, mobile user agent
bdg <url> --chrome-ws-url 9222     # Attach to a running Chrome by its DevTools port
bdg attach                         # List the tabs of your running Chrome
bdg attach <tab>                   # Attach to one without reloading it (index, or part of URL/title)

Discovery

bdg --help --json            # Commands, options, exit codes (compact)
bdg <command> --help --json  # One command in full
bdg cdp --list               # All CDP domains
bdg cdp Network --list       # Methods in a domain
bdg cdp --search <keyword>   # Search by keyword
bdg cdp <Method> --describe  # Method details (redirects, enums, example)
bdg cdp <Method> --send-anyway   # Send a near-miss of a bundled name as typed

Navigation

bdg page info                # URL and title
bdg page tabs                # Tabs; bdg page switch <n> | bdg page close [target]
bdg state save f.json        # Save cookies + storage; bdg <url> --state f.json restores
bdg page navigate <url>      # Load and wait (--no-wait to return at once)
bdg page reload
bdg page back                # / forward
bdg page emulate --viewport 900x700   # Responsive check (--color-scheme, --mobile, --reset)

DOM Reading

bdg dom query "button"       # Find elements [0], [1], ...
bdg dom get 0                # Semantic info (--raw for HTML, --full for all text)
bdg dom layout "#save"       # Position, visibility, covering element, scroll needed
bdg dom inspect "#save"      # What it looks like (styles, contrast, hints), no screenshot
bdg dom inspect "#save" --why color   # Which CSS rule sets it, and what it beats
bdg dom audit contrast       # Page-wide: text below WCAG AA, weakest first (overflow, layers, animations)
bdg css search -- --brand    # Where a token is set and used, in every stylesheet
bdg dom form                 # Forms with fields, values, validation
bdg dom a11y tree            # Accessibility tree
bdg dom a11y query role=button   # --limit 0 lists all
bdg dom listeners "#save"    # Event listeners (incl. delegated)
bdg dom frames               # Iframes for eval --frame

DOM Interaction

bdg dom fill 0 "value"                    # Fill (selects, checkboxes, files too)
bdg dom click 'button:has-text("Save")'   # Click (--double, --right)
bdg dom hover "nav .menu"                 # Hover
bdg dom press-key "#search" Enter          # Keys (--times, --modifiers)
bdg dom submit "#login" --wait-navigation # Submit a form
bdg dom scroll --bottom                   # Scroll (selector, --down N, --top)

Results include Page: (navigation), New text: (messages that appeared), the requests started, Download: (files saved to <session dir>/downloads/), and warnings such as nothing observed, (page still changing) after click/press-key, or a value mismatch after fill.

Waiting

bdg dom wait "#finish" --visible          # Becomes visible
bdg dom wait ".toast" --text "Saved"      # Contains text
bdg dom wait "#loading" --gone            # Removed
bdg dom wait --load                       # Page loaded (default --timeout 10000; exit 102)

Selector Filters

'button:has-text("Save")'    # Text contains (case-insensitive)
'a:text-is("Home")'          # Text equals (case-sensitive)
'input:visible'              # Rendered only
'li:has-text("x"):visible'   # Combined
'li:has-text("x") .toggle'   # Scoped: the .toggle in the row with "x"
'label:has-text("Name") input'   # Input inside a label

JavaScript

bdg eval "document.title"                 # Run JavaScript in the page
bdg eval --frame 1 "location.href"        # In an iframe (index, name/id, URL part)

Screenshots

bdg dom screenshot out.png                     # Full page, resized (~1,600 tokens)
bdg dom screenshot out.png --no-resize         # Full resolution
bdg dom screenshot out.png --no-full-page      # Viewport only
bdg dom screenshot out.png "#card"             # One element (selector or index)
bdg dom screenshot out.png --scroll "footer"   # Scroll to element, capture viewport
bdg dom screenshot shots/ --follow --limit 5   # Sequence of frames

Monitoring

bdg peek                     # Quick snapshot (network + console)
bdg peek --follow            # Live view
bdg console                  # Errors/warnings, current page
bdg console --follow         # Stream console
bdg network list --follow    # Stream requests
bdg network details <id>     # Full request/response (credentials masked; --include-sensitive, --body, --no-body, --body-max)
bdg console details <index>  # Full message with stack

Network

bdg network list                                  # Last 100 requests
bdg network list --preset errors                  # Preset
bdg network list --filter "domain:api.* method:POST"
bdg network list --sort size --last 5 --page current   # Heaviest of this page
bdg network har out.har                           # Export HAR
bdg network har - | jq '.log.entries | length'    # HAR to stdout
bdg network headers --header content-security-policy
bdg network cookies

Filter Syntax

status-code:>=400            # HTTP status (=, >=, <=, >, <)
domain:api.*                 # Domain with wildcards
method:POST                  # HTTP method
mime-type:application/json   # MIME type (image/* works)
resource-type:XHR,Fetch      # Resource type
larger-than:100KB            # Size (B, KB, MB, GB)
duration:>1s                 # Duration (ms or s)
has-response-header:set-cookie
is:from-cache                # Cached responses
is:running                   # In progress
is:failed                    # No response (DNS, refused, aborted, blocked)
scheme:https                 # URL scheme
url:access_token             # Part of the URL as shown (* matches anything)

!domain:cdn.*                # Negate with !
domain:api.* status-code:>=400   # Space = AND

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
failed is:failed
slow duration:>=1s

Output

bdg <command> --json         # One JSON envelope: { version, success, data }
bdg <command> -q             # Hide tips and "Next steps"
bdg <command> --json | jq '.data'

Exit Codes

Code Name Action
0 SUCCESS Continue
1 GENERIC_FAILURE Check stderr
80-99 User errors Fix input or state, don't retry unchanged
80 INVALID_URL Fix the URL; check the server is reachable
81 INVALID_ARGUMENTS Check syntax (bdg <command> --help)
82 PERMISSION_DENIED Fix file/directory permissions; accept the "Allow remote debugging?" prompt
83 RESOURCE_NOT_FOUND Start a session / fix the selector or id
84 RESOURCE_ALREADY_EXISTS Session already running: use it or bdg stop
85 RESOURCE_BUSY Session starting or stopping: wait and retry
86 DAEMON_ALREADY_RUNNING bdg status, then bdg stop
87 STALE_CACHE Re-run bdg dom query
88 NO_FORMS_FOUND No forms on the page
89 FORM_IN_IFRAME Use the iframe's fields as the message says
90 RESOURCE_CONFLICT Request conflicts with the session state, or the page replaced a built-in an action uses
91 SCRIPT_ERROR Fix the JavaScript passed to eval (or the page's own code that threw during an action)
100-119 Software errors Retry with backoff, or report
100 CHROME_LAUNCH_FAILURE Check Chrome / use another --port
101 CDP_CONNECTION_FAILURE bdg status; restart the session
102 CDP_TIMEOUT Page or session did not answer (or the remote-debugging prompt was not answered); re-run the command
103 SESSION_FILE_ERROR Check the session directory
104 UNHANDLED_EXCEPTION Report a bug
105 SIGNAL_HANDLER_ERROR Restart the session
106 SESSION_START_FAILURE Chrome launch or CDP connection failed
107 PAGE_CRASHED bdg page reload
110 SOFTWARE_ERROR Check ~/.bdg/daemon.log, report
130 INTERRUPTED Ctrl-C (cancels a start or a screenshot cleanly; also ends follow modes)
143 TERMINATED SIGTERM (also ends follow modes)

Troubleshooting Flowchart

Command fails?
├─ Exit 83 "No active session"  → bdg <url> (bdg status shows why the last one ended)
├─ Exit 83 "No nodes found"     → check selector: bdg dom query "<broader selector>"
├─ Exit 84 "already running"    → use it, or bdg stop && bdg <url>
├─ Exit 87 stale index          → re-run bdg dom query
├─ Exit 100 "Port ... in use"   → bdg <url> --port 9842, or bdg cleanup --force
├─ Exit 102 dom wait timed out  → read "last seen", check with bdg dom layout
├─ Exit 102 page busy/no answer → re-run; bdg cleanup --force if the session is frozen
├─ Exit 107 page crashed        → bdg page reload
└─ Anything stuck               → bdg cleanup --force

Common Issues Quick Fix

Symptom Quick Fix
"No active session" bdg <url> first
"Session already running" bdg stop, or keep using it
"Port 9222 is already in use" bdg <url> --port 9223 or bdg cleanup --force
Session hangs / does not respond bdg cleanup --force
Chrome left after a crash bdg cleanup
"The page crashed" (exit 107) bdg page reload
"No nodes found matching" Broaden the selector, add :visible, check iframes with bdg dom frames
"The element at index N is no longer in the page" Re-run bdg dom query
Click "does nothing" / nothing observed bdg dom listeners <selector>, bdg dom layout <selector>
Element appears later bdg dom wait <selector> --visible instead of sleep
"The page is still loading" warning bdg dom wait --load
Element in a cross-origin iframe bdg eval --frame <frame> '...'
Missing network data bdg page reload, or start with --all for tracking domains/binary bodies
Screenshot too many tokens Use the default (auto-resize), not --no-resize

jq Patterns

# Cookies (cdp results are under .data.result)
bdg cdp Network.getCookies --json | jq '.data.result.cookies[]'

# Count matches
bdg dom query "button" --json | jq '.data.count'

# Failed request URLs
bdg network list --preset errors --json | jq -r '.data.requests[].url'

# Status and URL of every HAR entry
bdg network har - | jq -r '.log.entries[] | "\(.response.status) \(.request.url)"'

# Screenshot token cost
bdg dom screenshot out.png --json | jq '.data | {finalTokens, resized}'

# Current page
bdg status --json | jq '.data.pageState'

# Error messages
bdg console --json | jq '.data.errors'

Performance Tips

  1. Use indices: Query once, then act by index (0, 1, 2...)
  2. JSON output: --json for parsing, -q for short human output
  3. Filter early: --preset, --filter, --type, --last
  4. Headless: --headless for lighter sessions
  5. Layout over screenshots: dom layout answers visibility questions in one line, and dom inspect answers what an element looks like and why
  6. Skip waiting: --no-wait on page and interaction commands when you don't need the page to settle

Platform-Specific Notes

macOS

  • Install Chrome: brew install --cask google-chrome

Linux

  • Install Chrome: sudo apt install google-chrome-stable
  • Running as root or in Docker: bdg adds --no-sandbox automatically (BDG_NO_SANDBOX=1 to force)

Windows (WSL)

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

Session Files Location

All files in ~/.bdg/ (override with BDG_SESSION_DIR); named sessions use ~/.bdg/sessions/<name>/:

  • daemon.sock - Unix socket; the session is running if it accepts connections
  • daemon.pid - Daemon process ID (informational)
  • session.meta.json - Active session metadata
  • chrome.pid - Chrome launched by bdg (crash recovery)
  • daemon.log - Daemon output
  • last-session.json - Why the last session ended
  • query-cache.json - Indices from the last query
  • port.txt - Remembered CDP port
  • chrome-profile/ - Chrome user data

Related Pages

Clone this wiki locally