Skip to content

cli.md

Latest commit

 

History

History
143 lines (98 loc) · 5.06 KB

cli.md

File metadata and controls

143 lines (98 loc) · 5.06 KB
Raw

Chrome DevTools CLI

The chrome-devtools-mcp package includes a CLI interface that allows you to interact with the browser directly from your terminal. This is particularly useful for debugging or when you want an agent to generate scripts that automate browser actions.

Getting started

Install the package globally to make the chrome-devtools command available:

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

The CLI enables unrestricted filesystem access by default. Use --workspace to limit file tools to specific directories. Repeat the flag for more than one directory. --allow-unrestricted-paths still works on its own for compatibility, but it cannot be combined with --workspace.

chrome-devtools start --workspace=/path/to/project --workspace=/path/to/output

Agent skill

The chrome-devtools-cli skill teaches your agent how to use the CLI. Plugin installs include this skill. To install it manually, copy the skill folder into the skills directory of your agent:

# Example for Claude Code. Use the skills directory of your agent.
mkdir -p ~/.claude/skills
cp -R "$(npm root -g)/chrome-devtools-mcp/skills/chrome-devtools-cli" ~/.claude/skills/

See Skills for all skills and installation options.

Note

Copy the skill again each time you update the CLI. See Keep skills up to date.

How it works

The CLI acts as a client to a background chrome-devtools-mcp daemon (uses Unix sockets on Linux/Mac and named pipes on Windows).

  • Automatic Start: The first time you call a tool (e.g., list_pages), the CLI automatically starts the MCP server and the browser in the background if they aren't already running.
  • Persistence: The same background instance is reused for subsequent commands, preserving the browser state (open pages, cookies, etc.).
  • Manual Control: You can explicitly manage the background process using start, stop, and status. The start command forwards all subsequent arguments to the underlying MCP server (e.g., --headless, --userDataDir) but not all args are supported. Run chrome-devtools start --help for supported args. Headless is enabled by default. Isolated is enabled by default unless --userDataDir is provided.
# Check if the daemon is running
chrome-devtools status

# Navigate page 1 to a URL
chrome-devtools navigate_page 1 --url "https://google.com"

# Take a screenshot of page 1 and save it to a file
chrome-devtools take_screenshot 1 --filePath screenshot.png

# Stop the background daemon when finished
chrome-devtools stop

Command Usage

The CLI supports all tools available in the MCP server even if they require a flag to activate in the MCP server (see Tool reference).

chrome-devtools <tool> [arguments] [flags]
  • Required Arguments: Passed as positional arguments. Page-scoped tools require <pageId> as their first positional argument.
  • Optional Arguments: Passed as flags (e.g., --filePath, --fullPage).

Examples

New Page and Navigation:

chrome-devtools new_page "https://example.com"
chrome-devtools navigate_page 1 --url "https://web.dev"

Interaction:

# Click an element by its UID from a snapshot on page 1
chrome-devtools click 1 "element-uid-123"

# Fill a form field on page 1
chrome-devtools fill 1 "input-uid-456" "search query"

Script Evaluation:

  • When --categoryExtensions and --pageIdRouting are enabled:
    • Target a page using --pageId <number>: chrome-devtools evaluate_script "() => document.title" --pageId 1
    • Target an extension service worker using --serviceWorkerId <string>: chrome-devtools evaluate_script "() => self.registration.scope" --serviceWorkerId sw-1
# Evaluate a JavaScript expression on page 1
chrome-devtools evaluate_script "() => document.title" --pageId 1

# Evaluate inside an extension service worker
chrome-devtools evaluate_script "() => self.registration.scope" --serviceWorkerId sw-1

Analysis:

# Run a Lighthouse audit on page 1 (defaults to navigation mode)
chrome-devtools lighthouse_audit 1 --mode snapshot

Output format

By default, the CLI outputs a human-readable summary of the tool's result. For programmatic use, you can request raw JSON:

chrome-devtools list_pages --output-format=json

Troubleshooting

If the CLI hangs or fails to connect, try stopping the background process:

chrome-devtools stop

For more verbose logs, set the NODE_DEBUG environment variable. The background process does not write to the terminal, so restart it with --logFile to capture its logs in a file:

NODE_DEBUG=* chrome-devtools start --logFile=/tmp/chrome-devtools.log
chrome-devtools list_pages

CLI generation

Implemented in scripts/generate-cli.ts. Some commands are excluded from CLI generation such as wait_for and fill_form.

chrome-devtools-mcp args are also filtered in src/bin/chrome-devtools.ts because not all args make sense in a CLI interface.