chrome-devtools-cli

chrome-devtools-cli is a collaboration-first terminal interface for controlling an existing Chrome session or a managed Chromium session.

It adds a CLI product layer on top of the internal DevTools/MCP runtime in this repository:

• attach to an already running browser with login state
• reuse the same session across multiple shells
• bind a stable tab with handoff / use-tab
• run Playwright scripts against the shared browser/tab
• keep access to the underlying DevTools tool surface when needed

Install

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

Available commands:

• chrome-devtools-cli
• chrome-devtools

Quick Start

Start a managed browser:

chrome-devtools-cli start
chrome-devtools-cli status
chrome-devtools-cli tabs

Attach to an existing Chrome started with remote debugging:

chrome-devtools-cli attach --browserUrl http://127.0.0.1:9222
chrome-devtools-cli tabs
chrome-devtools-cli handoff --current-tab

Bind a specific tab and run Playwright:

chrome-devtools-cli use-tab --title "Dashboard"
chrome-devtools-cli playwright --script 'async ({page}) => ({title: await page.title(), url: page.url()})'

Stop the shared session:

chrome-devtools-cli stop

Main Commands

• start: launch a managed browser session
• attach: connect to an existing debuggable browser
• status: show daemon/session metadata
• stop: stop the current session and clear persisted state
• tabs: list available tabs in the current session
• handoff: bind the currently selected tab into session state
• use-tab: rebind by pageId, title, or url
• playwright: run an inline or file-based Playwright script in the shared browser session

The CLI also exposes the migrated DevTools tool commands such as list_pages, navigate_page, take_screenshot, evaluate_script, performance_*, and more.

What Is CLI-Specific In This Repo

These files are the main chrome-devtools-cli-specific product layer:

• src/bin/chrome-devtools.ts
• src/daemon/state.ts
• src/session/reuse.ts
• src/browser-endpoint.ts
• src/playwright/runner.ts
• src/playwright/script-loader.ts
• tests/e2e/chrome-devtools-session-reuse.test.ts
• tests/e2e/chrome-devtools-collaboration-state.test.ts
• tests/e2e/chrome-devtools-recovery.test.ts

What Still Uses mcp Internally

Some files still keep mcp naming because the current CLI daemon still launches the internal DevTools/MCP server layer rather than reimplementing it:

• src/bin/chrome-devtools-mcp.ts
• src/bin/chrome-devtools-mcp-main.ts
• src/bin/chrome-devtools-mcp-cli-options.ts
• src/index.ts
• most files under src/tools
• most files under src/formatters

Those are not just leftover docs or aliases; they are still runtime support and should not be deleted yet.

Docs

CLI-specific usage is in docs/cli.md.