Chrome DevTools CLI Usage Guide

chrome-devtools-cli provides command-line control of Chrome browsers for automation, debugging, and performance analysis. Perfect for developers, scripts, and CI/CD pipelines.

Quick Installation

# Homebrew (macOS/Linux)
brew install pleaseai/tap/chrome-devtools-cli

# Quick install script (auto-detects platform)
curl -fsSL https://raw.githubusercontent.com/pleaseai/chrome-devtools-cli/main/install.sh | bash

# npm/Bun
npm install -g @pleaseai/chrome-devtools-cli

Detailed installation: See [references/INSTALLATION.md](references/INSTALLATION.md)

Quick Start

Basic Navigation

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

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

# List all pages
chrome-devtools nav list-pages

Screenshots

# Standard screenshot
chrome-devtools debug screenshot --path screenshot.png

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

Performance Analysis

# Quick performance analysis
chrome-devtools perf analyze --url https://example.com --format json

Network Monitoring

# Start monitoring
chrome-devtools network start-monitoring

# List requests (TOON format for 58.9% token reduction)
chrome-devtools network list-requests --format toon

Essential Commands

Input Automation

# Click element
chrome-devtools input click --uid <element-uid>

# Fill input
chrome-devtools input fill --uid input-email --value "[email protected]"

# Press keys
chrome-devtools input press-key --key Enter

# Handle dialogs
chrome-devtools input handle-dialog --action accept

Page Navigation

# Create new page
chrome-devtools nav new-page --url <url>

# Wait for element
chrome-devtools nav wait-for --selector "#element"

# Wait for text
chrome-devtools nav wait-for --text "Welcome"

Device Emulation

# Emulate device
chrome-devtools emulate device --name "iPhone 13"

# Custom viewport
chrome-devtools emulate resize --width 1920 --height 1080

Debugging

# Start console monitoring
chrome-devtools debug start-console-monitoring

# List console messages
chrome-devtools debug list-console --types error,warning

# Evaluate JavaScript
chrome-devtools debug evaluate --script "document.title"

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

Performance

# Start trace
chrome-devtools perf start-trace

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

# Automated analysis
chrome-devtools perf analyze --url <url> --duration 10000 --format json

Network

# Start monitoring
chrome-devtools network start-monitoring

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

# Get request details
chrome-devtools network get-request --id <request-id>

# Clear history
chrome-devtools network clear

Global Options

Available on all commands:

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

Connection:

• --browser-url <url> - Connect to existing Chrome instance
• --ws-endpoint <endpoint> - WebSocket endpoint

Browser:

• --headless - Run without GUI
• --isolated - Temporary profile
• --channel <channel> - Chrome channel (stable, beta, dev, canary)

Output:

• --format <format> - json, toon, or text (default)

Display:

• --viewport <size> - Initial viewport (e.g., 1280x720)

Complete options: See [references/COMMANDS.md](references/COMMANDS.md)

Output Formats

Text (Default)

Human-readable console output.

JSON

Standard JSON for programmatic use.

TOON (Token-Optimized)

58.9% token reduction vs JSON - ideal for LLM workflows.

chrome-devtools network list-requests --format toon

Common Workflows

Complete Automation

# Start monitoring
chrome-devtools debug start-console-monitoring
chrome-devtools network start-monitoring

# Navigate and interact
chrome-devtools nav new-page --url https://example.com
chrome-devtools input fill --uid input-email --value "[email protected]"
chrome-devtools input click --uid button-submit

# Capture results
chrome-devtools debug screenshot --path result.png
chrome-devtools network list-requests --format toon

# Cleanup
chrome-devtools close

CI/CD Integration

#!/bin/bash
# Headless browser testing

chrome-devtools --headless nav new-page --url https://staging.example.com
chrome-devtools --headless debug screenshot --path ci-screenshot.png
chrome-devtools --headless perf analyze --url https://staging.example.com --format json > perf.json
chrome-devtools close

Mobile Testing

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

chrome-devtools emulate device --name "iPad Pro"
chrome-devtools nav navigate --url https://example.com
chrome-devtools debug screenshot --path mobile-ipad.png

More workflows: See [references/WORKFLOWS.md](references/WORKFLOWS.md)

Advanced Usage

Connect to Existing Chrome

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

# Connect via CLI
chrome-devtools --browser-url http://127.0.0.1:9222 nav list-pages

Headless Mode

chrome-devtools --headless --viewport 1920x1080 nav new-page --url https://example.com

Programmatic API

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

await navigatePage({ url: 'https://example.com' })
await takeScreenshot({ path: 'screenshot.png', fullPage: true })
await closeBrowser()

Advanced features: See [references/ADVANCED-USAGE.md](references/ADVANCED-USAGE.md)

Key Features

• Input Automation - Click, hover, fill forms, keyboard, drag-drop
• Navigation - Multi-page management, URL navigation, wait conditions
• Emulation - Device emulation, viewport resizing
• Performance - Trace recording, performance analysis
• Network - Request monitoring and inspection
• Debugging - Console monitoring, JavaScript evaluation, screenshots
• Multiple Formats - JSON, TOON (58.9% token reduction), text
• Flexible Connection - Launch new or connect to existing Chrome

Requirements

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

Architecture

Built on Puppeteer with CLI framework and output formatting utilities.

Tips and Best Practices

1. Use TOON format for LLM workflows (58.9% token reduction)
2. Start monitoring before navigation to capture all requests
3. Use headless mode for CI/CD pipelines
4. Use isolated mode for reproducible tests
5. Connect to existing Chrome for debugging live instances

Reference Documentation

• [Installation Guide](references/INSTALLATION.md) - All installation methods
• [Commands Reference](references/COMMANDS.md) - Complete command documentation
• [Advanced Usage](references/ADVANCED-USAGE.md) - Advanced features and patterns
• [Common Workflows](references/WORKFLOWS.md) - Practical workflow examples

Resources

• GitHub Repository
• npm Package
• Chrome DevTools MCP
• Puppeteer Docs

Version: 1.0.0 Author: Minsu Lee (@amondnet) License: MIT