chrome-cmd

<div align="center"> <a href="https://www.google.com/chrome/" target="_blank" rel="noopener noreferrer"> <img width="64" src="https://raw.githubusercontent.com/alrra/browser-logos/main/src/chrome/chrome.svg" alt="Chrome logo"> </a> <h2>Chrome CMD</h2> <a href="#rocket-quick-start">Quick Start</a> • <a href="#bulb-usage">Usage</a> • <a href="#package-additional-information">Additional Information</a> • <a href="#star-inspiration">Inspiration</a> </div> ## Overview Control Chrome from the command line: list tabs, execute JavaScript, monitor network, capture screenshots, automate forms. <div align="center"> <img width="80%" src="https://raw.githubusercontent.com/lucasvtiradentes/chrome-cmd/main/.github/images/demo.webp"> </div> ## :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 ```bash # 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. <details> <summary>Tab Management</summary>  ```bash # List all open Chrome tabs chrome-cmd tab list # 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 # Navigate tab to a specific URL chrome-cmd tab navigate https://github.com 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.images.length" 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" # Fill an input field in selected tab chrome-cmd tab input --selector "#username" --value "myuser" chrome-cmd tab input --selector "#search" --value "query" --submit ```  </details> <details> <summary>JavaScript Execution</summary>  ```bash # Execute JavaScript on selected tab chrome-cmd tab exec "document.title" # Output: "GitHub - Chrome CMD" # More examples chrome-cmd tab exec "document.images.length" chrome-cmd tab exec "Array.from(document.querySelectorAll('a')).map(a => a.href)" chrome-cmd tab exec "2 + 2" ```  </details> <details> <summary>Console Logs</summary>  ```bash 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  </details> <details> <summary>Network Requests</summary>  ```bash 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  </details> <details> <summary>HTML Extraction</summary>  ```bash 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  </details> <details> <summary>Screenshots</summary>  ```bash chrome-cmd tab screenshot chrome-cmd tab screenshot --output ~/Downloads/page.png chrome-cmd tab screenshot --tab 2 chrome-cmd tab screenshot --only-viewport ```  </details> <details> <summary>Storage Inspection</summary>  ```bash 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  </details> <details> <summary>Form Automation</summary>  ```bash chrome-cmd tab click --selector "button.submit" chrome-cmd tab click --text "Sign In" ``` ```bash chrome-cmd tab input --selector "#username" --value "myuser" chrome-cmd tab input --selector "#search" --value "query" --submit ```  </details> <details> <summary>System Commands</summary>  ```bash # 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 remove # Remove profile and bridge configuration chrome-cmd profile select # Select active profile from configured profiles ```  </details> <details> <summary>Command History</summary> Click the Chrome CMD extension icon in your browser toolbar to view recent commands, execution times, and results. </details> ## :package: Additional Information **Prerequisites:** Node.js 18+, Google Chrome, Linux/macOS/Windows <details> <summary>Multi-Profile Support</summary> You can use chrome-cmd with multiple Chrome profiles. Just repeat the Quick Start setup for each profile: 1. Open your other Chrome profile 2. Run `chrome-cmd install` again 3. Load the extension and paste the Extension ID To switch between profiles: ```bash chrome-cmd profile select # → Shows list of registered profiles # → Type the profile number # → All commands now run on selected profile ``` </details> <details> <summary>Uninstallation</summary> To completely remove chrome-cmd, run these commands in order: ```bash # 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 ``` </details> <details> <summary>Development setup</summary> For local development: ```bash # 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 ``` Load extension from `packages/chrome-extension/` directory. </details> <details> <summary>How it works</summary> 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) </details> ## :star: Inspiration - [BroTab](https://github.com/balta2ar/brotab) - Original Python implementation --- <div align="center"> <a target="_blank" href="https://www.linkedin.com/in/lucasvtiradentes/"><img src="https://img.shields.io/badge/-linkedin-blue?logo=Linkedin&logoColor=white" alt="LinkedIn"></a> <a target="_blank" href="mailto:lucasvtiradentes@gmail.com"><img src="https://img.shields.io/badge/gmail-red?logo=gmail&logoColor=white" alt="Gmail"></a> Made with ❤️ by Lucas Vieira </div>