Imported from finas/browser-cli (SKILL.md). Install upstream with npx skills add finas/browser-cli. Copyright stays with the author.

Chrome DevTools Skill

This skill enables browser automation and debugging using Chrome DevTools Protocol via MCP.

Quick Start

Prerequisites

Chrome must be running with remote debugging enabled:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

# Linux
/usr/bin/google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-profile-stable

Installation

cd ./cli
npm install
npm link

Key Concepts

Page IDs

Commands that accept URLs and navigate to them will return a page ID (page number). This ID can be used with page management commands like select-page and close-page. Page IDs are simple numbers (1, 2, 3...) assigned by Chrome.

Example:

cdp-cli navigate https://example.com
# Output: Page ID: 1

cdp-cli screenshot output.png https://github.com
# Output: Page ID: 2

# Use these IDs to manage pages
cdp-cli select-page 1
cdp-cli close-page 2

Persistent Browser Session

All commands work with the same Chrome instance. The browser stays open between commands, allowing you to:

• Navigate once, then take multiple screenshots/snapshots
• Build up page state across multiple commands
• Inspect and interact with the current page without re-navigating

Element UIDs

Interaction commands (click, hover, fill) require element UIDs from snapshots, not CSS selectors. This ensures reliable element targeting through Chrome's accessibility tree.

Available Commands

Navigation & Page Management

Navigate to URL

cdp-cli navigate <url>

Navigate to any URL in Chrome. Returns the page ID (page number) of the navigated page.

Example:

cdp-cli navigate https://example.com
# Output includes: Page ID: 1

List Open Pages

cdp-cli pages
# or
cdp-cli list-pages

List all open browser tabs/pages with their IDs and URLs. Returns page numbers (1, 2, 3...) that can be used with other page management commands.

Create New Page

cdp-cli new-page <url>

Open a new browser tab and navigate to URL.

Example:

cdp-cli new-page https://github.com

Select Page

cdp-cli select-page <pageId>

Switch to a specific page using its ID from pages command.

Close Page

cdp-cli close-page <pageId>

Close a specific page using its ID.

Debugging & Inspection

Take Screenshot

cdp-cli screenshot <output.png> [url]

Capture a screenshot. Output filename is required. If URL is provided, navigates first and returns the page ID. Otherwise, captures current page.

Examples:

# Screenshot current page (no navigation)
cdp-cli navigate https://example.com
cdp-cli screenshot current-page.png

# Navigate and screenshot (returns page ID)
cdp-cli screenshot homepage.png https://example.com
# Output: Page ID: 1

Note: Screenshots are saved relative to your current directory. The full path is displayed after saving.

DOM Snapshot

cdp-cli snapshot [url]

Capture accessibility tree snapshot with element UIDs. If URL is provided, navigates first and returns the page ID. Otherwise, captures current page.

Example:

# Navigate and snapshot (returns page ID)
cdp-cli snapshot https://example.com
# Output: Page ID: 1

# Snapshot current page
cdp-cli navigate https://example.com
cdp-cli snapshot

Output shows elements with UIDs:

uid: "123" role: "button" name: "Submit"
uid: "456" role: "textbox" name: "Email"
uid: "789" role: "link" name: "More information"

Use these UIDs for interaction commands (click, hover, fill).

Console Logs

cdp-cli console [url]

Capture and display console messages (logs, warnings, errors). If URL is provided, navigates first. Otherwise, captures from current page.

Examples:

# Console logs from current page
cdp-cli navigate https://myapp.com
cdp-cli console

# Navigate and get console logs
cdp-cli console https://myapp.com

Execute JavaScript

cdp-cli evaluate <function> [url]

Execute JavaScript function. Function is required. If URL is provided, navigates first and returns the page ID. Otherwise, executes on current page.

Examples:

# Execute on current page
cdp-cli navigate https://example.com
cdp-cli evaluate "() => document.title"

# Navigate and execute (returns page ID)
cdp-cli evaluate "() => document.title" https://example.com
# Output: Page ID: 1

# Count links on current page
cdp-cli evaluate "() => document.querySelectorAll('a').length"

# Get computed style
cdp-cli evaluate "() => getComputedStyle(document.body).backgroundColor"

Performance & Auditing

Performance Analysis

cdp-cli performance <url>

Analyze page performance with Chrome DevTools traces. Provides metrics like LCP, FID, CLS.

Example:

cdp-cli performance https://developers.chrome.com

Lighthouse Audit

cdp-cli lighthouse <url>

Run comprehensive Lighthouse audit covering performance, accessibility, best practices, and SEO. Returns the page ID after navigation.

Example:

cdp-cli lighthouse https://example.com
# Output: Page ID: 1

Note: Lighthouse audits take 30-60 seconds to complete.

Network Monitoring

cdp-cli network [url]

