browser-debugger-cli 0.10.0 → 0.12.0

package/.claude/skills/bdg/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: bdg
+description: Use bdg CLI to drive and debug a real Chrome via Chrome DevTools Protocol - navigate, click, fill and submit forms, check what an action changed (navigation, new messages, pending requests), inspect elements without screenshots (box, layout, fonts, colors, a11y), read network requests and console errors, and call any CDP method. Use this skill when you need to verify a UI change in a running app, debug a page, automate a browser flow, or scrape dynamic content.
+---
+
+# bdg - Browser Automation CLI
+
+## Quick Start
+
+```bash
+bdg https://example.com          # Start session (launches Chrome)
+bdg dom screenshot /tmp/page.png # Take screenshot
+bdg stop                         # End session
+```
+
+## Session Management
+
+```bash
+bdg <url>                  # Start session (1920x1080, headless if no display)
+bdg <url> --headless       # Force headless mode
+bdg <url> --no-headless    # Force visible browser window
+bdg status                 # Check session status
+bdg peek                   # Preview collected telemetry
+bdg stop                   # End session (use sparingly)
+bdg cleanup                # Clean up after a crashed session
+bdg cleanup --force        # Kill a stuck session (daemon + its Chrome)
+```
+
+**Sessions run indefinitely by default** (no timeout). With HMR/hot-reload dev servers, keep the session running:
+
+```bash
+bdg http://localhost:5173      # Start once
+# ... make code changes, HMR updates the page ...
+bdg dom screenshot /tmp/s.png  # Check anytime
+bdg peek                       # Preview collected data
+# No need to stop/restart - Chrome stays on the page
+```
+
+**Don't stop sessions prematurely** - use `bdg peek` to inspect data. Only call `bdg stop` when completely done with browser automation.
+
+## Screenshots
+
+Always use `bdg dom screenshot` (raw CDP is blocked):
+
+```bash
+bdg dom screenshot /tmp/page.png                    # Full page
+bdg dom screenshot /tmp/viewport.png --no-full-page # Viewport only
+bdg dom screenshot /tmp/el.png --selector "#main"   # Element only
+bdg dom screenshot /tmp/scroll.png --scroll "#target" # Scroll to element first
+```
+
+## Actions Report What Changed
+
+`dom click`, `fill`, `submit`, `pressKey`, `hover` and `scroll` wait for the requests the action starts, then say what happened. Read this before reaching for a screenshot:
+
+```text
+✓ Element Clicked
+Page: navigated to https://app.test/secure (200)    # navigation (or "URL changed ... (same document)")
+New text: "Your password is invalid!" (div#flash)   # alert/status/aria-live messages that appeared
+⚠ Element Clicked (no visible effect observed ...)  # nothing changed - wrong element or a broken handler
+```
+
+- In `--json`: `navigation`, `messages`, `effect: "none"` and pending work (timers, spinners) are fields on `data`.
+- Results the page shows later are not waited for: follow up with `bdg dom wait` (below).
+
+## Form Interaction
+
+```bash
+# Discover forms
+bdg dom form --brief              # Quick scan: field names, types, required
+
+# Fill and interact
+bdg dom fill "input[name='user']" "myuser"    # Fill by selector
+bdg dom fill 0 "value"                         # Fill by index (from query)
+bdg dom click "button.submit"                  # Click element
+bdg dom submit "form" --wait-navigation        # Submit and wait for page load
+bdg dom pressKey "input" Enter                 # Press Enter key
+
+# Options
+--no-wait          # Skip network stability wait
+--wait-navigation  # Wait for page navigation (traditional forms)
+--wait-network <ms> # Wait for network idle (SPA forms)
+--index <n>        # Select nth element when multiple match
+```
+
+## DOM Inspection
+
+```bash
+bdg dom query "selector"     # Find elements, returns [0], [1], [2]... (0-based)
+bdg dom get "selector"       # Get semantic a11y info (token-efficient)
+bdg dom get "selector" --raw # Get full HTML
+bdg dom eval "js expression" # Run JavaScript
+bdg dom a11y "role:button"   # Query by accessibility role/name
+```
+
+Selectors search open shadow roots and same-origin iframes, and accept `:has-text("...")` and `:visible`.
+
+### Look Without a Screenshot
+
+```bash
+bdg dom inspect "button.primary"   # Box, layout, rendered font, colors + WCAG contrast, borders, state (~60-100 tokens)
+bdg dom inspect ".card" --why color  # Which CSS rule set a property, and what it overrode
+bdg dom layout ".card"             # Positions/sizes of every match: above/below the fold, hidden, covered
+bdg dom listeners "#save"          # Event listeners that run for an element (incl. delegated, React/Preact)
+bdg page emulate --viewport 390x844 --color-scheme dark   # Responsive/theme check mid-session
+```
+
+### Wait for Something
+
+```bash
+bdg dom wait '#result' --visible       # Appears and is visible
+bdg dom wait '.toast' --text 'Saved'   # Contains text
+bdg dom wait '#loading' --gone         # Spinner went away
+bdg dom wait --load                    # Page finished loading
+```
+
+## Network and Console
+
+```bash
+bdg network list                              # Requests (DevTools-style)
+bdg network list --filter "status-code:>=400" # Failed requests
+bdg details network <id>                      # Headers, timing, body of one request
+bdg console --level error                     # Console errors on the current page
+bdg console --follow                          # Stream messages live
+bdg network har /tmp/session.har              # Export HAR 1.2
+```
+
+## CDP Access
+
+Direct access to Chrome DevTools Protocol:
+
+```bash
+# Execute any CDP method
+bdg cdp Runtime.evaluate --params '{"expression": "document.title", "returnByValue": true}'
+bdg cdp Page.navigate --params '{"url": "https://example.com"}'
+bdg cdp Page.reload --params '{"ignoreCache": true}'
+
+# Discovery
+bdg cdp --list                    # List all domains
+bdg cdp Network --list            # List methods in domain
+bdg cdp Network.getCookies --describe  # Show method schema
+bdg cdp --search cookie           # Search methods
+```
+
+**Important**: Always use `returnByValue: true` for Runtime.evaluate to get serialized values.
+
+## Common Patterns
+
+### Login Flow
+```bash
+bdg https://example.com/login
+bdg dom form --brief
+bdg dom fill "input[name='username']" "$USER"
+bdg dom fill "input[name='password']" "$PASS"
+bdg dom submit "button[type='submit']" --wait-navigation
+bdg dom screenshot /tmp/result.png
+bdg stop
+```
+
+### Verify a UI Change (dev server with HMR)
+```bash
+bdg http://localhost:5173                 # Once; keep the session running
+bdg dom click "button.save"               # Read the reported effect
+bdg dom wait '.toast' --text 'Saved'
+bdg console --level error                 # Anything thrown?
+bdg dom inspect ".toast"                  # Looks right? (no screenshot needed)
+```
+
+### Extract Data
+```bash
+bdg cdp Runtime.evaluate --params '{
+  "expression": "Array.from(document.querySelectorAll(\"a\")).map(a => ({text: a.textContent, href: a.href}))",
+  "returnByValue": true
+}' | jq '.data.result.result.value'
+```
+
+## JSON Output and Exit Codes
+
+Add `--json` (`-j`) to any command for `{ version, success, data }` (or `{ success: false, error, exitCode, suggestion }`). `bdg --help --json` lists every command, flag and exit code.
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 0 | Success | - |
+| 81 | Invalid arguments (incl. blocked raw CDP methods) | Read the suggestion, use the alternative |
+| 83 | Resource not found | Element/session doesn't exist |
+| 85 | Session busy (still starting/stopping) | Retry shortly |
+| 87 | Stale index (page changed since `dom query`) | Re-run the query |
+| 91 | `dom eval` script threw | Fix the JavaScript |
+| 101 | CDP connection failure | Run `bdg cleanup --force` and retry |
+| 102 | Timeout (CDP, or `dom wait --timeout`) | Increase timeout or check page load |
+
+## Troubleshooting
+
+```bash
+bdg status --verbose      # Full diagnostics
+bdg cleanup               # Clean up after a crashed session
+bdg cleanup --force       # Kill a stuck session (daemon + its Chrome)
+```
+
+**Chrome won't launch?** Run `bdg cleanup --force` then retry.
+
+**Session stuck?** Run `bdg cleanup --force` to reset.
+
+### Custom Chrome Flags
+
+Use `--chrome-flags` or `BDG_CHROME_FLAGS` for self-signed certificates, CORS, etc.:
+
+```bash
+# CLI option
+bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"
+
+# Environment variable
+BDG_CHROME_FLAGS="--ignore-certificate-errors" bdg https://localhost:5173
+
+# Multiple flags
+bdg https://example.com --chrome-flags="--ignore-certificate-errors --disable-web-security"
+```
+
+**Common flags for development:**
+- `--ignore-certificate-errors` - Self-signed SSL certs
+- `--disable-web-security` - CORS issues in development
+- `--allow-insecure-localhost` - Insecure localhost
+- `--disable-features=IsolateOrigins,site-per-process` - Cross-origin iframes
+
+## Verification Best Practices
+
+**Prefer DOM queries over screenshots** for verification:
+
+```bash
+# GOOD: Fast, precise, scriptable
+bdg cdp Runtime.evaluate --params '{
+  "expression": "document.querySelector(\".error-message\")?.textContent",
+  "returnByValue": true
+}'
+
+# GOOD: Check element exists
+bdg dom query ".submit-btn"
+
+# GOOD: Check text content
+bdg cdp Runtime.evaluate --params '{
+  "expression": "document.body.innerText.includes(\"Success\")",
+  "returnByValue": true
+}'
+
+# AVOID: Screenshots for simple verification (slow, requires visual inspection)
+bdg dom screenshot /tmp/check.png  # Only use when you need visual proof
+```
+
+**When to use screenshots:**
+- Visual regression testing
+- Capturing proof for user review
+- Debugging layout issues
+- When DOM structure is unknown
+
+**When to use DOM queries:**
+- Verifying text content appeared
+- Checking element exists/visible
+- Validating form state
+- Counting elements
+- Any programmatic assertion
+
+## When NOT to Use bdg
+
+- **Static HTML** - Use `curl` + `htmlq`/`pq`
+- **API calls** - Use `curl` + `jq`
+- **Simple HTTP** - Use `wget`/`curl`
+
+Use bdg when you need: JavaScript execution, dynamic content, browser APIs, screenshots, or network manipulation.

