browser-debugger-cli 0.11.0 → 0.13.0

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

@@ -16,8 +16,8 @@ bdg stop                         # End session
 ## Session Management
 
 ```bash
-bdg <url>                  # Start session (1920x1080, headless if no display)
-bdg <url> --headless       # Force headless mode
+bdg <url>                  # Start session (a window on a Mac or Linux desktop; headless over SSH, with CI set, on servers)
+bdg <url> --headless       # Force headless mode (do this when running unattended)
 bdg <url> --no-headless    # Force visible browser window
 bdg status                 # Check session status
 bdg peek                   # Preview collected telemetry
@@ -98,7 +98,7 @@ Selectors search open shadow roots and same-origin iframes, and accept `:has-tex
 ### 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 "button.primary"   # Box, layout, rendered font, colors + WCAG contrast, borders, state (~80-130 tokens; --no-hints drops the hints)
 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)
@@ -176,7 +176,7 @@ bdg cdp Runtime.evaluate --params '{
 
 ## 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.
+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; `bdg <command> --help --json` describes one command in full (option behaviors, defaults, examples).
 
 | Code | Meaning | Action |
 |------|---------|--------|

package/README.md

@@ -1,127 +1,191 @@
-# 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)
 
-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.
+**Give your AI agent a real browser. And the DevTools to go with it.**
 
-## Why bdg?
+📖 **[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)
 
-- **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
+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.
 
-**When to use alternatives:**
-- **Puppeteer/Playwright**: Complex multi-step scripts, mature testing ecosystem
-- **Chrome DevTools MCP**: Already invested in MCP infrastructure
+```bash
+npm install -g browser-debugger-cli
+bdg localhost:3000
+```
 
-**Built for agents:** Self-discovery (`--list`, `--search`), semantic exit codes, structured errors, case-insensitive commands, token-efficient output.
+## Two ways to use it
 
-## Benchmark: CLI vs MCP for AI Agents
+### Debug a page: browser telemetry on demand
 
-We benchmarked bdg against Chrome DevTools MCP Server on real developer debugging tasks.
+![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)
 
+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.
 
-**[Full benchmark analysis →](docs/benchmarks/ARTICLE_MCP_VS_CLI_FOR_AGENTS.md)**
+### Automate without writing a script
 
-**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).
+![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)
 
+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.
 
-## Install
+## More examples
+
+### Reuse the browser's login from the shell
+
+```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
+```
+
+### The rest of DevTools
+
+```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}'
+```
+
+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 --help --json                          # Every command, flag and exit code, plus "task → command" mappings
+bdg dom query --help --json                # One command in full: option behaviors, defaults, examples
+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
 ```
 
-**Requirements:** Node.js 22.12+ and Chrome (or Chromium).
+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"
+```
+
+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).
 
-**Platform Support:**
-- ✅ macOS and Linux
-- ✅ Windows via WSL
-- ❌ PowerShell/Git Bash (not yet)
+| | bdg | Chrome DevTools MCP |
+|---|---|---|
+| **Score** | **77 / 100** | 60 / 100 |
+| **Token efficiency** | **202** | 152 |
+| Tokens used | ~38.1K | ~39.4K |
 
-## Use with Claude Code and Other Agents
+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)
 
-bdg ships an agent skill (`SKILL.md`) that teaches the workflow: start once, act, read what the action changed, inspect without screenshots, check network and console.
+## Use it with your agent
+
+bdg ships an agent skill that teaches the workflow: start once, act, read what changed, inspect without screenshots, check network and console.
 
 ```bash
-bdg install-skill            # ~/.claude/skills/bdg (Claude Code) + ~/.agents/skills/bdg (Codex, Gemini CLI, ...)
+bdg install-skill            # Claude Code (~/.claude/skills) + Codex, Gemini CLI, ... (~/.agents/skills)
 bdg install-skill --claude   # Claude Code only
 ```
 
-Start a new agent session afterwards, and re-run `bdg install-skill` after upgrading bdg. In Claude Code the skill loads when a task needs a browser, or on demand with `/bdg`.
+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.
 
-## Quick Start
+## Quick start
 
 ```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 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 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 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
 ```
 
-## Current State
+Local dev servers with self-signed certificates: `bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"`. Need parallel sessions? `bdg example.com --session agent2`.
 