Capture network requests. If URL is provided, navigates first. Otherwise, captures from current page.

Examples:

# Network requests from current page
cdp-cli navigate https://example.com
cdp-cli network

# Navigate and capture network
cdp-cli network https://example.com

Element Interaction

Important: Interaction commands require element UIDs from the snapshot command, not CSS selectors.

Workflow for Interaction

1. First, get element UIDs:

cdp-cli snapshot https://example.com

2. Find the element you want to interact with in the output (look for uid: "xxx")

3. Use that UID in interaction commands:

Click Element

cdp-cli click <url> <uid>

Click an element and returns the page ID after navigation.

Example:

# Get UIDs first
cdp-cli snapshot https://example.com
# Output: uid: "123" role: "link" name: "More information"

# Click that element (returns page ID)
cdp-cli click https://example.com "123"
# Output: Page ID: 1

Hover Element

cdp-cli hover <url> <uid>

Hover over an element to trigger tooltips, dropdowns, etc. Returns the page ID after navigation.

Example:

cdp-cli hover https://example.com "456"
# Output: Page ID: 1

Fill Input

cdp-cli fill <url> <uid> <value>

Fill an input field, textarea, or select element. Returns the page ID after navigation.

Example:

# Get input field UID from snapshot
cdp-cli snapshot https://www.google.com
# Output: uid: "789" role: "textbox" name: "Search"

# Fill the input (returns page ID)
cdp-cli fill https://www.google.com "789" "test query"
# Output: Page ID: 1

Device Emulation

Emulate Device

cdp-cli emulate <url> "<device>"

Emulate mobile devices or tablets with proper viewport and user agent.

Supported Devices:

• iPhone 12, iPhone 13, iPhone 14
• iPad Pro, iPad Mini
• Pixel 5, Pixel 7
• Galaxy S21, Galaxy S22
• And many more...

Examples:

cdp-cli emulate https://example.com "iPhone 12"
cdp-cli emulate https://example.com "iPad Pro"
cdp-cli emulate https://example.com "Pixel 5"

Common Use Cases

1. E2E Testing Workflow

# Navigate to login page
cdp-cli navigate https://myapp.com/login

# Get element UIDs
cdp-cli snapshot

# Fill login form (using UIDs from snapshot)
cdp-cli fill https://myapp.com/login "email-uid" "user@example.com"
cdp-cli fill https://myapp.com/login "password-uid" "password123"

# Click submit button
cdp-cli click https://myapp.com/login "submit-uid"

# Verify success
cdp-cli console https://myapp.com/dashboard

2. Performance Monitoring

# Analyze performance
cdp-cli performance https://myapp.com

# Run full Lighthouse audit
cdp-cli lighthouse https://myapp.com

# Check network requests
cdp-cli network https://myapp.com

3. Visual Regression Testing

# Capture baseline
cdp-cli screenshot baseline.png https://myapp.com/dashboard

# Make changes...

# Capture new version
cdp-cli screenshot current.png https://myapp.com/dashboard

# Compare images externally

4. Mobile Responsiveness Testing

# Test on iPhone
cdp-cli emulate https://myapp.com "iPhone 12"
cdp-cli screenshot mobile-iphone.png

# Test on iPad
cdp-cli emulate https://myapp.com "iPad Pro"
cdp-cli screenshot mobile-ipad.png

# Test on Android
cdp-cli emulate https://myapp.com "Pixel 5"
cdp-cli screenshot mobile-android.png

5. Debugging JavaScript Errors

# Check console for errors
cdp-cli console https://myapp.com

# Execute debug script
cdp-cli evaluate https://myapp.com "() => { console.log('Debug info:', window.myApp); return window.myApp; }"

# Take DOM snapshot to inspect structure
cdp-cli snapshot https://myapp.com

6. Multi-Page Workflows

# Open multiple pages
cdp-cli new-page https://example.com
cdp-cli new-page https://github.com
cdp-cli new-page https://stackoverflow.com

# List all pages
cdp-cli pages

# Switch between pages (use IDs from pages output)
cdp-cli select-page <page-id-1>
cdp-cli screenshot page1.png

cdp-cli select-page <page-id-2>
cdp-cli screenshot page2.png

7. Form Automation

# Navigate to form
cdp-cli navigate https://forms.example.com

# Get form element UIDs
cdp-cli snapshot

# Fill all fields
cdp-cli fill https://forms.example.com "name-uid" "John Doe"
cdp-cli fill https://forms.example.com "email-uid" "john@example.com"
cdp-cli fill https://forms.example.com "message-uid" "Hello World"

# Submit form
cdp-cli click https://forms.example.com "submit-uid"

# Verify submission
cdp-cli console https://forms.example.com/success

8. Persistent Session Workflow

# Navigate once
cdp-cli navigate https://example.com

