--- name: chrome-devtools-cli-usage description: Complete guide for Chrome DevTools CLI - browser automation, debugging, performance analysis, network inspection. Use when automating Chrome, taking screenshots, analyzing performance, monitoring network/console, device emulation, or user mentions chrome-devtools, browser automation, puppeteer, debugging, performance testing, screenshot, network monitoring, console monitoring, or 크롬 개발자도구, 브라우저 자동화, 디버깅, 성능 분석. allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion version: 1.0.0 lastUpdated: 2025-11-08 --- # 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 ```bash # 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 ```bash # 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 ```bash # Standard screenshot chrome-devtools debug screenshot --path screenshot.png # Full page screenshot chrome-devtools debug screenshot --path screenshot.png --full-page ``` ### Performance Analysis ```bash # Quick performance analysis chrome-devtools perf analyze --url https://example.com --format json ``` ### Network Monitoring ```bash # 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 ```bash # Click element chrome-devtools input click --uid # Fill input chrome-devtools input fill --uid input-email --value "user@example.com" # Press keys chrome-devtools input press-key --key Enter # Handle dialogs chrome-devtools input handle-dialog --action accept ``` ### Page Navigation ```bash # Create new page chrome-devtools nav new-page --url # Wait for element chrome-devtools nav wait-for --selector "#element" # Wait for text chrome-devtools nav wait-for --text "Welcome" ``` ### Device Emulation ```bash # Emulate device chrome-devtools emulate device --name "iPhone 13" # Custom viewport chrome-devtools emulate resize --width 1920 --height 1080 ``` ### Debugging ```bash # 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 ```bash # Start trace chrome-devtools perf start-trace # Stop trace chrome-devtools perf stop-trace --output trace.json # Automated analysis chrome-devtools perf analyze --url --duration 10000 --format json ``` ### Network ```bash # 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 # Clear history chrome-devtools network clear ``` ## Global Options Available on all commands: ```bash chrome-devtools [options] [command-options] ``` **Connection:** - `--browser-url ` - Connect to existing Chrome instance - `--ws-endpoint ` - WebSocket endpoint **Browser:** - `--headless` - Run without GUI - `--isolated` - Temporary profile - `--channel ` - Chrome channel (stable, beta, dev, canary) **Output:** - `--format ` - json, toon, or text (default) **Display:** - `--viewport ` - 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. ```bash chrome-devtools network list-requests --format toon ``` ## Common Workflows ### Complete Automation ```bash # 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 "user@example.com" 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 ```bash #!/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 ```bash # 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 ```bash # 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 ```bash chrome-devtools --headless --viewport 1920x1080 nav new-page --url https://example.com ``` ### Programmatic API ```typescript 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](https://pptr.dev/) 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](https://github.com/pleaseai/chrome-devtools-cli) - [npm Package](https://www.npmjs.com/package/@pleaseai/chrome-devtools-cli) - [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) - [Puppeteer Docs](https://pptr.dev/) --- **Version**: 1.0.0 **Author**: Minsu Lee ([@amondnet](https://github.com/amondnet)) **License**: MIT