Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/pleaseai/chrome-devtools-cli


https://github.com/pleaseai/chrome-devtools-cli

Last synced: 5 months ago
JSON representation

Awesome Lists containing this project

README 

          
# Chrome DevTools CLI



[![npm version](https://badge.fury.io/js/@pleaseai%2Fchrome-devtools-cli.svg)](https://badge.fury.io/js/@pleaseai%2Fchrome-devtools-cli)

[![CI](https://github.com/pleaseai/chrome-devtools-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/pleaseai/chrome-devtools-cli/actions/workflows/ci.yml)

[![codecov](https://codecov.io/github/pleaseai/chrome-devtools-cli/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/github/pleaseai/chrome-devtools-cli)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![code style](https://antfu.me/badge-code-style.svg)](https://github.com/antfu/eslint-config)



**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](https://github.com/ChromeDevTools/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)



```bash

# Add tap

brew tap pleaseai/tap



# Install

brew install chrome-devtools-cli



# Or one-liner

brew install pleaseai/tap/chrome-devtools-cli

```



Update:



```bash

brew upgrade chrome-devtools-cli

```



### Binary Download



Download pre-built binaries from [GitHub Releases](https://github.com/pleaseai/chrome-devtools-cli/releases):



#### Quick Install (Recommended)



Auto-detects your platform and architecture:



```bash

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

```



Or download and run the script manually:



```bash

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

chmod +x install.sh

./install.sh

```



#### Manual Installation



```bash

# 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



```bash

# Global installation

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

# or

bun add -g @pleaseai/chrome-devtools-cli

```



### Local Installation (as library)



```bash

npm install @pleaseai/chrome-devtools-cli

# or

bun add @pleaseai/chrome-devtools-cli

```



### Claude Code Plugin



Install as a plugin for [Claude Code](https://claude.com) to get integrated skill documentation and automation support.



#### Add Marketplace



```bash

/plugin marketplace add pleaseai/claude-code-plugins

```



#### Install Plugin



```bash

/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



```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

```



### Take a Screenshot



```bash

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

```



### Analyze Performance



```bash

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

```



### Monitor Network Requests



```bash

# Start monitoring

chrome-devtools network start-monitoring



# List requests

chrome-devtools network list-requests --format toon

```



## Usage



### Global Options



```bash

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

```



**Global Options:**



- `--browser-url ` - Connect to running Chrome via port forwarding

- `--ws-endpoint ` - WebSocket endpoint for Chrome

- `--ws-headers ` - Custom WebSocket headers (JSON)

- `--headless` - Run in headless mode

- `--executable-path ` - Path to Chrome executable

- `--isolated` - Use temporary user data directory

- `--channel ` - Chrome channel (stable|canary|beta|dev)

- `--viewport ` - Initial viewport size (e.g., 1280x720)

- `--proxy-server ` - Proxy server configuration

- `--accept-insecure-certs` - Ignore certificate errors

- `--format ` - Output format (json|toon|text)



## Commands



### Input Automation



#### Click on Element



```bash

chrome-devtools input click --uid 

chrome-devtools input click --uid  --dbl-click

```



#### Hover over Element



```bash

chrome-devtools input hover --uid 

```



#### Fill Input Field



```bash

chrome-devtools input fill --uid  --value "text"

```



#### Press Keyboard Key



```bash

chrome-devtools input press-key --key Enter

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

```



#### Drag and Drop



```bash

chrome-devtools input drag --from  --to 

```



#### Upload File



```bash

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

```



#### Handle Dialog



```bash

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



```bash

chrome-devtools nav list-pages

chrome-devtools nav list-pages --format json

```



#### Select Page



```bash

chrome-devtools nav select-page --index 0

```



#### Close Page



```bash

chrome-devtools nav close-page --index 1

```



#### Create New Page



```bash

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

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

```



#### Navigate Page



```bash

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

```



#### Wait for Element or Text



```bash

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



```bash

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

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

```



#### Resize Viewport



```bash

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

```



### Performance



#### Start Performance Trace



```bash

chrome-devtools perf start-trace

```



#### Stop Performance Trace



```bash

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

```



#### Analyze Performance



```bash

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

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

```



### Network



#### Start Monitoring



```bash

chrome-devtools network start-monitoring

```



#### List Network Requests



```bash

chrome-devtools network list-requests

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

```



#### Get Request Details



```bash

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

```



#### Clear Request History



```bash

chrome-devtools network clear

```



### Debugging



#### Start Console Monitoring



```bash

chrome-devtools debug start-console-monitoring

```



#### List Console Messages



```bash

chrome-devtools debug list-console

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

```



#### Get Console Message



```bash

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

```



#### Clear Console History



```bash

chrome-devtools debug clear-console

```



#### Evaluate JavaScript



```bash

chrome-devtools debug evaluate --script "document.title"

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

```



#### Take Screenshot



```bash

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



```bash

chrome-devtools debug snapshot

chrome-devtools debug snapshot --verbose

```



### Browser Management



#### Close Browser



```bash

chrome-devtools close

```



## Output Formats



### Text (Default)



Human-readable output format for console display.



```bash

chrome-devtools nav list-pages

```



### JSON



Standard JSON format for programmatic consumption.



```bash

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.



```bash

chrome-devtools nav list-pages --format toon

```



## Advanced Usage



### Connecting to Existing Chrome Instance



#### Step 1: Start Chrome with Remote Debugging



**macOS:**



```bash

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \

  --remote-debugging-port=9222 \

  --user-data-dir=/tmp/chrome-profile

```



**Linux:**



```bash

/usr/bin/google-chrome \

  --remote-debugging-port=9222 \

  --user-data-dir=/tmp/chrome-profile

```



**Windows:**



```bash

"C:\Program Files\Google\Chrome\Application\chrome.exe" ^

  --remote-debugging-port=9222 ^

  --user-data-dir="%TEMP%\chrome-profile"

```



#### Step 2: Connect via CLI



```bash

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

```



### Using WebSocket Endpoint



```bash

# Get WebSocket URL from http://127.0.0.1:9222/json/version

chrome-devtools --ws-endpoint ws://127.0.0.1:9222/devtools/browser/ nav list-pages

```



### Headless Mode



```bash

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

chrome-devtools --headless debug screenshot --path screenshot.png

```



### Custom Chrome Channel



```bash

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)



```bash

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

```



## Examples



### Complete Automation Workflow



```bash

# 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



```bash

# 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



```bash

# 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](https://pptr.dev/)** - Browser automation

- **[Commander.js](https://github.com/tj/commander.js)** - CLI framework

- **[@pleaseai/cli-toolkit](https://github.com/passionfactory/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:



```typescript

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](https://nodejs.org/) v20.19 or newer (LTS version)

- [Chrome](https://www.google.com/chrome/) current stable version or newer

- [npm](https://www.npmjs.com/) or [Bun](https://bun.sh/)



## 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](https://github.com/ChromeDevTools/chrome-devtools-mcp) by Google LLC.



## Related Projects



- [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) - MCP server for Chrome DevTools

- [@pleaseai/cli-toolkit](https://github.com/passionfactory/cli-toolkit) - CLI utilities for LLM-focused tools

- [Puppeteer](https://pptr.dev/) - Headless Chrome Node.js API



## Support



- [GitHub Issues](https://github.com/passionfactory/chrome-devtools-cli/issues)

- [Documentation](https://github.com/passionfactory/chrome-devtools-cli#readme)



---



**Author**: Minsu Lee ([@amondnet](https://github.com/amondnet))