aeroxy/chrome-devtools-cli/chrome-devtools

Chrome DevTools CLI

A CLI that talks directly to your running Chrome via the DevTools Protocol.

Prerequisites

The browser must have remote debugging enabled:

1. Open Chrome (or Edge)
2. Go to chrome://inspect/#remote-debugging (Edge: edge://inspect/#remote-debugging)
3. Enable the remote debugging server

This is a persistent, in-browser toggle — not a launch flag. Three things follow from that, and they are what make it the right route for attaching to an everyday browser:

• It takes effect immediately. The server starts on the already-running

process; no restart, no relaunch, nothing to quit.

• It survives restarts. The choice is stored in the profile's Local State

as devtools.remote_debugging.user-enabled, so every later launch serves a port with no flags. To check whether a profile has it on, read that key.

• It is per-browser and per-profile. Enabling it in Chrome does nothing for

Edge, and vice versa — each has its own toggle and its own Local State.

The port is chosen by the browser and recorded in <user-data-dir>/DevToolsActivePort. Read that file rather than assuming a number: it differs per browser and can change between launches. Auto-connect does this for you, which is why no URL is needed. A daemon is spawned on first invocation and reused across commands (5-minute idle timeout by default, set by DAEMON_IDLE_TIMEOUT_SECS).

If the OS will not let the CLI read that file, remote debugging is usually still on. For the default profile the CLI then connects to port 9222 instead and prints Warning: cannot read ...DevToolsActivePort: Operation not permitted .... To use another port, pass --port <n> with the port shown at chrome://inspect/#remote-debugging. --port also works for a browser launched with --remote-debugging-port. See "Failure Handling: cannot read DevToolsActivePort" below for what to tell the user.

Microsoft Edge works the same — it is Chromium and speaks the same protocol. Add --browser edge so auto-connect reads Edge's profile instead of Chrome's (--channel still selects stable/beta/dev/canary, except that Edge ships no Canary for Linux — --browser edge --channel canary is rejected there rather than pointed at a directory that cannot exist). --ws-endpoint and --user-data-dir already say where to connect, so --browser is not needed to reach Edge — but pass it anyway when you are targeting Edge, because it is also the label recorded for the daemon (list-daemons) and the browser named in connection errors. Without it both say Chrome, the default, whatever the endpoint points at. Everything below applies unchanged — only the profile location differs.

The --remote-debugging-port launch flag is the other route, and it is for a throwaway instance rather than your everyday browser — see the headless recipe below. Two traps if you reach for it: it is ignored when that profile is already running (the launch hands off to the existing process and no port file appears, so quit first or use a different --user-data-dir), and a fresh Edge profile is not the clean room it looks like — Edge's first-run import pulls open tabs and extensions from your default browser, so a mktemp -d profile can come up holding your real session.

⚠️ Critical: How Page Targeting Works

Targets are NOT arbitrary strings. You cannot use --target main, --target page1, or any made-up name.

Targets are friendly word-pair names (like warm-squid, pink-hen) that the CLI derives from Chrome's internal target IDs. You get them from command output — never invent them.

Names are stable for the lifetime of a tab — navigating within the same tab keeps the same target name; closing and reopening the tab gives a new name.

The Correct Workflow

Step 1: Run `list-pages` to see what's open and get target names

chrome-devtools list-pages

Output:

[0] (warm-squid) Your Repositories — https://github.com/aeroxy
[1] (pink-hen) Gmail — https://mail.google.com
[2] (hazy-vole) Example — https://example.com

Step 2: Use the friendly name from the output in subsequent commands

chrome-devtools --target warm-squid navigate https://example.com
chrome-devtools --target pink-hen screenshot --output screenshot.png

Alternative: Use `--page <index>` for numeric indexing (0-based)

chrome-devtools --page 0 navigate https://example.com

If both `--target` and `--page` are omitted, the command runs on page 0 (leftmost tab). This is fine for single-tab workflows but should generally be avoided — always pin to a known page.

Core Capabilities

• Navigation: navigate, navigate --back, navigate --forward, navigate --reload
• Page management: list-pages, new-page, close-page, select-page
• Extraction: screenshot, snapshot (accessibility tree), evaluate (JavaScript), read-page (page content as markdown), run-script (run local JS file), adapter (run site adapter)
• Interaction: click, fill, type-text, press-key, hover, click-at
• Emulation: emulate (viewport, mobile, geolocation, URL blocking)
• Inspection: console (logs), network (requests), sw-logs (extension service workers)
• Third-party tools: list-3p-tools, execute-3p-tool (tools exposed by window.__dtmcp)
• Synchronization: wait-for (wait for text on page)
• Daemon control: kill-daemon

Standard Patterns

Pattern 1: Navigate and Interact

navigate and new-page print the target name at the end — capture it to pin subsequent commands.

# 1. List pages to find target
chrome-devtools list-pages
 
# 2. Navigate (target name shown at end of output)
chrome-devtools --target warm-squid navigate https://example.com
# stdout: Navigated to https://example.com
# stderr: [navigated to: https://example.com]
# stderr: [target:warm-squid]
 
# 3. Pin all subsequent commands to this page
chrome-devtools --target warm-squid screenshot --output page.png
chrome-devtools --target warm-squid evaluate "document.title"
 
