chrome-cmd

Chrome CMD

Quick Start • Usage • Additional Information • Inspiration

Overview

Control Chrome from the command line: list tabs, execute JavaScript, monitor network, capture screenshots, automate forms.

:sparkles: Features

   ✔️ Tab control - list, create, close, focus, and navigate tabs from terminal
   ✔️ JavaScript execution - run code in any tab and get instant results
   ✔️ Network inspection - capture HTTP requests with headers, payloads, and response bodies
   ✔️ Console monitoring - view color-coded logs with smart formatting and type filtering
   ✔️ Screenshots - capture full-page or viewport screenshots with single command
   ✔️ Form automation - click elements and fill input fields programmatically
   ✔️ Storage inspection - view cookies, localStorage, and sessionStorage data
   ✔️ Multi-profile support - manage multiple Chrome profiles with seamless switching

:rocket: Quick Start

# 1. Install
npm install -g chrome-cmd

# 2. Run install command
chrome-cmd install
# → Shows extension path
# → Guides you through the installation process
# → Waits for Extension ID

# 3. Load extension in Chrome
# → Open chrome://extensions/
# → Enable "Developer mode"
# → Click "Load unpacked" and select the path shown
# → Copy the Extension ID

# 4. Paste Extension ID in terminal
# → Paste and press Enter
# → Installation complete!

# 5. Start using!
chrome-cmd tab list

:bulb: Usage

All commands use the selected tab by default. Override with --tab <index> flag.

Tab Management

# List all open Chrome tabs
chrome-cmd tab list
chrome-cmd tab list --json

# Select tab for subsequent commands
chrome-cmd tab select
chrome-cmd tab select --tab 1

# Focus/activate a tab (bring to front)
chrome-cmd tab focus
chrome-cmd tab focus --tab 3

# Create a new tab
chrome-cmd tab create https://google.com
chrome-cmd tab create https://google.com --background
chrome-cmd tab create https://google.com --wait
chrome-cmd tab create https://google.com --json
chrome-cmd tab create

# Navigate tab to a specific URL
chrome-cmd tab navigate https://github.com
chrome-cmd tab navigate https://github.com --wait
chrome-cmd tab navigate https://github.com --tab 2

# Execute JavaScript in selected tab
chrome-cmd tab exec "document.title"
chrome-cmd tab exec "document.title" --json
chrome-cmd tab exec "Array.from(document.querySelectorAll('a')).map(a => a.href)"
chrome-cmd tab exec "2 + 2"

# Close selected tab
chrome-cmd tab close

# Reload/refresh selected tab
chrome-cmd tab refresh

# Capture screenshot of selected tab
chrome-cmd tab screenshot
chrome-cmd tab screenshot --output ~/Downloads/page.png
chrome-cmd tab screenshot --tab 2
chrome-cmd tab screenshot --only-viewport

# Extract HTML content from selected tab
chrome-cmd tab html
chrome-cmd tab html --selector "div.content"
chrome-cmd tab html --raw
chrome-cmd tab html --include-compacted-tags

# Get console logs from selected tab
chrome-cmd tab logs
chrome-cmd tab logs -n 100
chrome-cmd tab logs --error
chrome-cmd tab logs --warn
chrome-cmd tab logs --info --log --debug
chrome-cmd tab logs --error --warn

# Get network requests from selected tab
chrome-cmd tab requests
chrome-cmd tab requests -n 100
chrome-cmd tab requests --method GET
chrome-cmd tab requests --method POST
chrome-cmd tab requests --status 200
chrome-cmd tab requests --status 404
chrome-cmd tab requests --url "/api"
chrome-cmd tab requests --url "google.com"
chrome-cmd tab requests --all
chrome-cmd tab requests --failed
chrome-cmd tab requests --body
chrome-cmd tab requests --headers
chrome-cmd tab requests --method POST --status 200 --url "/api"
chrome-cmd tab requests --details 1

# Get storage data from selected tab
chrome-cmd tab storage
chrome-cmd tab storage --cookies
chrome-cmd tab storage --local
chrome-cmd tab storage --session

# Click on an element in selected tab
chrome-cmd tab click --selector "button.submit"
chrome-cmd tab click --text "Sign In"
chrome-cmd tab click --coords "100,200"

