Browser automation via Chrome DevTools Protocol - control Chrome, Brave, Edge with real browser profiles
npm install browser-cdp
Browser automation via Chrome DevTools Protocol. Control Chrome, Brave, or Edge using your real browser - same fingerprint, real cookies, no automation detection.
``bash`
npm install -g browser-cdp
`bashStart browser with CDP enabled
browser-cdp start [browser] [--profile=NAME] [--isolated] [--port=PORT]
'Take screenshot
browser-cdp screenshotExport page as PDF
browser-cdp pdf [--path=FILE] [--format=A4|Letter|Legal|Tabloid] [--landscape]Interactive element picker
browser-cdp pick ''Stream browser console output (network errors, exceptions, logs)
browser-cdp console [--duration=SECONDS]Stream network requests/responses
browser-cdp network [--filter=PATTERN] [--json] [--errors] [--duration=SECONDS]Manage cookies (export/import/clear)
browser-cdp cookies export [--path=FILE]
browser-cdp cookies import
browser-cdp cookies clearManage localStorage/sessionStorage
browser-cdp storage get
browser-cdp storage set
browser-cdp storage list
browser-cdp storage clear
browser-cdp storage export [--path=FILE]
browser-cdp storage import
Add --session for sessionStorage instead of localStorage
Show page performance metrics
browser-cdp insights [--json]Run Lighthouse audit (Chrome only)
browser-cdp lighthouse [--json] [--category=NAME]
`Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
|
DEBUG_PORT | CDP debugging port | 9222 |
| BROWSER | Browser to use (chrome, brave, edge) | chrome |
| BROWSER_PATH | Custom browser executable path | (auto-detect) |Examples
`bash
Start Brave with real profile
browser-cdp start braveStart Brave with specific profile (by name)
browser-cdp start brave --profile=WorkStart Chrome on custom port
DEBUG_PORT=9333 browser-cdp startNavigate and search
browser-cdp nav https://google.com
browser-cdp eval 'document.querySelector("textarea").value = "hello"'Take screenshot
browser-cdp screenshot
Returns: /tmp/screenshot-2024-01-01T12-00-00.png
Export page as PDF
browser-cdp pdf
Returns: /tmp/pdf-2024-01-01T12-00-00.pdf
Export to specific file in A4 landscape
browser-cdp pdf --path report.pdf --format A4 --landscapePick elements interactively
browser-cdp pick "Select the login button"Stream console output (captures network errors, exceptions, console.log)
browser-cdp console
Then refresh the page to see errors
Stream console for 10 seconds
browser-cdp console --duration=10Stream network traffic
browser-cdp network
Then navigate to see requests
Filter to API calls only
browser-cdp network --filter=apiOnly show failed requests (4xx/5xx)
browser-cdp network --errorsJSON output for parsing
browser-cdp network --json --duration=5 | jq '.url'Export cookies to JSON file
browser-cdp cookies export
Returns: cookies.json with all cookies
Export to custom file
browser-cdp cookies export --path session.jsonImport cookies from file
browser-cdp cookies import session.jsonClear all cookies
browser-cdp cookies clearGet/set localStorage values
browser-cdp storage get authToken
browser-cdp storage set theme darkList all storage keys
browser-cdp storage listExport/import storage
browser-cdp storage export
browser-cdp storage import storage.jsonWork with sessionStorage
browser-cdp storage get tempData --sessionGet page performance insights
browser-cdp insights
Returns: TTFB, First Paint, FCP, DOM loaded, resources, memory
Run Lighthouse audit (Chrome only - Brave blocks CDP debugger)
browser-cdp start chrome --isolated
browser-cdp nav https://example.com
browser-cdp lighthouse
Returns: Performance, Accessibility, Best Practices, SEO scores
Close browser when done
browser-cdp close
`Cookies Command
The
cookies command provides session persistence for authenticated workflows:$3
Save your browser cookies to a JSON file for later use:
`bash
browser-cdp cookies export # Saves to cookies.json
browser-cdp cookies export --path auth.json # Save to specific file
`Output format:
`json
[
{
"name": "session_id",
"value": "abc123...",
"domain": "example.com",
"path": "/",
"httpOnly": true,
"secure": true,
"sameSite": "Strict",
"expires": 1735689600
}
]
`$3
Load previously exported cookies into the browser:
`bash
browser-cdp cookies import auth.json
`Useful for:
- Resuming authenticated sessions across browser restarts
- Sharing sessions across team members
- Preserving login state for automation workflows
$3
Delete all cookies from the browser:
`bash
browser-cdp cookies clear
`Storage Command
The
storage command provides localStorage and sessionStorage management:$3
`bash
browser-cdp storage get authToken # Get from localStorage
browser-cdp storage set theme dark # Set in localStorage
browser-cdp storage set tempData "session" --session # Set in sessionStorage
`$3
`bash
browser-cdp storage list # List localStorage keys
browser-cdp storage list --session # List sessionStorage keys
`$3
Save storage to a JSON file for backup or restore:
`bash
browser-cdp storage export # Saves to storage.json
browser-cdp storage export --path app-state.json # Save to specific file
browser-cdp storage import app-state.json # Restore from file
`Output format:
`json
{
"authToken": "eyJhbGciOiJIUzI1NiIs...",
"theme": "dark"
}
`$3
`bash
browser-cdp storage clear # Clear localStorage
browser-cdp storage clear --session # Clear sessionStorage
`$3
| Storage Type | Lifetime | Scope | Flag |
|--------------|----------|-------|------|
| localStorage | Permanent | Per origin | (default) |
| sessionStorage | Tab session | Per tab |
--session |Pre-started Browser
If you already have a browser running with CDP enabled, the CLI will connect to it:
`bash
Add to ~/.zshrc
alias brave-debug='/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser --remote-debugging-port=9222'Start browser manually
brave-debugCLI detects and connects
browser-cdp start # "Browser already running on :9222"
browser-cdp nav https://example.com
`Supported Browsers
| Browser | Command |
|---------|---------|
| Chrome |
chrome (default) |
| Brave | brave |
| Edge | edge |Platform Support
Works on macOS and Linux. Browser paths auto-detected per platform.
| Platform | Chrome Path | Config Path |
|----------|-------------|-------------|
| macOS |
/Applications/Google Chrome.app/... | ~/Library/Application Support/Google/Chrome/ |
| Linux | /usr/bin/google-chrome | ~/.config/google-chrome/ |Use
BROWSER_PATH env var to override if your browser is installed elsewhere.Why Real Browser?
| Aspect | browser-cdp | Playwright Test Mode |
|--------|-------------|---------------------|
| Browser | Your installed Chrome/Brave/etc | Bundled Chromium |
| Profile | Real cookies/logins by default | Fresh test profile |
| Detection | Not detectable as automation | Automation flags present |
| Use case | Real-world testing, scraping | Isolated E2E tests |
Development
`bash
Install dependencies
bun installRun all tests
bun run testRun unit tests only (fast, no browser needed)
bun run test:unitRun integration tests (requires browser)
bun run test:integrationWatch mode
bun run test:watch
``- dev-browser - Browser automation plugin for Claude Code with LLM-optimized DOM snapshots
MIT