# 4. Open a new tab — capture the NEW target name from output
chrome-devtools new-page https://github.com
# stdout: Opened new page: https://github.com (target: icy-goat)
# stderr: [target:icy-goat]  ← new tab, new target
chrome-devtools --target icy-goat snapshot

Note: The [navigated to: ...] and [target:...] lines go to stderr, not stdout. The stdout contains only the main command output ("Navigated to …", "Opened new page: …").

Pattern 2: Emulation (Viewport & Geolocation)

Overrides are per-tab: each page keeps its own viewport/geolocation/URL-blocks, persisting across navigation within that tab and isolated from other tabs (until cleared, the tab closes, or the daemon exits). emulate with no flags shows the active tab's state.

# Set viewport and geolocation
chrome-devtools --target warm-squid emulate --viewport 1920x1080 --geolocation 40.71,-74.00
 
# Emulate mobile device
chrome-devtools --target warm-squid emulate --viewport 375x812 --mobile --device-scale-factor 3
 
# Navigate with emulation (emulation applied before URL loads)
chrome-devtools --target warm-squid navigate https://example.com --viewport 375x812 --mobile
 
# Open new tab with emulation
chrome-devtools new-page https://example.com --viewport 375x812
 
# Show current overrides
chrome-devtools --target warm-squid emulate
# Output: No emulation overrides active.  (or lists current blocks/viewport/etc.)
 
# Clear emulation overrides
chrome-devtools --target warm-squid emulate --clear-all        # clears everything
chrome-devtools --target warm-squid emulate --clear-viewport   # clears viewport only
chrome-devtools --target warm-squid emulate --clear-geolocation

Pattern 3: URL Blocking (Network Debugging)

Block URL patterns using simple * wildcards: *.png (all PNG files), cdn.example.com/* (a domain path), *analytics* (any URL containing "analytics"). Patterns persist in the daemon until cleared.

Scope: blocking applies to subresources the page loads (images, scripts, fetch/XHR, stylesheets, CDN, trackers). It does not block the top-level navigation document itself — e.g. --block-url "*example.com*" then navigate https://example.com still loads the page, but any example.com subresources are blocked. This is a Chrome Network.setBlockedURLs limitation, not a CLI bug.

# Add block patterns
chrome-devtools --target warm-squid emulate --block-url "*.png"
chrome-devtools --target warm-squid emulate --block-url "*.ico" --block-url "*.svg"
 
# Block while navigating (inline)
chrome-devtools --target warm-squid --block-url "*.png" navigate https://example.com
 
# Show current blocks
chrome-devtools --target warm-squid emulate
# Output: Blocked URLs:
#           *.png
#           *.ico
#           *.svg
 
# Remove a specific pattern from the blocklist
chrome-devtools --target warm-squid emulate --unblock-url "*.png"
# (Note: --unblock-url REMOVES that pattern from the blocklist. There is no separate "allowlist".)
 
# Clear all blocks
chrome-devtools --target warm-squid emulate --clear-blocks
chrome-devtools --target warm-squid emulate --clear-all

Pattern 4: Form Interaction

Two ways to fill inputs — choose based on what the site expects:

• fill sets the value directly via element.value = .... Fast, no key events. Works for text inputs, textareas, <select>, checkboxes, radio buttons. Often breaks React/Vue apps because these frameworks rely on real input events.
• type-text dispatches individual keyboard events. Slower but triggers all the input, compositionstart/end, etc. events that frameworks listen for. Use this when `fill` seems to "not work" on interactive frameworks.

# Click an element by CSS selector
chrome-devtools --target warm-squid click "button.submit"
 
# Click at viewport-relative coordinates (0,0 is top-left of the visible viewport)
chrome-devtools --target warm-squid click-at 100 200
 
# Fill a text input (fast, no key events)
chrome-devtools --target warm-squid fill "input.search" "search query"
 
# Type text one char at a time (use for React/Vue/form-validation sites)
chrome-devtools --target warm-squid type-text "search query" --submit-key Enter
 
# Press a key or key combo. Examples: Enter, Tab, Escape, ArrowDown,
# Control+A, Meta+C, Shift+Tab, Backspace, Space.
chrome-devtools --target warm-squid press-key Enter
chrome-devtools --target warm-squid press-key Control+A
 
# Hover over an element
chrome-devtools --target warm-squid hover ".menu-item"
 
# Wait for text to appear (default timeout: 30 seconds = 30000 ms)
chrome-devtools --target warm-squid wait-for "Results" --timeout 10000

Pattern 5: Console & Network Inspection

The daemon maintains a persistent session for the current page that continuously collects network and console events across commands.

console and network return accumulated events and clear the buffer (drain). A second call immediately after returns empty unless new events arrived. Use this for inspecting what happened; use --duration for live monitoring.

# Navigate (generates network + console events)
chrome-devtools --target warm-squid navigate https://example.com
 
# Drain accumulated network requests (instant, non-blocking)
chrome-devtools --target warm-squid network
 
# Drain console messages
chrome-devtools --target warm-squid console
 
# Filter by console type: log, warning, error, info, debug, exception
chrome-devtools --target warm-squid console --type error --type warning
 
# Filter network by resource type (case-sensitive): Document, Script, Stylesheet,
# Image, Font, XHR, Fetch, Manifest, Media, WebSocket, Other
chrome-devtools --target warm-squid network --type Fetch --type XHR