# Fill an input field in selected tab
chrome-cmd tab input --selector "#username" --value "myuser"
chrome-cmd tab input --selector "#search" --value "query" --submit

# Drag from one position to another (coordinates as "x,y")
chrome-cmd tab drag --from "100,200" --to "400,500"
chrome-cmd tab drag --from "100,200" --to "400,500" --steps 20

# Type text into the focused element
chrome-cmd tab type "hello world"
chrome-cmd tab type "[e-mail]"

# Press a key or key combination
chrome-cmd tab press Enter
chrome-cmd tab press Escape
chrome-cmd tab press a --ctrl
chrome-cmd tab press c --ctrl --shift

# Right-click on element or position (context menu)
chrome-cmd tab rightclick --selector ".file-item"
chrome-cmd tab rightclick --coords "100,200"

# Hover over an element or position
chrome-cmd tab hover --selector ".dropdown-trigger"
chrome-cmd tab hover --coords "100,200"

JavaScript Execution

# Execute JavaScript on selected tab
chrome-cmd tab exec "document.title"
# Output: "GitHub - Chrome CMD"

# More examples
chrome-cmd tab exec "document.title" --json
chrome-cmd tab exec "Array.from(document.querySelectorAll('a')).map(a => a.href)"
chrome-cmd tab exec "2 + 2"

Console Logs

chrome-cmd tab logs
chrome-cmd tab logs -n 100
chrome-cmd tab logs --error
chrome-cmd tab logs --warn
chrome-cmd tab logs --info --log --debug
chrome-cmd tab logs --error --warn

Features: Color-coded output, smart object formatting, type filtering, adjustable limit

Network Requests

chrome-cmd tab requests
chrome-cmd tab requests -n 100
chrome-cmd tab requests --method GET
chrome-cmd tab requests --method POST
chrome-cmd tab requests --status 200
chrome-cmd tab requests --status 404
chrome-cmd tab requests --url "/api"
chrome-cmd tab requests --url "google.com"
chrome-cmd tab requests --all
chrome-cmd tab requests --failed
chrome-cmd tab requests --body
chrome-cmd tab requests --headers
chrome-cmd tab requests --method POST --status 200 --url "/api"
chrome-cmd tab requests --details 1

Captured data: URL, method, status, headers, payload, response body, timing, type, errors

HTML Extraction

chrome-cmd tab html
chrome-cmd tab html --selector "div.content"
chrome-cmd tab html --raw
chrome-cmd tab html --include-compacted-tags

Features: Pretty printing, CSS selectors, token optimization, raw mode

Screenshots

chrome-cmd tab screenshot
chrome-cmd tab screenshot --output ~/Downloads/page.png
chrome-cmd tab screenshot --tab 2
chrome-cmd tab screenshot --only-viewport

Storage Inspection

chrome-cmd tab storage
chrome-cmd tab storage --cookies
chrome-cmd tab storage --local
chrome-cmd tab storage --session

Data includes: Cookie flags, expiry, size, key-value pairs

Form Automation

chrome-cmd tab click --selector "button.submit"
chrome-cmd tab click --text "Sign In"
chrome-cmd tab click --coords "100,200"

chrome-cmd tab input --selector "#username" --value "myuser"
chrome-cmd tab input --selector "#search" --value "query" --submit

System Commands

# Install Chrome CMD extension
chrome-cmd install

# Update to latest version
chrome-cmd update

# Shell completion (bash/zsh)
chrome-cmd completion install

chrome-cmd completion uninstall

# Profile management
chrome-cmd profile info             # Show configured profiles and active profile
chrome-cmd profile remove           # Remove profile and bridge configuration
chrome-cmd profile select           # Select active profile from configured profiles

Command History

Click the Chrome CMD extension icon in your browser toolbar to view recent commands, execution times, and results.

:package: Additional Information

Prerequisites: Node.js 18+, Google Chrome, Linux/macOS/Windows

Multi-Profile Support

You can use chrome-cmd with multiple Chrome profiles. Just repeat the Quick Start setup for each profile:

• Open your other Chrome profile
• Run chrome-cmd install again
• Load the extension and paste the Extension ID

To switch between profiles:

chrome-cmd profile select
# → Shows list of registered profiles
# → Type the profile number
# → All commands now run on selected profile

