Browser CLI

browser-cli — Terminal Browser Control

browser-cli is a command-line tool that controls Chrome browsers through the AIPex extension's WebSocket daemon. It translates shell commands into browser actions — managing tabs, clicking elements, filling forms, capturing screenshots, and more.

Architecture:

browser-cli ──WebSocket──▶ aipex-daemon ──WebSocket──▶ AIPex Chrome Extension ──▶ Browser APIs

The daemon auto-spawns on first use and self-terminates when idle. No manual setup beyond initial extension connection.

When to Use This Skill

Use this skill when the user wants to:

• Control a Chrome browser from the terminal without an MCP client
• Open, close, switch, or organize browser tabs via CLI
• Search for page elements and interact with them (click, fill, hover)
• Capture screenshots of browser tabs
• Automate browser workflows in shell scripts or CI pipelines
• Download page content as markdown or images
• Request human input during automated browser tasks
• Manage AIPex skills from the command line

Trigger phrases: "browser-cli", "control browser from terminal", "browser automation CLI", "click element from shell", "terminal browser control", "command line browser", "shell browser automation"

Installation

Prerequisites

• Node.js >= 18 installed
• AIPex Chrome extension installed (Chrome Web Store or developer build)

Install browser-cli

npm install -g browser-cli

Verify the installation:

browser-cli --version

Connect AIPex Extension

After installing, connect the AIPex Chrome extension to the daemon:

1. Open Chrome → click the AIPex extension icon → Options
2. Find the WebSocket Connection section
3. Set WebSocket URL to ws://localhost:9223/extension
4. Click Connect

Verify the connection:

browser-cli status

A successful response:

{
  "ok": true,
  "data": {
    "status": "ok",
    "extensionConnected": true,
    "bridgeClients": 0
  }
}

Quick Start

browser-cli tab list                         # List all open tabs
browser-cli tab new https://example.com      # Open a tab
browser-cli page search "button*" --tab 123  # Find elements
browser-cli interact click btn-42 --tab 123  # Interact
browser-cli page screenshot                  # Verify visually

Command Groups

tab — Manage browser tabs

browser-cli tab list                         # List all open tabs
browser-cli tab current                      # Get the active tab
browser-cli tab new https://example.com      # Open a new tab
browser-cli tab switch 42                    # Switch to tab by ID
browser-cli tab close 42                     # Close a tab
browser-cli tab info 42                      # Get tab details
browser-cli tab organize                     # AI-powered tab grouping
browser-cli tab ungroup                      # Remove all tab groups

page — Inspect and interact with page content

browser-cli page search "button*" --tab 123              # Search elements by glob pattern
browser-cli page search "{input,textarea}*" --tab 123    # Search multiple element types
browser-cli page screenshot                               # Screenshot active tab
browser-cli page screenshot-tab 123 --send-to-llm true   # Screenshot with LLM analysis
browser-cli page metadata --tab 123                       # Get page metadata
browser-cli page scroll-to "#main-content"                # Scroll to element
browser-cli page highlight "button.submit"                # Highlight element
browser-cli page highlight-text "p" "important"           # Highlight text in content

interact — Click, fill, hover, and type

browser-cli interact click btn-42 --tab 123                         # Click by UID
browser-cli interact fill input-5 "hello world" --tab 123           # Fill input by UID
browser-cli interact hover menu-3 --tab 123                         # Hover by UID
browser-cli interact form --tab 123 --elements '[{"uid":"in-1","value":"foo"}]'  # Batch fill
browser-cli interact editor editor-1 --tab 123                     # Get editor content
browser-cli interact upload --tab 123 --file-path /path/to/file    # Upload file
browser-cli interact computer --action left_click --coordinate "[500,300]"  # Pixel-level click

download — Save content locally

browser-cli download markdown --text "# Notes" --filename notes    # Save as markdown
browser-cli download image --data "data:image/png;base64,..."      # Save image
browser-cli download chat-images --messages '[...]' --folder imgs   # Batch save images

intervention — Request human input

browser-cli intervention list                                       # List intervention types
browser-cli intervention info voice-input                           # Get type details
browser-cli intervention request voice-input --reason "Need input"  # Request intervention
browser-cli intervention cancel                                     # Cancel active request

skill — Manage AIPex skills

browser-cli skill list                                    # List all skills
browser-cli skill load my-skill                           # Load skill content
browser-cli skill info my-skill                           # Skill details
browser-cli skill run my-skill scripts/init.js            # Execute skill script
browser-cli skill ref my-skill references/guide.md        # Read skill reference
browser-cli skill asset my-skill assets/icon.png          # Get skill asset

Standalone commands

browser-cli status    # Check daemon + extension connection
browser-cli update    # Self-update to latest version

Workflow: Search, Interact, Verify

The recommended pattern for browser automation:

# 1. Discover tabs
browser-cli tab list

# 2. Search for elements (fast, no screenshot needed)
browser-cli page search "{button,input,link}*" --tab 123

# 3. Interact using UIDs from search results
browser-cli interact click btn-submit --tab 123
# or
browser-cli interact fill input-email "user@example.com" --tab 123

# 4. Verify visually (only when needed)
browser-cli page screenshot

Login form example

browser-cli page search "{input,textbox}*" --tab 123
browser-cli interact fill input-email "user@example.com" --tab 123
browser-cli interact fill input-pass "secret" --tab 123
browser-cli page search "*[Ll]ogin*" --tab 123
browser-cli interact click btn-login --tab 123

Shell script example

#!/bin/bash
browser-cli tab new https://example.com
sleep 2
TAB_ID=$(browser-cli tab current | jq '.data.id')
browser-cli page search "link*" --tab "$TAB_ID"
browser-cli page screenshot

Global Options

Environment Variables

Troubleshooting