Chrome DevTools CLI

chrome-devtools-cli lets you control and inspect a live Chrome browser from the command line. It provides direct CLI access to the full power of Chrome DevTools for reliable automation, in-depth debugging, and performance analysis - perfect for developers, scripts, and CI/CD pipelines.

Inspired by Chrome DevTools MCP, this CLI tool provides similar browser automation capabilities with superior token efficiency (~58.9% reduction via TOON format) - ideal for LLM-powered automation workflows.

Features

• 🎯 Input Automation: Click, hover, fill forms, drag-and-drop, keyboard input
• 🧭 Navigation: Multi-page management, URL navigation, wait conditions
• 📱 Emulation: Device emulation, viewport resizing
• ⚡ Performance: Trace recording, performance analysis
• 🌐 Network: Request monitoring, inspection
• 🐛 Debugging: Console monitoring, script evaluation, screenshots, snapshots
• 🎨 Multiple Output Formats: JSON, TOON, or human-readable text
• 🔧 Flexible Browser Connection: Launch new instances or connect to existing Chrome

Installation

Homebrew (Recommended for macOS/Linux)

# Add tap
brew tap pleaseai/tap

# Install
brew install chrome-devtools-cli

# Or one-liner
brew install pleaseai/tap/chrome-devtools-cli

Update:

brew upgrade chrome-devtools-cli

Binary Download

Download pre-built binaries from GitHub Releases:

Quick Install (Recommended)

Auto-detects your platform and architecture:

curl -fsSL https://raw.githubusercontent.com/pleaseai/chrome-devtools-cli/main/install.sh | bash

Or download and run the script manually:

curl -fsSL https://raw.githubusercontent.com/pleaseai/chrome-devtools-cli/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

Manual Installation

# macOS (Apple Silicon)
curl -L https://github.com/pleaseai/chrome-devtools-cli/releases/latest/download/chrome-devtools-darwin-arm64 -o chrome-devtools
chmod +x chrome-devtools
sudo mv chrome-devtools /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/pleaseai/chrome-devtools-cli/releases/latest/download/chrome-devtools-darwin-x64 -o chrome-devtools
chmod +x chrome-devtools
sudo mv chrome-devtools /usr/local/bin/

# Linux (ARM64)
curl -L https://github.com/pleaseai/chrome-devtools-cli/releases/latest/download/chrome-devtools-linux-arm64 -o chrome-devtools
chmod +x chrome-devtools
sudo mv chrome-devtools /usr/local/bin/

# Linux (x64)
curl -L https://github.com/pleaseai/chrome-devtools-cli/releases/latest/download/chrome-devtools-linux-x64 -o chrome-devtools
chmod +x chrome-devtools
sudo mv chrome-devtools /usr/local/bin/

npm/Bun

# Global installation
npm install -g @pleaseai/chrome-devtools-cli
# or
bun add -g @pleaseai/chrome-devtools-cli

Local Installation (as library)

npm install @pleaseai/chrome-devtools-cli
# or
bun add @pleaseai/chrome-devtools-cli

Claude Code Plugin

Install as a plugin for Claude Code to get integrated skill documentation and automation support.

Add Marketplace

/plugin marketplace add pleaseai/claude-code-plugins

Install Plugin

/plugin install chrome-devtools-cli@pleaseai

Once installed, access comprehensive usage skills directly within Claude Code with automated guidance for browser automation, debugging, and performance testing workflows.

Quick Start

Launch Chrome and Navigate

# Open a new page
chrome-devtools nav new-page --url https://example.com

# Navigate current page
chrome-devtools nav navigate --url https://google.com

Take a Screenshot

chrome-devtools debug screenshot --path screenshot.png --full-page

Analyze Performance

chrome-devtools perf analyze --url https://example.com --format json

Monitor Network Requests

# Start monitoring
chrome-devtools network start-monitoring

# List requests
chrome-devtools network list-requests --format toon

Usage

Global Options

chrome-devtools [global-options] <command> [command-options]

Global Options:

• --browser-url <url> - Connect to running Chrome via port forwarding
• --ws-endpoint <endpoint> - WebSocket endpoint for Chrome
• --ws-headers <headers> - Custom WebSocket headers (JSON)
• --headless - Run in headless mode
• --executable-path <path> - Path to Chrome executable
• --isolated - Use temporary user data directory
• --channel <channel> - Chrome channel (stable|canary|beta|dev)
• --viewport <viewport> - Initial viewport size (e.g., 1280x720)
• --proxy-server <proxy> - Proxy server configuration
• --accept-insecure-certs - Ignore certificate errors
• --format <format> - Output format (json|toon|text)