# Take multiple actions without re-navigating
cdp-cli snapshot                    # Get current page structure
cdp-cli screenshot page1.png        # Screenshot current state
cdp-cli console                     # Check console logs
cdp-cli network                     # Check network requests
cdp-cli evaluate "() => document.title"  # Run JavaScript

# Navigate to another page
cdp-cli navigate https://example.com/about

# Continue working with new page
cdp-cli snapshot
cdp-cli screenshot page2.png
cdp-cli evaluate "() => document.querySelectorAll('h1').length"

How It Works

The CLI connects to the chrome-devtools-mcp server, which provides access to Chrome DevTools Protocol through a standardized MCP interface. This allows programmatic control of Chrome for testing, debugging, and automation.

Architecture:

CLI (MCP Client) → MCP Server (chrome-devtools-mcp) → Chrome (port 9222)

Key Features:

• Persistent browser session across commands
• Element interaction via accessibility tree UIDs
• Full Chrome DevTools Protocol access
• Automatic error handling and validation

Tips & Best Practices

Element Interaction

• Always run snapshot first to get current element UIDs
• UIDs are unique per page load - get fresh UIDs after navigation
• Use descriptive element roles/names from snapshot to identify correct UIDs
• Wait for dynamic content to load before taking snapshots

Persistent Sessions

• Chrome stays open between commands - no need to re-navigate
• Take advantage of this for multi-step workflows
• Use snapshot without URL to inspect current page
• Use screenshot without URL to capture current page

Performance Testing

• Run performance tests multiple times for consistent results
• Clear cache between tests for accurate measurements
• Use headless mode for CI/CD environments
• Compare results against baseline metrics

Screenshots

• Screenshots are saved relative to current directory
• Full path is displayed after saving
• Use consistent viewport sizes for comparison
• Consider using device emulation for mobile screenshots
• Can screenshot current page without re-navigating

Network Debugging

• Network logs capture all requests since page load
• Check for failed requests (4xx, 5xx status codes)
• Monitor request sizes for performance optimization
• Use network logs to debug API issues

Console Logs

• Console logs include errors, warnings, and info messages
• Source-mapped stack traces are included when available
• Check console logs to debug JavaScript errors
• Logs are captured from page load until command execution

Lighthouse Audits

• Audits take 30-60 seconds to complete
• Run in headless mode for consistent results
• Focus on actionable recommendations
• Track scores over time to measure improvements

Troubleshooting

Chrome Not Connected

# Verify Chrome is running with remote debugging
curl http://127.0.0.1:9222/json/version

# If not, start Chrome with the correct flags
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile-stable

Error Message:

✗ Error: Chrome is not running with remote debugging enabled.

Solution: Start Chrome with the command shown above before running any CLI commands.

Element Not Found

# Get fresh snapshot to see current elements
cdp-cli snapshot

# Verify the UID exists in the snapshot output
# UIDs change after navigation - always get fresh UIDs

Screenshot Not Saved

• Check the full path displayed in the output
• Ensure you have write permissions in the current directory
• Verify the file extension is .png, .jpg, or .webp

Command Hangs

• Ensure Chrome is running and accessible
• Check that the MCP server can connect to Chrome
• Try closing and restarting Chrome

Invalid Function Error

# Ensure evaluate uses function declaration syntax
# ✅ Correct: "() => document.title"
# ❌ Wrong: "document.title"

# ✅ Correct: "() => { return window.location.href; }"
# ❌ Wrong: "window.location.href"

Advanced Usage

Scripting with CDP CLI

#!/bin/bash

# Automated testing script
URL="https://myapp.com"

echo "Running automated tests..."

# Navigate once
cdp-cli navigate $URL

# Run multiple tests on same page
cdp-cli performance $URL > performance-report.txt
cdp-cli lighthouse $URL > lighthouse-report.txt
cdp-cli screenshot screenshot-$(date +%Y%m%d).png
cdp-cli console $URL | grep -i error > errors.txt

echo "Tests complete!"

CI/CD Integration

# GitHub Actions example
- name: Run CDP CLI Tests
  run: |
    # Start Chrome in headless mode
    google-chrome --headless --remote-debugging-port=9222 --user-data-dir=/tmp/chrome &
    
    # Wait for Chrome to start
    sleep 2
    
    # Run tests
    cdp-cli performance https://myapp.com
    cdp-cli lighthouse https://myapp.com
    cdp-cli screenshot screenshot.png https://myapp.com

Related Tools

• chrome-devtools-mcp: The MCP server providing CDP access
• Puppeteer: Alternative Node.js library for Chrome automation
• Playwright: Cross-browser automation framework
• Selenium: Traditional browser automation tool

Resources

• Chrome DevTools Protocol Documentation
• chrome-devtools-mcp GitHub
• Model Context Protocol
• Lighthouse Documentation