Skip to content

Commands

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

Commands Reference

Complete command reference for bdg.

Session Lifecycle

Start Session

bdg <url>                           # Start session with URL
bdg localhost:3000                  # Local development
bdg https://example.com             # Full URL
bdg example.com                     # Auto-adds http://

Options:

Flag Description
--port <n> Custom CDP port (default: 9222)
--timeout <s> Auto-stop after seconds
--headless Run Chrome headless
--no-wait Don't wait for page load
--user-data-dir <path> Custom Chrome profile
--chrome-ws-url <url> Connect to existing Chrome
--compact Compact JSON output
--all Disable default filtering

Check Status

bdg status                          # Basic status
bdg status --verbose                # Include Chrome diagnostics
bdg status --json                   # JSON output

Stop Session

bdg stop                            # Stop session
bdg stop --kill-chrome              # Also kill Chrome

Cleanup

bdg cleanup                         # Remove stale files
bdg cleanup --force                 # Force even if active
bdg cleanup --aggressive            # Kill all Chrome processes
bdg cleanup --all                   # Remove session.json too

CDP Commands

Protocol Introspection

# List all domains
bdg cdp --list                      # 53 domains

# List methods in domain
bdg cdp Network --list              # 39 methods
bdg cdp DOM --list

# Search by keyword
bdg cdp --search cookie             # Find cookie-related methods
bdg cdp --search screenshot

# Describe method
bdg cdp Network.getCookies --describe
bdg cdp Page.captureScreenshot --describe

Execute CDP Methods

# No parameters
bdg cdp Network.getCookies
bdg cdp DOM.getDocument

# With parameters
bdg cdp Runtime.evaluate --params '{"expression":"document.title","returnByValue":true}'
bdg cdp Page.navigate --params '{"url":"https://example.com"}'

# Pipe with jq
bdg cdp Network.getCookies | jq '.cookies[] | select(.httpOnly)'

DOM Commands

Query Elements

bdg dom query "button"              # Find all buttons
bdg dom query ".error"              # By class
bdg dom query "#app"                # By ID
bdg dom query --json                # JSON output

Results are cached with indices for quick access.

Get Element Details

# Semantic output (default) - 70-99% token reduction
bdg dom get "button"                # [Button] "Submit" (focusable)
bdg dom get "#search"               # [Searchbox] "Search" (focusable)
bdg dom get 0                       # By cached index

# Raw HTML output
bdg dom get "button" --raw          # Full HTML
bdg dom get "button" --raw --all    # All matches
bdg dom get "button" --raw --nth 2  # 2nd match
bdg dom get --raw --node-id 123     # By nodeId

Semantic vs Raw:

Semantic (Default) Raw (--raw)
Token Efficiency 70-99% reduction Full HTML
Use Case AI agents, automation Debugging
Format [Role] "Name" (props) HTML with attributes

Element Interaction

# Fill inputs
bdg dom fill "#username" "admin"
bdg dom fill "input[type=password]" "secret"
bdg dom fill 0 "value"              # By cached index

# Click elements
bdg dom click "#login-btn"
bdg dom click "button" --index 2    # 2nd button
bdg dom click 0                     # By cached index

# Press keys
bdg dom pressKey "input" Enter
bdg dom pressKey "input" Tab
bdg dom pressKey "body" Escape
bdg dom pressKey "input" a --modifiers ctrl  # Ctrl+A

# Submit forms
bdg dom submit "#login-form"
bdg dom submit "#form" --wait-navigation

Screenshots

bdg dom screenshot output.png
bdg dom screenshot page.jpg --format jpeg
bdg dom screenshot visible.png --no-full-page
bdg dom screenshot hq.jpg --format jpeg --quality 100

Evaluate JavaScript

bdg dom eval "document.title"
bdg dom eval "window.location.href"
bdg dom eval "document.querySelectorAll('a').length"

Accessibility Commands

View A11y Tree

bdg dom a11y tree                   # First 50 nodes
bdg dom a11y tree --json            # Full tree as JSON

Query by Role/Name

bdg dom a11y query role=button
bdg dom a11y query name="Submit"
bdg dom a11y query role=button,name="Submit"
bdg dom a11y query description="Click to submit"

Describe Element

bdg dom a11y describe "button[type=submit]"
bdg dom a11y describe "#login-form"
bdg dom a11y describe 0             # By cached index

Network Commands

HAR Export

bdg network har                     # Default filename
bdg network har myfile.har          # Custom filename
bdg network har --json              # JSON metadata

Headers Inspection

bdg network headers                 # Main page headers
bdg network headers <requestId>     # Specific request
bdg network headers --header csp    # Filter by header
bdg network headers --json

Cookies

bdg network getCookies
bdg network getCookies --url https://api.example.com

Monitoring Commands

Peek (Snapshot)

bdg peek                            # Last 10 items
bdg peek --last 50                  # More items
bdg peek --network                  # Network only
bdg peek --console                  # Console only
bdg peek --type Document            # By resource type
bdg peek --type XHR,Fetch           # Multiple types
bdg peek --verbose                  # Full URLs
bdg peek --json

Resource Types: Document, Stylesheet, Image, Media, Font, Script, XHR, Fetch, WebSocket, Other

Tail (Live Updates)

bdg tail                            # Live updates
bdg tail --network                  # Network only
bdg tail --interval 2000            # Custom interval

Details

bdg details network <requestId>     # Full request/response
bdg details console <index>         # Console message details

Console Commands

Smart Summary (Default)

bdg console                         # Current page: errors/warnings deduplicated
bdg console --last 50               # Limit to last 50 messages
bdg console --json                  # JSON with summary stats

Default view shows messages from current page load only:

  • Errors and warnings with deduplication and occurrence counts
  • Source locations (file:line:col) from stack traces
  • Summary counts for info/debug/other messages

History (All Navigations)

bdg console --history               # All page loads, not just current
bdg console --history --list        # Full history chronologically

Chronological List

bdg console --list                  # All messages in order (current page)
bdg console --list --last 100       # Last 100 messages

Live Streaming

bdg console --follow                # Stream in real-time (like tail -f)

Details

bdg details console <index>         # Full message details with stack trace

Output Format

Success

{
  "version": "0.6.0",
  "success": true,
  "timestamp": "2025-11-22T12:00:00.000Z",
  "duration": 1234,
  "target": {
    "url": "http://localhost:3000",
    "title": "App"
  },
  "data": {...}
}

Error

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

Global Options

Flag Description
--json JSON output
--help Show help
--version Show version
--help --json Machine-readable help schema

Clone this wiki locally