chrome-cli

A CLI tool for browser automation via the Chrome DevTools Protocol.

A fast, standalone command-line tool for automating Chrome and Chromium browsers. No Node.js, no Python — just a single native binary that speaks the Chrome DevTools Protocol (CDP) directly over WebSocket.

Features

• Tab management — list, create, close, and activate browser tabs
• URL navigation — navigate to URLs, go back/forward, reload, and manage history
• Page inspection — capture accessibility trees, extract text, find elements
• Screenshots — full-page and viewport screenshots to file or stdout
• JavaScript execution — run scripts in the page context, return results as JSON
• Form filling — fill inputs, select options, and submit forms by accessibility UID
• Network monitoring — follow requests in real time, intercept and block URLs
• Console capture — read and follow console messages with type filtering
• Performance tracing — start/stop Chrome trace recordings, collect metrics
• Device emulation — emulate mobile devices, throttle network/CPU, set geolocation
• Dialog handling — accept, dismiss, or respond to alert/confirm/prompt dialogs
• Shell integration — completion scripts for Bash, Zsh, Fish, PowerShell, and Elvish
• Man pages — built-in man page viewer via chrome-cli man

How does chrome-cli compare?

Installation

Pre-built binaries

Download the latest release for your platform from GitHub Releases.

# macOS (Apple Silicon)
curl -fsSL https://github.com/Nunley-Media-Group/chrome-cli/releases/latest/download/chrome-cli-aarch64-apple-darwin.tar.gz \
  | tar xz && mv chrome-cli-*/chrome-cli /usr/local/bin/

# macOS (Intel)
curl -fsSL https://github.com/Nunley-Media-Group/chrome-cli/releases/latest/download/chrome-cli-x86_64-apple-darwin.tar.gz \
  | tar xz && mv chrome-cli-*/chrome-cli /usr/local/bin/

# Linux (x86_64)
curl -fsSL https://github.com/Nunley-Media-Group/chrome-cli/releases/latest/download/chrome-cli-x86_64-unknown-linux-gnu.tar.gz \
  | tar xz && mv chrome-cli-*/chrome-cli /usr/local/bin/

# Linux (ARM64)
curl -fsSL https://github.com/Nunley-Media-Group/chrome-cli/releases/latest/download/chrome-cli-aarch64-unknown-linux-gnu.tar.gz \
  | tar xz && mv chrome-cli-*/chrome-cli /usr/local/bin/

Cargo install

cargo install chrome-cli

Build from source

git clone https://github.com/Nunley-Media-Group/chrome-cli.git
cd chrome-cli
cargo build --release
# Binary is at target/release/chrome-cli

Supported platforms

Quick Start

1. Install chrome-cli (see Installation above)

2. Start Chrome with remote debugging enabled:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Or launch headless Chrome directly via chrome-cli:
chrome-cli connect --launch --headless

3. Connect to Chrome:

chrome-cli connect

4. Navigate to a URL:

chrome-cli navigate https://example.com

5. Inspect the page:

chrome-cli page snapshot

Usage Examples

# Viewport screenshot
chrome-cli page screenshot --file screenshot.png

# Full-page screenshot
chrome-cli page screenshot --full-page --file full-page.png

# Get the visible text content of the page
chrome-cli page text

# Run a JavaScript expression and get the result
chrome-cli js exec "document.title"

# Run JavaScript from a file
chrome-cli js exec --file script.js

# First, capture the accessibility tree to find UIDs
chrome-cli page snapshot

# Fill a single field by accessibility UID
chrome-cli form fill s5 "hello@example.com"

# Fill multiple fields at once
chrome-cli form fill-many s5="hello@example.com" s8="MyPassword123"

# Submit a form
chrome-cli form submit s10

# Follow network requests in real time
chrome-cli network follow --timeout 5000

# Block specific URLs
chrome-cli network block "*.ads.example.com"

# Record a trace for 5 seconds
chrome-cli perf record --duration 5000

# Record until Ctrl+C, with page reload
chrome-cli perf record --reload

# Save to a specific file
chrome-cli perf record --duration 5000 --file trace.json

# Get Core Web Vitals
chrome-cli perf vitals

Command Reference

Run chrome-cli <command> --help for detailed usage of any command, or chrome-cli man <command> to view its man page.

Architecture

┌──────────────────────────────────────────────────────┐
│                    chrome-cli                         │
│                                                      │
│  ┌────────────┐   ┌─────────────┐   ┌────────────┐  │
│  │  CLI Layer  │──▶│  Command    │──▶│ CDP Client │  │
│  │  (clap)     │   │  Dispatch   │   │ (WebSocket)│  │
│  └────────────┘   └─────────────┘   └─────┬──────┘  │
│                                            │         │
└────────────────────────────────────────────┼─────────┘
                                             │ JSON-RPC
                                             ▼
                                    ┌─────────────────┐
                                    │  Chrome Browser  │
                                    │  (DevTools       │
                                    │   Protocol)      │
                                    └─────────────────┘

How it works: chrome-cli communicates with Chrome using the Chrome DevTools Protocol (CDP) over a WebSocket connection. Commands are sent as JSON-RPC messages; responses and events flow back on the same connection.

Session management: When you run chrome-cli connect, a session file is created with the WebSocket URL. Subsequent commands reuse this connection automatically. The session persists until you run chrome-cli connect disconnect or Chrome exits.

Performance: chrome-cli is a native Rust binary with sub-50ms startup time. There is no interpreter, no runtime, and no JIT warmup — it goes straight from your shell to Chrome.

Claude Code Integration

chrome-cli is designed for AI agent consumption. See the full Claude Code Integration Guide for discovery mechanisms, common workflows, best practices, and error handling patterns.

Drop the CLAUDE.md template into your project to give Claude Code browser automation capabilities out of the box.

Related Projects

• Chrome DevTools MCP — The official Chrome DevTools MCP server by Google, providing browser automation for AI coding agents via the Model Context Protocol. If you're looking for MCP-based browser control rather than a CLI tool, check it out.

Contributing

All contributions must follow the NMG-SDLC workflow without deviation. NMG-SDLC is a BDD spec-driven development toolkit that enforces a structured delivery lifecycle: issue creation, specification writing, implementation, verification, and PR creation. Contributions that bypass the SDLC process will not be accepted.

Prerequisites

• Rust 1.85.0 or later (pinned via rust-toolchain.toml)
• Chrome or Chromium (for integration testing)
• Claude Code with the NMG-SDLC plugin installed

Build and test

git clone https://github.com/Nunley-Media-Group/chrome-cli.git
cd chrome-cli

# Build
cargo build

# Run tests
cargo test

# Lint
cargo clippy -- -D warnings
cargo fmt --check

# Generate man pages
cargo xtask man

Code style

This project uses strict Clippy configuration (all = "deny", pedantic = "warn") and rustfmt with the 2024 edition. All warnings must be resolved before merging.

License

Licensed under either of MIT License or Apache License, Version 2.0 at your option.