Commands

Input Automation

Click on Element

chrome-devtools input click --uid <element-uid>
chrome-devtools input click --uid <element-uid> --dbl-click

Hover over Element

chrome-devtools input hover --uid <element-uid>

Fill Input Field

chrome-devtools input fill --uid <element-uid> --value "text"

Press Keyboard Key

chrome-devtools input press-key --key Enter
chrome-devtools input press-key --key "Control+C"

Drag and Drop

chrome-devtools input drag --from <source-uid> --to <target-uid>

Upload File

chrome-devtools input upload-file --uid <input-uid> --file /path/to/file.pdf

Handle Dialog

chrome-devtools input handle-dialog --action accept
chrome-devtools input handle-dialog --action dismiss
chrome-devtools input handle-dialog --action accept --prompt-text "my input"

Navigation

List Pages

chrome-devtools nav list-pages
chrome-devtools nav list-pages --format json

Select Page

chrome-devtools nav select-page --index 0

Close Page

chrome-devtools nav close-page --index 1

Create New Page

chrome-devtools nav new-page --url https://example.com
chrome-devtools nav new-page --url https://example.com --timeout 30000

Navigate Page

chrome-devtools nav navigate --url https://example.com

Wait for Element or Text

chrome-devtools nav wait-for --selector "#my-element"
chrome-devtools nav wait-for --text "Welcome"
chrome-devtools nav wait-for --selector ".button" --timeout 5000

Emulation

Emulate Device

chrome-devtools emulate device --name "iPhone 13"
chrome-devtools emulate device --name "iPad Pro"

Resize Viewport

chrome-devtools emulate resize --width 1920 --height 1080

Performance

Start Performance Trace

chrome-devtools perf start-trace

Stop Performance Trace

chrome-devtools perf stop-trace --output trace.json

Analyze Performance

chrome-devtools perf analyze --url https://example.com
chrome-devtools perf analyze --url https://example.com --duration 5000 --format json

Network

Start Monitoring

chrome-devtools network start-monitoring

List Network Requests

chrome-devtools network list-requests
chrome-devtools network list-requests --limit 10 --offset 0 --format toon

Get Request Details

chrome-devtools network get-request --id req-123

Clear Request History

chrome-devtools network clear

Debugging

Start Console Monitoring

chrome-devtools debug start-console-monitoring

List Console Messages

chrome-devtools debug list-console
chrome-devtools debug list-console --types error,warning --format json

Get Console Message

chrome-devtools debug get-console --id msg-123

Clear Console History

chrome-devtools debug clear-console

Evaluate JavaScript

chrome-devtools debug evaluate --script "document.title"
chrome-devtools debug evaluate --script "window.innerWidth" --format json

Take Screenshot

chrome-devtools debug screenshot --path screenshot.png
chrome-devtools debug screenshot --path screenshot.jpg --type jpeg --quality 80
chrome-devtools debug screenshot --full-page --path full-page.png

Take Page Snapshot

chrome-devtools debug snapshot
chrome-devtools debug snapshot --verbose

Browser Management

Close Browser

chrome-devtools close

Output Formats

Text (Default)

Human-readable output format for console display.

chrome-devtools nav list-pages

JSON

Standard JSON format for programmatic consumption.

chrome-devtools nav list-pages --format json

TOON

Token-optimized format that reduces output size by ~58.9% compared to JSON, ideal for LLM processing.

chrome-devtools nav list-pages --format toon

Advanced Usage

Connecting to Existing Chrome Instance

Step 1: Start Chrome with Remote Debugging

macOS:

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

Linux:

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

Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir="%TEMP%\chrome-profile"

Step 2: Connect via CLI

chrome-devtools --browser-url http://127.0.0.1:9222 nav list-pages

Using WebSocket Endpoint

# Get WebSocket URL from http://127.0.0.1:9222/json/version
chrome-devtools --ws-endpoint ws://127.0.0.1:9222/devtools/browser/<id> nav list-pages

Headless Mode

chrome-devtools --headless nav new-page --url https://example.com
chrome-devtools --headless debug screenshot --path screenshot.png

Custom Chrome Channel

chrome-devtools --channel canary nav new-page --url https://example.com
chrome-devtools --channel beta perf analyze --url https://example.com