The extension icon indicates which profile is active: the active profile shows the CLI icon, while other connected profiles show the default icon.

Uninstallation

To completely remove chrome-cmd, run these commands in order:

# 1. Remove shell completions (if installed)
chrome-cmd completion uninstall

# 2. Manually remove the Chrome extension
# Open chrome://extensions/ and click "Remove" on the Chrome CMD extension

# 3. Uninstall the CLI package
npm uninstall -g chrome-cmd

Development setup

For local development:

# Clone repository
git clone https://github.com/lucasvtiradentes/chrome-cmd.git
cd chrome-cmd

# Build CLI
cd packages/cli
npm install
npm run build

# Use with npm run dev
npm run dev -- tabs list

# install
cat > ~/.local/bin/chrome-cmd-dev << EOF
#!/bin/bash
cd $(pwd) && npx tsx src/cli/index.ts "\$@"
EOF
chmod +x ~/.local/bin/chrome-cmd-dev

# remove
rm ~/.local/bin/chrome-cmd-dev

Load extension from packages/chrome-extension/ directory.

How it works

The architecture uses a 3-layer design to enable terminal control of Chrome:

┌──────────────────────────────────────────────────────────────────────┐
│  LAYER 1: Command Line Interface                                     │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ $ chrome-cmd tab exec "document.title"                        │  │
│  │                                                                │  │
│  │ • Commander.js for CLI parsing                                 │  │
│  │ • BridgeClient sends HTTP to bridge                           │  │
│  │ • ConfigManager selects active Chrome profile                  │  │
│  └────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────┬─────────────────────────────────────┘
                                 │
                          HTTP POST Request
                       http://localhost:8765-8774
                                 │
┌────────────────────────────────▼─────────────────────────────────────┐
│  LAYER 2: Bridge Server                                              │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ Node.js HTTP Server + Native Messaging Bridge                  │  │
│  │                                                                │  │
│  │ • One instance per Chrome profile (auto-started)               │  │
│  │ • HTTP server on dynamic port (8765-8774)                      │  │
│  │ • Converts HTTP ↔ Chrome Native Messaging (stdin/stdout)       │  │
│  │ • Registered in ~/.config/chrome-cmd/bridges.json              │  │
│  └────────────────────────────────────────────────────────────────┘  │
└────────────────────────────────┬─────────────────────────────────────┘
                                 │
                     Native Messaging Protocol
                         (stdin/stdout JSON)
                                 │
┌────────────────────────────────▼─────────────────────────────────────┐
│  LAYER 3: Chrome Extension (Service Worker)                          │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ background.ts - Main command handler                           │  │
│  │                                                                │  │
│  │ • Connects to bridge via chrome.runtime.connectNative()        │  │
│  │ • Dispatches commands to chrome.debugger API                   │  │
│  │ • Returns results through bridge to CLI                        │  │
│  │ • popup.ts shows command history                               │  │
│  └────────────────────────────┬───────────────────────────────────┘  │
└────────────────────────────────┼─────────────────────────────────────┘
                                 │
                      Chrome Debugger Protocol (CDP)
                       chrome.debugger.sendCommand()
                                 │
                    ┌────────────▼─────────────┐
                    │      Chrome Tabs         │
                    │                          │
                    │ • Execute JavaScript     │
                    │ • Network monitoring     │
                    │ • Console log capture    │
                    │ • Screenshots            │
                    │ • DOM manipulation       │
                    └──────────────────────────┘

Key Features:

• Multi-profile support: Each Chrome profile gets its own bridge instance
• Auto-recovery: Bridge auto-starts when extension connects
• Port allocation: Dynamic ports (8765-8774) prevent conflicts
• Bi-directional: Commands flow down, results flow back up

Required permissions:

• debugger - Execute JavaScript, capture screenshots, monitor network/console
• scripting - Inject content script for command details modal in popup
• tabs - List and manage tabs, navigate, focus windows
• nativeMessaging - Connect CLI to Chrome extension via bridge
• storage - Track command history in extension popup
• identity + identity.email - Auto-detect Chrome profile name (email)
• management - Get extension installation info

⚠️ Not suitable for Chrome Web Store distribution (requires debugger permission)

:star: Inspiration

• BroTab - Original Python implementation

Made with ❤️ by Lucas Vieira