/browser/agent-harness/cli_anything/browser

cli-anything-browser — Browser Automation CLI

A command-line interface for browser automation using DOMShell's MCP server. Maps Chrome's Accessibility Tree to a virtual filesystem for agent-native browser automation.

Features

• Filesystem-first navigation: Use ls, cd, cat to explore web pages
• Search: grep for text patterns in the accessibility tree
• Actions: click, type to interact with elements
• JSON output: --json flag for machine-readable output
• Interactive REPL: Stateful session with command history
• Daemon mode: Optional persistent connection for faster interactive use

Installation

Prerequisites

1. Node.js and npx (required for DOMShell MCP server):

   # Install Node.js from https://nodejs.org/
   node --version
   npx --version
   

2. Chrome/Chromium with DOMShell extension:

   • Install DOMShell from Chrome Web Store
   • Ensure Chrome is running before using the CLI

3. Python 3.10+:

   python --version
   

Install CLI

cd browser/agent-harness
pip install -e .

Verify installation:

cli-anything-browser --help

Usage

One-Shot Commands

# Open a page
cli-anything-browser page open https://example.com

# List elements at root
cli-anything-browser fs ls /

# Navigate into a section
cli-anything-browser fs cd /main

# List elements in current directory
cli-anything-browser fs ls

# Read element content
cli-anything-browser fs cat /main/button[0]

# Search for text
cli-anything-browser fs grep "Login"

# Click an element
cli-anything-browser act click /main/button[0]

# Type into an input
cli-anything-browser act type /main/input[0] "Hello, World!"

# Get page info
cli-anything-browser page info

# Navigate back/forward
cli-anything-browser page back
cli-anything-browser page forward

Note: One-shot commands each start with a fresh session (no URL or working directory). For stateful workflows (like cd followed by ls without a path), use the REPL instead.

JSON Output

# Get machine-readable output
cli-anything-browser --json fs ls /

# Returns:
{
  "path": "/",
  "entries": [
    {
      "name": "main",
      "role": "landmark",
      "path": "/main"
    }
  ]
}

Daemon Mode (Persistent Connection)

For faster interactive use, start daemon mode within a REPL session:

# Start REPL with daemon mode
cli-anything-browser --daemon

# Or start daemon within REPL
session daemon-start

# Run commands (uses persistent connection)
fs ls /
fs cd /main

# Stop daemon when done
session daemon-stop

Note: Daemon mode only works within a single running process (REPL or --daemon flag). State does not persist across separate CLI invocations.

Interactive REPL

Run without arguments to enter interactive mode:

cli-anything-browser

REPL commands:

• page open <url> — Open a URL
• fs ls [path] — List elements
• fs cd <path> — Change directory
• fs cat [path] — Read element
• fs grep <pattern> — Search for text
• fs pwd — Print working directory
• act click <path> — Click element
• act type <path> <text> — Type text
• session status — Show session state
• help — Show commands
• quit — Exit REPL

Command Groups

page — Page Navigation

• open <url> — Navigate to URL
• reload — Reload current page
• back — Navigate back in history
• forward — Navigate forward in history
• info — Show current page info

fs — Filesystem Commands

• ls [path] — List elements at path
• cd <path> — Change directory
• cat [path] — Read element content
• grep <pattern> [path] — Search for text
• pwd — Print working directory

act — Action Commands

• click <path> — Click an element
• type <path> <text> — Type text into input

session — Session Management

• status — Show session status
• daemon-start — Start persistent daemon mode
• daemon-stop — Stop daemon mode

Path Syntax

DOMShell uses a filesystem-like path syntax for the Accessibility Tree:

/                           — Root (page)
/main                       — Main landmark
/main/div[0]                — First div in main
/main/div[0]/button[2]      — Third button in first div

Array indices are 0-based. Use relative paths with .. to go up.

Examples

Basic Navigation

# Open a page
cli-anything-browser page open https://example.com

# Explore structure
cli-anything-browser fs ls /
cli-anything-browser fs cd /main
cli-anything-browser fs ls

# Go back to root
cli-anything-browser fs cd /

Search and Click

# Open page and search for login button
cli-anything-browser page open https://example.com/login
cli-anything-browser fs grep "Login"

# Click the login button (adjust path as needed)
cli-anything-browser act click /main/button[0]

Form Fill

# Type into form fields
cli-anything-browser act type /main/input[0] "user@example.com"
cli-anything-browser act type /main/input[1] "password123"

# Click submit
cli-anything-browser act click /main/button[0]

Testing

Run tests:

# Unit tests (no Chrome required)
pytest cli_anything/browser/tests/test_core.py -v

# E2E tests (requires Chrome + DOMShell)
pytest cli_anything/browser/tests/test_full_e2e.py -v

Troubleshooting

"npx not found"

Install Node.js from https://nodejs.org/

"DOMShell not found"

Run: npx @apireno/domshell --version (first run downloads the package)

"DOMShell MCP call failed"

• Ensure Chrome is running
• Install DOMShell extension from Chrome Web Store
• Check that DOMShell is enabled in Chrome

Commands hang on first use

First npx call downloads DOMShell package (10-50 MB). Subsequent calls are faster. Use --daemon mode for persistent connection.

Architecture

This CLI follows the CLI-Anything harness methodology:

• Backend: DOMShell MCP server via stdio transport
• State: Page state (URL, working directory, navigation history)
• Pattern: Filesystem-first commands map to Accessibility Tree

Links

• DOMShell GitHub
• CLI-Anything
• Issue #90

License

Apache License 2.0 — See CLI-Anything for details.