Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lucasvtiradentes/chrome-cmd

🌐 interact your Chrome browser from the command line
https://github.com/lucasvtiradentes/chrome-cmd

automation browser chrome claude-code cli terminal

Last synced: 4 months ago
JSON representation

🌐 interact your Chrome browser from the command line

Awesome Lists containing this project

README 

          




  Chrome logo



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



```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 ` flag.



Tab Management



```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



```



JavaScript Execution



```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"

```



Console Logs



```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



Network Requests



```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



HTML Extraction



```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



Screenshots



```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

```



Storage Inspection



```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



Form Automation



```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

```



System Commands



```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



```



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:



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

```



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:



```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

```



Development setup



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

```



```bash

# 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](https://github.com/balta2ar/brotab) - Original Python implementation



---





  


    LinkedIn

    Gmail

  


  
Made with ❤️ by Lucas Vieira