-**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.
+## What it covers
 
-## Agent Discovery Pattern
+| 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` |
 
-```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
-```
+The [CLI reference](docs/CLI_REFERENCE.md) documents every command. `bdg --help --json` gives agents the machine-readable version.
+
+## Install
 
-## Documentation
+**Requirements:** Node.js 22.12+ and a Chromium-based browser: Chrome, Chromium or Microsoft Edge.
 
-📖 **[Wiki](https://github.com/szymdzum/browser-debugger-cli/wiki)** - Guides, command reference, recipes
+**Platforms:** macOS, Linux and Windows via WSL. Native PowerShell and Git Bash are not supported yet.
 
-- [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)
+**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`:
 
-## Design Principles
+```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
+```
 
-This tool implements [Agent-Friendly Tools](docs/principles/AGENT_FRIENDLY_TOOLS.md):
+Firefox and Safari are not supported: bdg speaks the Chrome DevTools Protocol, which they do not implement.
 
-- **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
+## When to use something else
 
-## Contributing
+- **Playwright / Puppeteer**: long scripted test suites and a mature testing ecosystem.
+- **Chrome DevTools MCP**: if your setup is already built around MCP servers.
 
-[Issues](https://github.com/szymdzum/browser-debugger-cli/issues) for bugs, [Discussions](https://github.com/szymdzum/browser-debugger-cli/discussions) for ideas. PRs welcome.
+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/cdp.d.ts

@@ -1,4 +1,7 @@
-import type { Command } from 'commander';
+import { type Command } from 'commander';
+import { type CommandResult } from './shared/CommandRunner.js';
+import type { CdpCommandOptions } from './shared/optionTypes.js';
+import { type CdpExecuteData } from '../ui/formatters/cdp.js';
 /**
  * Register CDP command with full introspection support.
  *
@@ -14,4 +17,22 @@ import type { Command } from 'commander';
  * @param program - Commander.js Command instance to register commands on
  */
 export declare function registerCdpCommand(program: Command): void;
+/**
+ * Whether the argument names a domain without a method and nothing asks to
+ * run it (`bdg cdp Network`): its methods are listed, as with `--list`.
+ *
+ * @param method - Method or domain argument
+ * @param options - Command options
+ * @returns True for a bare domain name
+ */
+export declare function isBareDomain(method: string, options: CdpCommandOptions): boolean;
+/**
+ * The page exception a method reported in its result (`Runtime.evaluate`,
+ * `Runtime.callFunctionOn`, ... answer a script that threw with
+ * `exceptionDetails`), as an error result like `dom eval`'s (exit 91).
+ *
+ * @param result - Method result
+ * @returns Error result, or undefined when the result has no exception
+ */
+export declare function pageExceptionResult(result: unknown): CommandResult<CdpExecuteData> | undefined;
 //# sourceMappingURL=cdp.d.ts.map

package/dist/commands/cdp.js

@@ -1,10 +1,14 @@
+import { Option } from 'commander';
 import { normalizeMethod } from '../cdp/protocol.js';
 import { getAllDomainSummaries, getDomainMethods, getProtocolCounts, getDomainSummary, getMethodSchema, } from '../cdp/schema.js';
 import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
 import { CommandError } from '../errors/index.js';
+import { emptyCdpSearchError, missingArgumentError, scriptExecutionError, } from '../errors/messages.js';
 import { callCDP } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
+import { describeException } from '../runtime/dom/evalHelpers.js';
+import { formatCdpDescription, formatCdpDomainMethods, formatCdpDomains, formatCdpResult, formatCdpSearch, isEmptyCdpResult, } from '../ui/formatters/cdp.js';
 import { formatHint } from '../ui/messages/hints.js';
 import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
@@ -26,6 +30,8 @@ const DOMAIN_NOTES = {
     Tracing: 'Performance tracing. Call Tracing.start, perform actions, then Tracing.end. ' +
         'Data arrives via Tracing.dataCollected events.',
 };
+/** Usage of `bdg cdp`, suggested when it gets neither a method nor a flag */
+const CDP_USAGE = 'Usage: bdg cdp [method] [--params <json>] [--list] [--describe] [--search <query>]';
 /**
  * Domain and method counts of the bundled protocol, for the help text.
  *
@@ -44,18 +50,6 @@ const METHOD_NOTES = {
     'Profiler.start': 'Starts CPU profiling. Returns empty. Call Profiler.stop to get the profile data.',
     'Tracing.start': 'Starts tracing. Returns empty. Data arrives via events after Tracing.end.',
 };
-/**
- * Check if a CDP result is empty (null, undefined, or empty object).
- */
-function isEmptyResult(result) {
-    if (result === null || result === undefined) {
-        return true;
-    }
-    if (typeof result === 'object' && Object.keys(result).length === 0) {
-        return true;
-    }
-    return false;
-}
 /**
  * Get contextual hint for a method based on domain notes and result.
  */
@@ -64,7 +58,7 @@ function getMethodHint(methodName, result) {
         return METHOD_NOTES[methodName];
     }
     const domain = methodName.split('.')[0];
-    if (domain && DOMAIN_NOTES[domain] && isEmptyResult(result)) {
+    if (domain && DOMAIN_NOTES[domain] && isEmptyCdpResult(result)) {
         return DOMAIN_NOTES[domain];
     }
     return undefined;
@@ -90,35 +84,87 @@ export function registerCdpCommand(program) {
         '  Discovery: --list, --search, --describe\n' +
         '  Execution: case-insensitive (network.getcookies works)')
         .argument('[method]', 'CDP method name (e.g., Network.getCookies, network.getcookies)')
-        .option('--params <json>', 'Method parameters as JSON')
-        .option('--list', 'List all domains or methods in a domain')
-        .option('--describe', 'Show method signature and parameters')
-        .option('--search <query>', 'Search methods by keyword')
-        .addOption(jsonOption().hideHelp())
+        .addOption(new Option('--params <json>', 'Method parameters as JSON'))
+        .addOption(new Option('--list', 'List all domains or methods in a domain').conflicts([
+        'describe',
+        'params',
+    ]))
+        .addOption(new Option('--describe', 'Show method signature and parameters').conflicts('params'))
+        .addOption(new Option('--search <query>', 'Search methods by keyword').conflicts([
+        'list',
+        'describe',
+        'params',
+    ]))
+        .addOption(jsonOption())
         .addHelpText('after', () => `\nBundled protocol: ${cdpCountsText()}`)
         .action(async (method, options) => {
-        await runCommand(async (opts) => {
-            if (opts.search) {
-                return await handleSearch(opts.search, method);
-            }
-            if (opts.list && !method) {
-                return handleListDomains();
-            }
-            if (opts.list && method) {
-                return handleListDomainMethods(method);
-            }
-            if (opts.describe && method) {
-                return handleDescribeMethod(method);
-            }
-            if (method) {
-                return await handleExecuteMethod(method, opts.params);
-            }
-            throw new CommandError('Missing required argument or flag', {
-                suggestion: 'Usage: bdg cdp [method] [--params <json>] [--list] [--describe] [--search <query>]',
-            }, EXIT_CODES.INVALID_ARGUMENTS);
-        }, { ...options, json: true });
+        await runCdpCommand(method, options);
     });
 }
+/**
+ * Run the `bdg cdp` mode the options select, with its human-readable output.
+ *
+ * @param method - Method or domain argument
+ * @param options - Command options (exits 81 when neither a method nor a
+ *   discovery flag is given)
+ */
+async function runCdpCommand(method, options) {
+    if (options.search !== undefined) {
+        const query = options.search;
+        return runCommand(async () => handleSearch(query, method), options, formatCdpSearch);
+    }
+    if (method && (options.list || isBareDomain(method, options))) {
+        return runCommand(async () => handleListDomainMethods(method), options, formatCdpDomainMethods);
+    }
+    if (options.list)
+        return runCommand(async () => handleListDomains(), options, formatCdpDomains);
+    if (options.describe && method) {
+        return runCommand(async () => handleDescribeMethod(method), options, formatCdpDescription);
+    }
+    if (method) {
+        return runCommand(async () => handleExecuteMethod(method, options.params), options, formatCdpResult);
+    }
+    return runCommand(async () => {
+        const err = missingArgumentError(CDP_USAGE);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }, options);
+}
+/**
+ * Whether the argument names a domain without a method and nothing asks to
+ * run it (`bdg cdp Network`): its methods are listed, as with `--list`.
+ *
+ * @param method - Method or domain argument
+ * @param options - Command options
+ * @returns True for a bare domain name
+ */
+export function isBareDomain(method, options) {
+    return (!method.includes('.') &&
+        options.params === undefined &&
+        !options.describe &&
+        getDomainSummary(method) !== undefined);
+}
+/**
+ * The page exception a method reported in its result (`Runtime.evaluate`,
+ * `Runtime.callFunctionOn`, ... answer a script that threw with
+ * `exceptionDetails`), as an error result like `dom eval`'s (exit 91).
+ *
+ * @param result - Method result
+ * @returns Error result, or undefined when the result has no exception
+ */
+export function pageExceptionResult(result) {
+    if (typeof result !== 'object' || result === null || !('exceptionDetails' in result)) {
+        return undefined;
+    }
+    const details = result
+        .exceptionDetails;
+    const err = scriptExecutionError(describeException(details));
+    return {
+        success: false,
+        error: err.message,
+        exitCode: EXIT_CODES.SCRIPT_ERROR,
+        errorContext: { suggestion: err.suggestion },
+    };
+}
 /**
  * Find similar methods to suggest when a method is not found.
  * Returns up to 3 closest matches based on edit distance.
@@ -177,6 +223,15 @@ function blockedAlternative(methodName) {
  * @returns Success result with matching methods
  */
 async function handleSearch(query, domain) {
+    if (!query.trim()) {
+        const err = emptyCdpSearchError();
+        return {
+            success: false,
+            error: err.message,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: err.suggestion },
+        };
+    }
     if (domain !== undefined && !getDomainSummary(domain)) {
         return {
             success: false,
@@ -186,11 +241,11 @@ async function handleSearch(query, domain) {
         };
     }
     const { searchMethods } = await import('../cdp/schema.js');
-    const results = searchMethods(query).filter((m) => domain === undefined || m.domain.toLowerCase() === domain.toLowerCase());
+    const results = searchMethods(query.trim()).filter((m) => domain === undefined || m.domain.toLowerCase() === domain.toLowerCase());
     return {
         success: true,
         data: {
-            query,
+            query: query.trim(),
             count: results.length,
             methods: results.map((m) => ({
                 name: m.name,
@@ -338,6 +393,7 @@ function handleDescribeMethod(methodName) {
         };
     }
     const methodNote = METHOD_NOTES[schema.name] ?? DOMAIN_NOTES[schema.domain];
+    const alternative = blockedAlternative(schema.name);
     return {
         success: true,
         data: {
@@ -365,9 +421,7 @@ function handleDescribeMethod(methodName) {
                 description: r.description,
                 items: r.items,
             })),
-            example: blockedAlternative(schema.name)
-                ? { command: blockedAlternative(schema.name) }
-                : schema.example,
+            example: alternative ? { command: alternative } : schema.example,
         },
     };
 }
@@ -443,6 +497,9 @@ async function handleExecuteMethod(methodName, paramsJson) {
     const response = await callCDP(normalized, params);
     validateIPCResponse(response);
     const cdpResult = response.data?.result;
+    const exception = pageExceptionResult(cdpResult);
+    if (exception)
+        return exception;
     const result = {
         success: true,
         data: {

package/dist/commands/console.d.ts

@@ -22,6 +22,18 @@ export declare function listsMessages(options: Pick<ConsoleCommandOptions, 'list
  * @returns Messages of the current page (empty if it logged nothing)
  */
 export declare function filterByCurrentNavigation(messages: ConsoleMessage[], currentNavigationId?: number): ConsoleMessage[];
+/**
+ * Dropped messages that could have been in the view: all of them with
+ * `--history`; for the current page only while the oldest kept message is
+ * that page's (else every dropped one came from an earlier page).
+ *
+ * @param messages - All kept messages, oldest first
+ * @param dropped - Oldest messages the session dropped at its limit
+ * @param options - `--history`
+ * @param currentNavigationId - Navigation id of the current page, if known
+ * @returns Dropped count to warn about (0: none of the view's)
+ */
+export declare function droppedInView(messages: ConsoleMessage[], dropped: number, options: Pick<ConsoleCommandOptions, 'history'>, currentNavigationId?: number): number;
 export declare function filterByLevel(messages: ConsoleMessage[], level: ConsoleLevel): ConsoleMessage[];
 /**
  * Messages the filters left out between the first and the last listed