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 "user@example.com"
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

Author: Minsu Lee (@amondnet)

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.claude-pllugin		.claude-pllugin
.github/workflows		.github/workflows
.husky		.husky
.please		.please
docs		docs
examples		examples
scripts		scripts
skills/chrome-devtools-cli-usage		skills/chrome-devtools-cli-usage
src		src
test		test
.gitignore		.gitignore
.gitmodules		.gitmodules
.lintstagedrc.json		.lintstagedrc.json
.npmignore		.npmignore
.prettierignore		.prettierignore
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
bunfig.toml		bunfig.toml
commitlint.config.js		commitlint.config.js
eslint.config.js		eslint.config.js
install.sh		install.sh
package.json		package.json
release-please-config.json		release-please-config.json
tsconfig.json		tsconfig.json

License

pleaseai/chrome-devtools-cli

Folders and files

Latest commit

History

Repository files navigation

Chrome DevTools CLI

Features

Installation

Homebrew (Recommended for macOS/Linux)

Binary Download

Quick Install (Recommended)

Manual Installation

npm/Bun

Local Installation (as library)

Claude Code Plugin

Add Marketplace

Install Plugin

Quick Start

Launch Chrome and Navigate

Take a Screenshot

Analyze Performance

Monitor Network Requests

Usage

Global Options

Commands

Input Automation

Click on Element

Hover over Element

Fill Input Field

Press Keyboard Key

Drag and Drop

Upload File

Handle Dialog

Navigation

List Pages

Select Page

Close Page

Create New Page

Navigate Page

Wait for Element or Text

Emulation

Emulate Device

Resize Viewport

Performance

Start Performance Trace

Stop Performance Trace

Analyze Performance

Network

Start Monitoring

List Network Requests

Get Request Details

Clear Request History

Debugging

Start Console Monitoring

List Console Messages

Get Console Message

Clear Console History

Evaluate JavaScript

Take Screenshot

Take Page Snapshot

Browser Management

Close Browser

Output Formats

Text (Default)

JSON

TOON

Advanced Usage

Connecting to Existing Chrome Instance

Step 1: Start Chrome with Remote Debugging

Step 2: Connect via CLI

Using WebSocket Endpoint

Headless Mode

Custom Chrome Channel

Isolated Mode (Temporary Profile)

Examples

Complete Automation Workflow

Performance Testing

Mobile Emulation Testing

Architecture

Packages