Chrome DevTools命令行界面
Chrome DevTools Protocol（CDP）的命令行界面，针对具有NDJSON输出格式的LLM代理进行了优化。
概述
cdp-cli 提供对所有Chrome DevTools Protocol功能的CLI访问，使其易于自动化浏览器交互、调试web应用程序和检查网络流量——所有这些都可以通过命令行使用grep/tail友好的输出。
新功能
--inspect 用于控制台输出
完全展开控制台消息中的嵌套对象和数组，而不是看到 Object 或 Array(12):
# Without --inspect
cdp-cli console "MyPage"
"Config: {options: Object, values: Array(5)}"
# With --inspect - see actual values
cdp-cli console "MyPage" --inspect
"Config: {options: {debug: true, level: 3}, values: [1, 2, 3, 4, 5]}"--user-gesture 对于单击命令
启用WebXR、全屏和其他需要用户交互的激活门控浏览器API：
# Standard click (uses Input.dispatchMouseEvent)
cdp-cli click "MyPage" "button#submit"
# User gesture click (uses Runtime.evaluate with userGesture: true)
# Required for WebXR session requests, fullscreen API, etc.
cdp-cli click "MyPage" "button#enter-vr" --user-gesture安装
npm install -g @myerscarpenter/cdp-cli快速开始
# Launch Chrome with remote debugging
cdp-cli launch
# List all open pages
cdp-cli tabs
# Navigate to a URL
cdp-cli new "https://example.com"
# Get page snapshot (accessibility tree)
cdp-cli snapshot "example"
# Click an element
cdp-cli click "example" "a"
# Take a screenshot
cdp-cli screenshot "example" screenshot.jpg或者手动启动Chrome：
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222
# Linux
google-chrome --remote-debugging-port=9222
# Windows
chrome.exe --remote-debugging-port=9222输出格式：NDJSON
所有列表命令输出 换行符分隔的JSON（NDJSON） -每行一个完整的JSON对象。此格式为：
- LLM友好：易于编程解析
- Grep兼容：使用标准Unix工具进行筛选
- 可流式传输的：增量处理大型数据集
NDJSON输出示例
$ cdp-cli tabs
{"id":"A1B2C3","title":"GitHub","url":"https://github.com","type":"page"}
{"id":"D4E5F6","title":"Google","url":"https://google.com","type":"page"}
$ cdp-cli console "example"
{"type":"log","timestamp":1698234567890,"text":"Page loaded","source":"console-api"}
{"type":"error","timestamp":1698234568123,"text":"TypeError: Cannot read...","source":"exception","line":42,"url":"https://example.com/app.js"}
$ cdp-cli network "example" | grep '"type":"fetch"'
{"url":"https://api.example.com/data","method":"GET","status":200,"type":"fetch","size":4567}命令
页面管理
标签页 -列出所有打开的浏览器页面
cdp-cli tabs新 -创建新页面/选项卡
cdp-cli new "https://example.com"
cdp-cli new # Empty page去 -导航页面（URL、后退、前进、重新加载）
cdp-cli go "example" "https://github.com"
cdp-cli go "example" back
cdp-cli go "example" forward
cdp-cli go "example" reload关闭 -关闭页面
cdp-cli close "example"
cdp-cli close A1B2C3调试
控制台 -列出控制台消息（默认情况下输出最小，针对LLM令牌节省进行了优化）
# Minimal output (bare strings, last 10 messages)
cdp-cli console "example"
"Page loaded"
"API call successful"
# Show more messages
cdp-cli console "example" --tail 50
# Show all messages (no limit)
cdp-cli console "example" --all
# or
cdp-cli console "example" --tail -1
# Note: When truncated, stderr shows: "(N messages skipped. Use --tail M or --all to see more)"
# This warning is visible to both humans and LLM agents
# Include message type (switches to object format)
cdp-cli console "example" --with-type
{"text":"Page loaded","type":"log","source":"console-api"}
{"text":"Error: failed","type":"error","source":"exception","line":42,"url":"app.js"}
# Include timestamp
cdp-cli console "example" --with-timestamp
{"text":"Page loaded","timestamp":1698234567890}
# Include source location (url, line number for exceptions)
cdp-cli console "example" --with-source
{"text":"Error: undefined","url":"https://example.com/app.js","line":42}
# Verbose mode - all fields (shortcut for all three flags)
cdp-cli console "example" --verbose
# or
cdp-cli console "example" -v
{"text":"Error: undefined","type":"error","source":"exception","timestamp":1698234567890,"url":"app.js","line":42}
# Expand nested objects/arrays (instead of "Object" or "Array(N)")
cdp-cli console "example" --inspect
# or
cdp-cli console "example" -i
# Filter by type (still outputs bare strings by default)
cdp-cli console "example" --type error
# Collect for longer duration (2 seconds)
cdp-cli console "example" --duration 2快照 -获取页面内容快照
# Accessibility tree (default) - great for LLM element identification!
cdp-cli snapshot "example"
# Text content only
cdp-cli snapshot "example" --format text
# DOM tree (JSON)
cdp-cli snapshot "example" --format dom评估 -评估JavaScript表达式
cdp-cli eval "example" "document.title"
cdp-cli eval "example" "window.location.href"
cdp-cli eval "example" "Array.from(document.querySelectorAll('h1')).map(h => h.textContent)"截图 -截图
# Save to file
cdp-cli screenshot "example" --output screenshot.jpg
# Different formats
cdp-cli screenshot "example" --output screenshot.png --format png
# Output base64 (NDJSON)
cdp-cli screenshot "example"网络检查
网络 -列出网络请求（默认收集0.1秒）
# Collect requests (default 0.1 seconds)
cdp-cli network "example"
# Collect for longer duration (5 seconds)
cdp-cli network "example" --duration 5
# Filter by type
cdp-cli network "example" --type fetch
cdp-cli network "example" --type xhr
# Combine duration and filtering
cdp-cli network "example" --duration 5 --type fetch输入自动化
点击 -通过CSS选择器单击元素
cdp-cli click "example" "button#submit"
cdp-cli click "example" "a.link" --double
# Use --user-gesture for WebXR, fullscreen, and other activation-gated APIs
cdp-cli click "example" "button#enter-vr" --user-gesture
cdp-cli click "example" "button#fullscreen" -g # short flag填充 -填写输入元素
cdp-cli fill "example" "user@example.com" "input#email"
cdp-cli fill "example" "secret123" "input[name='password']"钥匙 -按键盘键
cdp-cli key "example" enter
cdp-cli key "example" tab
cdp-cli key "example" escapeLLM使用模式
模式1：检查和交互
# 1. List pages to find target
cdp-cli tabs | grep "example"
# 2. Get accessibility tree to understand page structure
cdp-cli snapshot "example" --format ax > page-structure.json
# 3. Parse structure (LLM can identify element selectors)
# 4. Interact with elements
cdp-cli fill "example" "query" "input#search"
cdp-cli click "example" "button[type='submit']"
# 5. Capture result
cdp-cli screenshot "example" --output result.jpg模式2：调试Web应用程序
# 1. Navigate to app
cdp-cli new "http://localhost:3000"
# 2. Monitor console for errors (increase duration for continuous monitoring)
cdp-cli console "localhost" --duration 10 --type error
# 3. Inspect failed network requests
cdp-cli network "localhost" --duration 5 | grep '"status":4'模式3：自动化测试
# 1. Open test page
cdp-cli new "http://localhost:8080/test.html"
# 2. Fill form
cdp-cli fill "test" "testuser" "input#username"
cdp-cli fill "test" "testpass" "input#password"
cdp-cli click "test" "button#login"
# 3. Wait and verify
sleep 2
cdp-cli eval "test" "document.querySelector('.success-message')?.textContent"
# 4. Capture evidence
cdp-cli screenshot "test" --output test-result.jpg模式4：数据提取
# 1. Navigate to page
cdp-cli go "example" "https://example.com/data"
# 2. Extract data via JavaScript
cdp-cli eval "example" "Array.from(document.querySelectorAll('.item')).map(el => ({
title: el.querySelector('.title').textContent,
price: el.querySelector('.price').textContent
}))"全局选项
--cdp-url-Chrome DevTools协议URL（默认值：http://localhost:9222)--help-显示帮助--version-显示版本
LLM代理提示
- 使用NDJSON解析：每一行都是一个完整的JSON对象
const lines = output.split('\n').filter(l => l.trim());
const objects = lines.map(l => JSON.parse(l));- 利用grep进行过滤:
cdp-cli network "example" | grep '"status":404'
cdp-cli console "example" | grep error- 使用可访问性树进行元素发现:
cdp-cli snapshot "example" --format ax
# Parse to find elements by role, name, etc.
# Then construct CSS selectors for click/fill- 使用Unix工具链命令:
cdp-cli tabs | jq -r '.title'
cdp-cli console "example" | grep error | tail -5- 错误处理：所有错误均输出NDJSON
"error": true
{"error":true,"message":"Page not found: example","code":"PAGE_NOT_FOUND"}建筑
内置：
- TypeScript -类型安全代码
- 纱线 -CLI参数解析
- ws -用于CDP通信的WebSocket
- NDJSON -LLM友好的输出格式
重复使用经过实战考验的CDP逻辑 chrome开发工具mcp.
测试
该项目包括一个使用Vitest的全面测试套件。
运行测试
# Run all tests
npm test
# Run tests in watch mode (auto-rerun on file changes)
npm run test:watch
# Run tests with coverage report
npm run test:coverage
# Run tests with interactive UI
npm run test:ui测试结构
tests/
├── fixtures/ # Sample CDP responses and test data
│ └── cdp-responses.ts
├── mocks/ # Mock implementations
│ ├── websocket.mock.ts # WebSocket mock for CDP
│ └── fetch.mock.ts # Fetch mock for REST API
├── helpers.ts # Test utilities
├── setup.ts # Test environment setup
└── unit/ # Unit tests
├── output.test.ts # Output formatting tests
├── context.test.ts # CDPContext tests
└── commands/ # Command tests
├── pages.test.ts
├── debug.test.ts
├── network.test.ts
└── input.test.ts测试覆盖率
当前覆盖范围：
- 输出格式化：100%（10次测试）
- CDP上下文：~95%（23次测试）
- 页面命令：约90%（11次测试）
- 总体：80%以上的行、函数和语句
编写新测试
测试使用模拟的WebSocket和fetch，因此 不需要运行Chrome实例:
import { describe, it, expect, beforeEach } from 'vitest';
import { CDPContext } from '../src/context.js';
import { installMockFetch } from './mocks/fetch.mock.js';
describe('My Test', () => {
beforeEach(() => {
installMockFetch(); // Mock CDP REST API
});
it('should test something', async () => {
const context = new CDPContext();
const pages = await context.getPages();
expect(pages).toHaveLength(3);
});
});持续集成
测试在每次提交和拉取请求时自动运行（如果配置了CI）。
许可证
麻省理工学院
相关项目
- chrome开发工具mcp -Chrome DevTools的MCP服务器
- quest-devtools.mjs -简单的CDP CLI原型
______________________________________________________________________
专为LLM代理商打造 -每个命令都输出结构化、可解析、grep友好的数据。