@bsbofmusic/cdper

CLI for controlled access to a user's real Chrome/Edge session through CDP Bridge. Powers @bsbofmusic/cdper-mcp; Playwright CDP is an internal transport, not the public API.

Install

npm install -g @bsbofmusic/cdper

Quick Start

# Verify installation
cdper doctor

# Open a page
cdper open https://example.com --json
# Save tabId, workflowId, and leaseId from the JSON result.

# Get accessibility snapshot with @ref annotations
cdper snapshot <tabId> --workflow-id <workflowId> --lease-id <leaseId>

# Interact
cdper click <tabId> @5 --workflow-id <workflowId> --lease-id <leaseId>
cdper type <tabId> @5 "hello world" --workflow-id <workflowId> --lease-id <leaseId>
cdper press <tabId> Enter --workflow-id <workflowId> --lease-id <leaseId>

# List tabs
cdper tabs

# Screenshot
cdper screenshot <tabId> --out shot.png --workflow-id <workflowId> --lease-id <leaseId>
cdper screenshot <tabId> --out shot.png --lite --timeout 8000 --workflow-id <workflowId> --lease-id <leaseId>
# JSON output is path-only by default; request base64 explicitly when needed.
cdper screenshot <tabId> --json --include-data --workflow-id <workflowId> --lease-id <leaseId>

# Extract current-page links or text blocks
cdper extract <tabId> --mode links --limit 10 --workflow-id <workflowId> --lease-id <leaseId> --json
cdper extract <tabId> --mode text --selector "main" --workflow-id <workflowId> --lease-id <leaseId> --json

# Wait for content or a selector
cdper wait <tabId> --text "Example Domain" --timeout 5000 --workflow-id <workflowId> --lease-id <leaseId>
cdper wait <tabId> --selector "h1" --timeout 5000 --workflow-id <workflowId> --lease-id <leaseId>

# Evaluate JavaScript
cdper eval <tabId> "document.title" --workflow-id <workflowId> --lease-id <leaseId>

# ChatGPT / Doubao
cdper chatgpt "explain quantum computing"
cdper doubao "解释量子计算"

# Close tab
cdper close <tabId> --workflow-id <workflowId> --lease-id <leaseId>

Configuration and diagnostics

cdper doctor resolves CDP in this order: explicit --ws, CDP_WS, ~/.cdp-auth.json, then ~/.cdp-bridge/config.json plus CDP_BRIDGE_HOST.

The doctor output is token-redacted and is designed to be pasted into agent reports safely, but do not share raw ws://...token=... URLs.

After upgrading @bsbofmusic/cdper, @bsbofmusic/cdper-mcp, or official plugins, reload the already-running MCP gateway before retesting. Hermes users should run /reload-mcp; other native clients should restart/reload the MCP server from the client UI. A fresh npx version does not update an already-started MCP process.

Common cold-start states:

• no CDP configuration: ask the user for the CDP Bridge generated Tailscale IP, bridge port, and WS token/full WS URL, then write a private ~/.cdp-auth.json or set CDP_WS. Expected shape: ws://<TAILSCALE_IP>:<BRIDGE_PORT>/devtools/browser?token=<TOKEN>.
• portDriftCandidate: cdp-bridge is listening on a nearby port instead of the configured one. Update CDP_WS / ~/.cdp-auth.json / ~/.cdp-bridge/config.json, then reload the MCP client.
• bridgeReachable=true and browserReady=false: the bridge is online but Chrome CDP is standby. Start a browser from CDP Bridge (advanced + Default profile if you need the persistent replica), then retry.
• cdper not found after global install: your npm global bin is not on PATH; use the MCP npx -y @bsbofmusic/cdper-mcp@latest form or add the npm global bin directory to PATH.
• Chrome/Edge built-in Remote debugging is enabled on the same local debug port: turn that browser setting off and let CDP Bridge own the debug port, then rerun /control/start or doctor --deep.

Playwright-core policy

@bsbofmusic/cdper bundles a pinned, stable playwright-core for the official playwright-cdp transport. Users do not install full playwright, do not run npx playwright install, and do not use Playwright selectors as the cdper API. Upgrades happen by installing a newer cdper release after release gates pass.

Architecture

• Tab State: Persisted at ~/.cdper/tabs.json, 4-hour TTL
• Tab Lease: cdper open --json returns workflowId + leaseId; leased tab actions must provide both to prevent cross-workflow mistakes
• @ref System: Each cdper snapshot assigns incrementing IDs (@1, @2...) to interactive elements
• Short-lived connections: Each command attaches → executes → disconnects

Stable JSON contracts

• cdper open --json always includes top-level tabId, workflowId, leaseId, leaseExpiresAt, targetId, url, title, and the legacy nested tab object.
• cdper eval --json always includes ok, result, type, and jsonSerializable; if JavaScript returns undefined, result is null and type is undefined.
• cdper screenshot --json includes mode, timeoutMs, elapsedMs, tabId, url, and title; it omits base64 image data unless --include-data is passed. Normal screenshots retry once in lite mode after a capture timeout unless --no-retry-lite is set.
• cdper extract --json is a generic current-page primitive (links or text); link items include original href plus best-effort unwrapped url for common redirect links. It is not a search-engine-specific parser.
• --json writes machine-readable JSON to stdout; logs, warnings, and debug output go to stderr so agents can parse stdout directly.

License

MIT