package/README.md

@@ -1,116 +1,190 @@
-# Browser Debugger CLI
+# bdg - Browser Debugger CLI
 
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/szymdzum/browser-debugger-cli/pulls)
+[![npm downloads](https://img.shields.io/npm/dt/browser-debugger-cli?color=blue)](https://www.npmjs.com/package/browser-debugger-cli)
 [![CI](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/ci.yml)
 [![Security](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/security.yml/badge.svg)](https://github.com/szymdzum/browser-debugger-cli/actions/workflows/security.yml)
-[![npm downloads](https://img.shields.io/npm/dt/browser-debugger-cli?color=blue)](https://www.npmjs.com/package/browser-debugger-cli)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/szymdzum/browser-debugger-cli/pulls)
+
+**Give your AI agent a real browser. And the DevTools to go with it.**
+
+📖 **[Wiki](https://github.com/szymdzum/browser-debugger-cli/wiki)**: [Getting Started](https://github.com/szymdzum/browser-debugger-cli/wiki/Getting-Started) · [Commands](https://github.com/szymdzum/browser-debugger-cli/wiki/Commands) · [For AI Agents](https://github.com/szymdzum/browser-debugger-cli/wiki/For-AI-Agents) · [Recipes](https://github.com/szymdzum/browser-debugger-cli/wiki/Recipes) · [Quick Reference](https://github.com/szymdzum/browser-debugger-cli/wiki/Quick-Reference) · [Troubleshooting](https://github.com/szymdzum/browser-debugger-cli/wiki/Troubleshooting) · [CLI reference](docs/CLI_REFERENCE.md)
 
-Chrome DevTools Protocol in your terminal. Opens a persistent connection to Chrome where commands can be executed sequentially via Unix pipes. **Designed for AI agents** and developers who want direct browser control without framework overhead.
+bdg keeps a browser session open in the background and lets you drive it one shell command at a time. Click, fill, navigate, then read what actually happened: requests, console errors, layout and styles. It is built for coding agents like Claude Code, Codex and Gemini CLI, and it's just as handy in your own terminal. Every command is a plain process with compact output, so it pipes into `jq` and costs an agent few tokens.
 
-## Why bdg?
+```bash
+npm install -g browser-debugger-cli
+bdg localhost:3000
+```
 
-- **Raw CDP access** - Every [protocol method](https://chromedevtools.github.io/devtools-protocol/) available directly
-- **Token efficient** - No overhead from MCP tool definitions; progressive discovery loads only what's needed
-- **Self-correcting** - Errors clearly exposed with semantic exit codes and suggestions
-- **Composable** - Unix philosophy: pipes, jq, shell scripts work naturally
+## Two ways to use it
 
-**When to use alternatives:**
-- **Puppeteer/Playwright**: Complex multi-step scripts, mature testing ecosystem
-- **Chrome DevTools MCP**: Already invested in MCP infrastructure
+### Debug a page: browser telemetry on demand
 
-**Built for agents:** Self-discovery (`--list`, `--search`), semantic exit codes, structured errors, case-insensitive commands, token-efficient output.
+![The cart button does nothing; bdg shows the 500 response, the console error and the missing cookie](https://raw.githubusercontent.com/szymdzum/browser-debugger-cli/main/docs/assets/demo-debug.gif)
 
-## Benchmark: CLI vs MCP for AI Agents
+The cart button does nothing, and the page doesn't say why. Three commands later the agent knows: the click fired a POST that returned 500, the console says the `cart_id` cookie is missing, and the cookie jar confirms it. Network, console, cookies and the DOM are there whenever the agent asks, without a debugger UI.
 
-We benchmarked bdg against Chrome DevTools MCP Server on real developer debugging tasks.
+### Automate without writing a script
 
+![An agent fills a form, clicks Subscribe, reads the confirmation and inspects the button](https://raw.githubusercontent.com/szymdzum/browser-debugger-cli/main/docs/assets/demo-automate.gif)
 
-**[Full benchmark analysis →](docs/benchmarks/ARTICLE_MCP_VS_CLI_FOR_AGENTS.md)**
+No Playwright script written up front. The agent runs one command, reads what the browser reports back, and picks the next step from that: the click says which text appeared, `dom inspect` says what the button looks like. When the page does something unexpected, the agent adapts on the spot instead of failing at line 40 of a test.
 
-**Key findings:** CLI provided 33% better token efficiency through selective queries vs full accessibility tree dumps, plus capabilities MCP doesn't expose (memory profiling, HAR export, batch JS execution).
+## More examples
 
+### Reuse the browser's login from the shell
 
-## Install
+```console
+$ bdg network getCookies
+[1] session_id
+  Value: s%3A9f8e7d6c
+  HttpOnly: Yes
+  SameSite: Lax
+
+$ bdg network headers 89565.2 --header authorization
+Request Headers:
+  Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZGEifQ.demo
+
+$ bdg eval "localStorage.getItem('access_token')"
+eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZGEifQ.demo
+```
+
+`HttpOnly` cookies are included, even though the page's own JavaScript can't read them. Log in once in the browser, then reuse the session from the shell:
 
 ```bash
-npm install -g browser-debugger-cli
+COOKIES=$(bdg network getCookies --json | jq -r '[.data[] | "\(.name)=\(.value)"] | join("; ")')
+curl -H "Cookie: $COOKIES" localhost:3000/api/me
 ```
 
-**Requirements:** Node.js 22.12+ and Chrome (or Chromium).
+### The rest of DevTools
 
-**Platform Support:**
-- ✅ macOS and Linux
-- ✅ Windows via WSL
-- ❌ PowerShell/Git Bash (not yet)
+```console
+$ bdg dom a11y tree
+[RootWebArea] "My App" (focused)
+  [Heading] "My App"
+  [Button] "Sign in" (focusable)
+  [Image]                                         ← no accessible name
+
+$ bdg cdp Performance.enable
+$ bdg cdp Performance.getMetrics --json | jq '.data.result.metrics | from_entries'
+{ "Nodes": 51, "LayoutDuration": 0.000115, "ScriptDuration": 0.000775, "JSHeapUsedSize": 772124, ... }
+
+$ bdg cdp Emulation.setCPUThrottlingRate --params '{"rate":4}'    # Slow CPU
+$ bdg cdp Network.emulateNetworkConditions --params '{"offline":false,"latency":400,"downloadThroughput":50000,"uploadThroughput":20000}'
+```
 
-## Quick Start
+Accessibility, performance metrics, CPU profiling, heap snapshots, code coverage, throttling, storage, service workers: everything Chrome DevTools can do, bdg can do too, through raw CDP. Can't find the method you need? `bdg cdp --search heap`.
+
+## Agents learn it on their own
+
+No docs to paste into the prompt. The agent asks bdg:
 
 ```bash
-bdg example.com                    # Start session
-bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"  # Self-signed certs
-bdg https://localhost:5173 --chrome-flags="--disable-web-security"       # Disable CORS
-bdg cdp --search cookie            # Discover commands
-bdg cdp Network.getCookies         # Run any CDP method
-bdg dom query "button"             # High-level helpers
-bdg dom fill 'input[name="q"]' "shoes"
-bdg dom click 'button:has-text("Search")'
-bdg page navigate example.com/about
-bdg eval "document.title"          # Run JavaScript in the page (--frame for iframes)
-bdg network list --preset errors   # Network requests, console: bdg console
-bdg dom listeners "#save"          # Which event listeners run for an element
-bdg dom layout "#save"             # Where it is, whether it is visible or covered
-bdg dom inspect "#save"            # What it looks like (Figma-like styles), no screenshot
-bdg dom inspect "#save" --why color   # Which CSS rule sets a value, and what it beats
-bdg page emulate --viewport 900x700   # Responsive check mid-session (or --color-scheme)
-bdg dom wait "#result" --visible   # Wait for an element instead of sleeping
-bdg example.com --session agent2 --viewport 1280x800   # A second, independent session
-bdg stop                           # End session
+bdg --help --json                          # Every command, flag and exit code, plus "task → command" mappings
+bdg cdp --search cookie                    # 13 matching methods across all CDP domains, each with an example call
+bdg cdp Network.getCookies --describe      # Parameters, return types, an example
+```
+
+And when it gets something wrong, bdg tells it what it meant:
+
+```console
+$ bdg dom clik "a"
+error: unknown command 'clik'
+(Did you mean click?)
+
+$ bdg cdp Network.getCookie
+  "error": "Method 'Network.getCookie' not found",
+  "suggestion": "... Did you mean: Network.getCookies, Network.setCookie, Network.setCookies"
 ```
 
-## Current State
+Each mistake exits with code 81 (invalid arguments), so the agent knows to fix the call rather than retry it. CDP method names are case-insensitive, and raw CDP calls point to the friendlier command when one exists. More in the [Agent-Friendly Tools](docs/principles/AGENT_FRIENDLY_TOOLS.md) principles bdg follows.
+
+## Benchmark: CLI vs MCP
+
+We gave an AI agent five real debugging tasks, from a single JS error up to a memory leak, and ran each one with bdg and with the official Chrome DevTools MCP server (November 2025).
+
+| | bdg | Chrome DevTools MCP |
+|---|---|---|
+| **Score** | **77 / 100** | 60 / 100 |
+| **Token efficiency** | **202** | 152 |
+| Tokens used | ~38.1K | ~39.4K |
+
+bdg scored 17 points higher on about the same token budget, so its token efficiency was 33% better. Part of the gap is reach: memory profiling, HAR export and batch JS execution have no MCP equivalent. [Read the full analysis →](docs/benchmarks/ARTICLE_MCP_VS_CLI_FOR_AGENTS.md)
 
-**Raw CDP access is complete.** Every protocol method works now. High-level commands cover the common work: page navigation, DOM queries and interaction (click, fill, hover, keys, forms, shadow DOM and iframes), accessibility tree, screenshots, element styles with the CSS cascade (`dom inspect`: what an element looks like, which rule sets each value, and declarations that have no effect), network requests and HAR export, console messages and event listeners. Actions report what they changed (navigation, new messages, requests, or no visible effect), and several named sessions can run side by side. See the [CLI reference](docs/CLI_REFERENCE.md) for every command, and `bdg --help --json` for the machine-readable version.
+## Use it with your agent
 
-## Agent Discovery Pattern
+bdg ships an agent skill that teaches the workflow: start once, act, read what changed, inspect without screenshots, check network and console.
 
 ```bash
-# Agent explores what's possible (no docs needed)
-bdg cdp --list                              # All domains
-bdg cdp Network --list                      # Methods in one domain
-bdg cdp Network.getCookies --describe       # Full schema + examples
-bdg cdp Network.getCookies                  # Execute
-
-# Search across all domains
-bdg cdp --search screenshot                 # Find relevant methods
-bdg cdp --search cookie                     # methods mentioning cookies
+bdg install-skill            # Claude Code (~/.claude/skills) + Codex, Gemini CLI, ... (~/.agents/skills)
+bdg install-skill --claude   # Claude Code only
 ```
 
-## Documentation
+Start a new agent session afterwards. In Claude Code the skill loads when a task needs a browser, or on demand with `/bdg`. Re-run `bdg install-skill` after upgrading bdg.
 
-📖 **[Wiki](https://github.com/szymdzum/browser-debugger-cli/wiki)** - Guides, command reference, recipes
+## Quick start
 
-- [Getting Started](https://github.com/szymdzum/browser-debugger-cli/wiki/Getting-Started)
-- [Commands](https://github.com/szymdzum/browser-debugger-cli/wiki/Commands)
-- [For AI Agents](https://github.com/szymdzum/browser-debugger-cli/wiki/For-AI-Agents)
-- [Recipes](https://github.com/szymdzum/browser-debugger-cli/wiki/Recipes)
-- [Quick Reference](https://github.com/szymdzum/browser-debugger-cli/wiki/Quick-Reference)
-- [Architecture](https://github.com/szymdzum/browser-debugger-cli/wiki/Architecture)
-- [Troubleshooting](https://github.com/szymdzum/browser-debugger-cli/wiki/Troubleshooting)
+```bash
+bdg example.com                              # Start a session (the browser stays open)
+bdg dom fill 'input[name="q"]' "shoes"       # Interact
+bdg dom click 'button:has-text("Search")'
+bdg dom wait "#result" --visible             # Wait for an element instead of sleeping
+bdg network list --preset errors             # Failed requests
+bdg console                                  # Console messages
+bdg dom layout "#save"                       # Where is it? Visible? Covered?
+bdg dom inspect "#save" --why color          # Which CSS rule sets the color
+bdg dom audit contrast                       # Page-wide: text below WCAG AA, weakest first
+bdg css search -- --brand                    # Where a token is set, in every stylesheet
+bdg dom listeners "#save"                    # Which event listeners run
+bdg page emulate --viewport 900x700          # Responsive check mid-session (--mobile for a phone)
+bdg eval "document.title"                    # Run JavaScript (--frame for iframes)
+bdg cdp Network.getCookies                   # Any CDP method
+bdg stop                                     # End the session
+```
 
-## Design Principles
+Local dev servers with self-signed certificates: `bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"`. Need parallel sessions? `bdg example.com --session agent2`.
 
-This tool implements [Agent-Friendly Tools](docs/principles/AGENT_FRIENDLY_TOOLS.md):
+## What it covers
 
-- **Self-documenting** - Tools teach themselves via `--list`, `--describe`
-- **Semantic exit codes** - Machine-parseable error handling
-- **Structured output** - JSON by default, human-readable optional
-- **Progressive disclosure** - Simple commands, deep capabilities
+| Area | Commands |
+|---|---|
+| **Page** | navigate, reload, back/forward, viewport, phone (`--mobile`) and color-scheme emulation |
+| **Interaction** | click (double, right), fill (React-compatible, file inputs), hover, keys, forms, scroll, wait; shadow DOM and iframes included |
+| **Inspection** | element styles with the CSS cascade, layout and visibility, page-wide audits (contrast, overflow, layers, animations), stylesheet search, accessibility tree, event listeners, screenshots |
+| **Telemetry** | network requests and headers (incl. `Authorization`), HAR export, cookies (incl. `HttpOnly`), console messages, live `peek --follow` |
+| **Accessibility** | accessibility tree, semantic queries (`role:button name:Submit`), contrast checks |
+| **Performance** | metrics, CPU and heap profiling, tracing, CPU and network throttling (raw CDP) |
+| **Sessions** | several named sessions side by side, or attach to a browser you already have open (`--chrome-ws-url`) |
+| **Everything else** | raw CDP: `bdg cdp --list`, `--search`, `--describe` |
 
-## Contributing
+The [CLI reference](docs/CLI_REFERENCE.md) documents every command. `bdg --help --json` gives agents the machine-readable version.
+
+## Install
 
-[Issues](https://github.com/szymdzum/browser-debugger-cli/issues) for bugs, [Discussions](https://github.com/szymdzum/browser-debugger-cli/discussions) for ideas. PRs welcome.
+**Requirements:** Node.js 22.12+ and a Chromium-based browser: Chrome, Chromium or Microsoft Edge.
+
+**Platforms:** macOS, Linux and Windows via WSL. Native PowerShell and Git Bash are not supported yet.
+
+**Browsers:** bdg launches Chrome by default. To use Edge, point `CHROME_PATH` at its binary, or attach to an Edge you started with `--remote-debugging-port`:
+
+```bash
+CHROME_PATH="/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" bdg example.com   # macOS
+CHROME_PATH=/usr/bin/microsoft-edge bdg example.com                                         # Linux
+bdg example.com --chrome-ws-url 9222                                                        # Attach to a running browser
+```
+
+Firefox and Safari are not supported: bdg speaks the Chrome DevTools Protocol, which they do not implement.
+
+## When to use something else
+
+- **Playwright / Puppeteer**: long scripted test suites and a mature testing ecosystem.
+- **Chrome DevTools MCP**: if your setup is already built around MCP servers.
+
+bdg is for when an agent or a developer needs to poke at a live page, step by step, and understand what is going on.
+
+## Contributing
 
-See `docs/` for architecture and contributor guides.
+[Issues](https://github.com/szymdzum/browser-debugger-cli/issues) for bugs, [Discussions](https://github.com/szymdzum/browser-debugger-cli/discussions) for ideas. PRs welcome. See the [Architecture](https://github.com/szymdzum/browser-debugger-cli/wiki/Architecture) page and `docs/` for contributor guides.
 
 ## License
 

package/dist/commands/css.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `bdg css search <text>` - find text in the page's stylesheets, including
+ * cross-origin ones that page scripts cannot read: where a token is set, which
+ * rules use `oklch(`, a class or a custom property.
+ */
+import type { Command } from 'commander';
+/**
+ * Register the `css` command group.
+ *
+ * @param program - Root command
+ */
+export declare function registerCssCommands(program: Command): void;
+//# sourceMappingURL=css.d.ts.map

package/dist/commands/css.js

@@ -0,0 +1,53 @@
+/**
+ * `bdg css search <text>` - find text in the page's stylesheets, including
+ * cross-origin ones that page scripts cannot read: where a token is set, which
+ * rules use `oklch(`, a class or a custom property.
+ */
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { integerOption } from './shared/validation.js';
+import { cssSearch } from '../ipc/client.js';
+import { formatCssSearch } from '../ui/formatters/audit.js';
+import { CSS_SEARCH_HELP_EXAMPLES } from '../ui/messages/commands.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+/**
+ * Register the `css` command group.
+ *
+ * @param program - Root command
+ */
+export function registerCssCommands(program) {
+    const css = program.command('css').description("The page's stylesheets: search <text>");
+    css
+        .command('search')
+        .description('Find text in every stylesheet of the page (cross-origin ones too), with the rule and file:line')
+        .argument('<text>', 'Text to find (case-insensitive), e.g. oklch( or .btn-primary; put -- before one that starts with - (-- --brand)')
+        .option('--limit <n>', 'Matches listed (default: 20)', integerOption(1, 500))
+        .addOption(jsonOption())
+        .addHelpText('after', CSS_SEARCH_HELP_EXAMPLES)
+        .action(async (text, options) => {
+        await runCommand(() => search(text, options), options, formatCssSearch);
+    });
+}
+/**
+ * Ask the daemon to search the stylesheets.
+ *
+ * @param text - Text to find
+ * @param options - Limit
+ * @returns Command result
+ */
+async function search(text, options) {
+    const response = await cssSearch({
+        query: text,
+        ...(options.limit !== undefined && { limit: options.limit }),
+    });
+    if (response.status === 'error' || !response.data) {
+        return {
+            success: false,
+            error: response.error ?? 'Failed to search the stylesheets',
+            exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
+            ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+        };
+    }
+    return { success: true, data: response.data };
+}
+//# sourceMappingURL=css.js.map

package/dist/commands/dom/audit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `bdg dom audit [check...]` - page-wide checks without a screenshot or
+ * `dom eval`: text below a WCAG contrast level, what makes the page scroll
+ * sideways and cut-off text and scaled images, fixed and sticky layers, and
+ * running animations.
+ */
+import type { Command } from 'commander';
+/**
+ * Register `bdg dom audit`.
+ *
+ * @param dom - The `dom` command group
+ */
+export declare function registerAuditCommand(dom: Command): void;
+//# sourceMappingURL=audit.d.ts.map