Isolated Mode (Temporary Profile)

chrome-devtools --isolated nav new-page --url https://example.com

Examples

Complete Automation Workflow

# 1. Start console and network monitoring
chrome-devtools debug start-console-monitoring
chrome-devtools network start-monitoring

# 2. Navigate to a page
chrome-devtools nav new-page --url https://example.com

# 3. Interact with the page
chrome-devtools input fill --uid input-email --value "[email protected]"
chrome-devtools input fill --uid input-password --value "password123"
chrome-devtools input click --uid button-login

# 4. Wait for navigation
chrome-devtools nav wait-for --text "Dashboard"

# 5. Take a screenshot
chrome-devtools debug screenshot --path dashboard.png

# 6. Get console errors
chrome-devtools debug list-console --types error --format json

# 7. Get network requests
chrome-devtools network list-requests --format toon

# 8. Clean up
chrome-devtools close

Performance Testing

# Analyze performance with trace
chrome-devtools perf start-trace
chrome-devtools nav new-page --url https://example.com
chrome-devtools nav wait-for --timeout 5000
chrome-devtools perf stop-trace --output trace.json

# Or use the combined analyze command
chrome-devtools perf analyze \
  --url https://example.com \
  --duration 10000 \
  --format json > performance-report.json

Mobile Emulation Testing

# Test on iPhone
chrome-devtools emulate device --name "iPhone 13"
chrome-devtools nav new-page --url https://example.com
chrome-devtools debug screenshot --path mobile-view.png

# Test on iPad
chrome-devtools emulate device --name "iPad Pro"
chrome-devtools nav navigate --url https://example.com
chrome-devtools debug screenshot --path tablet-view.png

# Custom viewport
chrome-devtools emulate resize --width 375 --height 667

Architecture

This CLI provides browser automation capabilities using:

• Puppeteer - Browser automation
• Commander.js - CLI framework
• @pleaseai/cli-toolkit - Output formatting and utilities

Project Structure

chrome-devtools-cli/
├── src/
│   ├── browser/         # Browser management utilities
│   ├── commands/        # Command implementations
│   │   ├── input.ts     # Input automation
│   │   ├── navigation.ts # Navigation commands
│   │   ├── emulation.ts # Device emulation
│   │   ├── performance.ts # Performance analysis
│   │   ├── network.ts   # Network inspection
│   │   └── debugging.ts # Debugging tools
│   ├── cli.ts          # CLI entry point
│   ├── types.ts        # TypeScript types
│   └── index.ts        # Library exports
├── references/
│   └── chrome-devtools-mcp/ # Submodule reference
└── package.json

API Reference

The CLI can also be used programmatically:

import {
  click,
  closeBrowser,
  getBrowser,
  navigatePage,
  performanceAnalyzeInsight,
  takeScreenshot,
} from '@pleaseai/chrome-devtools-cli'

// Navigate to a page
await navigatePage({ url: 'https://example.com' })

// Take a screenshot
const screenshot = await takeScreenshot({
  path: 'screenshot.png',
  fullPage: true,
})

// Analyze performance
const perfData = await performanceAnalyzeInsight({
  url: 'https://example.com',
})

// Clean up
await closeBrowser()

Comparison with Chrome DevTools MCP

| Feature | Chrome DevTools MCP | Chrome DevTools CLI | | -------------------- | ------------------------------- | --------------------------- | | Interface | MCP Server | CLI Commands | | Usage | AI Assistants (Claude, Copilot) | Command Line / Scripts | | Output Format | MCP Protocol | JSON / TOON / Text | | Token Efficiency | Standard | ~58.9% reduction (TOON) | | Browser Control | ✅ | ✅ | | Performance Analysis | ✅ | ✅ | | Network Inspection | ✅ | ✅ | | Debugging Tools | ✅ | ✅ | | Automation Scripts | ❌ | ✅ | | Programmatic API | ❌ | ✅ |

Requirements

• Node.js v20.19 or newer (LTS version)
• Chrome current stable version or newer
• npm or Bun

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © PleaseAI

Credits

This project is inspired by the excellent Chrome DevTools MCP by Google LLC.

Related Projects

• Chrome DevTools MCP - MCP server for Chrome DevTools
• @pleaseai/cli-toolkit - CLI utilities for LLM-focused tools
• Puppeteer - Headless Chrome Node.js API

Support

• GitHub Issues
• Documentation

Author: Minsu Lee (@amondnet)