Chrome Devtools Cli

chrome-devtools-cli

The package is chrome-devtools-mcp, but the action CLI is chrome-devtools. Use chrome-devtools <tool> ... for this skill. Do not use npx chrome-devtools-mcp@latest unless you are configuring an MCP server outside this skill.

Core Workflow

chrome-devtools new_page "https://example.com"
chrome-devtools take_snapshot
chrome-devtools click "1_3"
chrome-devtools fill "1_5" "search text"
chrome-devtools press_key "Enter"

take_snapshot returns accessibility-tree UIDs such as 1_3. Always act on UIDs from the latest snapshot. Re-snapshot after navigation, reloads, or major DOM updates.

Operating Rules

• Run tools directly; the background daemon starts implicitly on first real action and preserves browser state.
• Do not run start, status, or stop before every action. Use them only for setup, custom launch flags, or troubleshooting.
• Use chrome-devtools <command> --help for exact syntax. Output defaults to Markdown; add --output-format=json when structured output is useful.
• Prefer snapshots over screenshots for deciding what to click or fill. Use screenshots for visual proof, layout inspection, or reports.
• Use evaluate_script, console, and network commands when debugging runtime behavior; use Lighthouse and performance tracing for page-quality/performance work.

Common Tasks

chrome-devtools list_pages
chrome-devtools navigate_page --url "https://example.com"
chrome-devtools navigate_page --type "reload" --ignoreCache=true
chrome-devtools evaluate_script "() => document.title"
chrome-devtools list_console_messages --types error
chrome-devtools list_network_requests --pageSize 50
chrome-devtools take_screenshot --filePath page.png
chrome-devtools lighthouse_audit --mode "navigation"
chrome-devtools performance_start_trace --reload=true --autoStop=false --filePath trace.json.gz
chrome-devtools performance_stop_trace

For a broader command map, read references/cli-reference.md.

Setup

If this is the first time using the CLI or chrome-devtools is missing, read references/installation.md. Installation is a one-time prerequisite, not part of the regular workflow.

References

• references/cli-reference.md — command groups, daemon behavior, output modes, and troubleshooting commands
• references/installation.md — global install and PATH troubleshooting

CLI Reference

Use this as a map, not as a substitute for chrome-devtools <command> --help.

How The CLI Runs

chrome-devtools is a client for a background chrome-devtools-mcp daemon. On Linux/macOS it uses a Unix socket; on Windows it uses a named pipe.

• First real action auto-starts the daemon and browser if needed.
• Later commands reuse the same browser state.
• start, status, and stop are for setup and troubleshooting.
• chrome-devtools start forwards supported launch options such as --headless, --userDataDir, --browserUrl, --channel, --proxyServer, --usageStatistics, and --slim.

Navigation And Page State

chrome-devtools list_pages
chrome-devtools new_page "https://example.com"
chrome-devtools select_page 1
chrome-devtools close_page 1
chrome-devtools navigate_page --url "https://example.com"
chrome-devtools navigate_page --type "back"
chrome-devtools navigate_page --type "forward"
chrome-devtools navigate_page --type "reload" --ignoreCache=true
chrome-devtools wait_for "Loaded"
chrome-devtools resize_page 1280 720

Snapshot-Based Interaction

chrome-devtools take_snapshot
chrome-devtools take_snapshot --verbose=true --filePath snapshot.txt
chrome-devtools click "1_3"
chrome-devtools click "1_3" --includeSnapshot=true
chrome-devtools fill "1_5" "text"
chrome-devtools fill_form '[{"uid":"1_5","value":"text"}]'
chrome-devtools hover "1_7"
chrome-devtools drag "1_8" "1_9"
chrome-devtools press_key "Enter"
chrome-devtools type_text "hello" --submitKey "Enter"
chrome-devtools upload_file "1_10" "./file.txt"
chrome-devtools handle_dialog accept

The UID shape varies by snapshot. Treat examples such as 1_3 as placeholders.

Runtime Debugging

chrome-devtools evaluate_script "() => document.title"
chrome-devtools evaluate_script "(node) => node.innerText" --args 1_4
chrome-devtools list_console_messages
chrome-devtools list_console_messages --types error
chrome-devtools get_console_message 1
chrome-devtools list_network_requests
chrome-devtools list_network_requests --resourceTypes Fetch
chrome-devtools get_network_request --reqid 1 --requestFilePath req.md --responseFilePath res.md
chrome-devtools take_screenshot --filePath page.png
chrome-devtools take_screenshot --uid "1_4" --filePath element.png

Emulation, Audits, And Performance

chrome-devtools emulate --viewport "390x844"
chrome-devtools emulate --colorScheme "dark"
chrome-devtools emulate --networkConditions "Offline"
chrome-devtools emulate --cpuThrottlingRate 4
chrome-devtools lighthouse_audit --mode "navigation"
chrome-devtools lighthouse_audit --mode "snapshot" --device "mobile"
chrome-devtools performance_start_trace --reload=true --autoStop=true
chrome-devtools performance_start_trace --reload=true --autoStop=false --filePath trace.json.gz
chrome-devtools performance_stop_trace --filePath trace.json
chrome-devtools performance_analyze_insight "1" "LCPBreakdown"
chrome-devtools take_memory_snapshot "./snap.heapsnapshot"

Navigate to the target URL before starting a trace when --reload or --autoStop is enabled.

Output And Troubleshooting

chrome-devtools take_snapshot --output-format=json
chrome-devtools status
chrome-devtools start --headless=true
chrome-devtools start --browserUrl http://127.0.0.1:9222
chrome-devtools stop

If actions fail because no daemon/browser is reachable, run status, then use start --help to choose launch flags. Stop the daemon when switching profiles, channels, or connection targets.

Installation

Install the package globally to make the chrome-devtools command available. You only need to do this the first time you use it.

npm i chrome-devtools-mcp@latest -g
chrome-devtools status # check if install worked.

Troubleshooting

• Command not found: If chrome-devtools is not recognized, ensure your global npm bin directory is in your system's PATH. Restart your terminal or source your shell configuration file (e.g., .bashrc, .zshrc).
• Permission errors: If you encounter EACCES or permission errors during installation, avoid using sudo. Instead, use a node version manager like nvm, or configure npm to use a different global directory.
• Old version running: Run chrome-devtools stop && npm uninstall -g chrome-devtools-mcp before reinstalling, or ensure the latest version is being picked up by your path.