browser4-cli

Files (5)

• SKILL.md
• agent.md · references/
• crawl.md · references/
• htmlsnapshot.md · references/
• x-sql.md · references/

SKILL.md (first lines)

# Browser Automation with browser4-cli

Browser4 CLI is a **coroutine-safe, high-performance browser automation engine** for AI agents.
It uses Chrome DevTools Protocol (CDP) with accessibility-tree snapshots for element interaction
and raw HTML snapshots for data extraction.

- **Session management**: auto-open/reconnect browsers, named sessions, attach to existing Chrome
- **Element interaction**: click, fill, type, press, select, check, uncheck, drag — all via accessibility refs
- **Data extraction**: CSS selectors, X-SQL queries, regex grep, LLM-powered extraction
- **Bulk processing**: recursive crawl, parallel swarm, repeated loop
- **Output modes**: human-readable, JSON (`--json`), quiet (`--quiet`)

## Quick Reference: Command Families

| Family | Purpose | Key commands |
|--------|---------|-------------|
| Session | Start/stop/reuse browser sessions | `open`, `goto`, `close`, `close-all`, `kill-all`, `attach`, `list`, `status` |
| Navigation | Move between pages | `goto <url>`, `go-back`, `go-forward`, `reload` |
| Snapshot | Capture page structure (accessibility tree) | `snapshot [-v N] [--auto-diff]`, `snapshot grep <pattern>` |
| Interaction | Click, type, fill forms | `click <ref>`, `fill <ref> <value>`, `type <ref> <text>`, `press <key>`, `select`, `check`, `uncheck`, `drag` |
| Extract (CSS) | Extract data via CSS selectors | `htmlsnapshot`, `htmlsnapshot get text/html/attr <selector>`, `get all`, `grep`, `inspect` |
| Extract (X-SQL) | Structured multi-field extraction | `htmlsnapshot query --sql "SELECT ..."` |
| Extract (AI) | Natural-language extraction | `extract "..."`, `summarize`, `agent run "..."` |
| Bulk | Multi-page traversal | `crawl`, `swarm`, `loop` |
| Storage | Cookies, localStorage, sessionStorage | `state-save`, `state-load`, `cookie-get`, `cookie-set`, `local-storage-*`, `session-storage-*` |
| Visual | Screenshots, viewport control | `screenshot [--filename f.png]`, `scroll`, `wait`, `resize`, `tab-*` |
| Script | Execute JS in page | `eval "JS code" [--json]` |

---

## 1. Core Loop (Copy-Paste Template)

Every browser4-cli session follows this pattern:

```bash
# 1. NAVIGATE — auto-opens/reconnects session
browser4-cli goto "https://example.com"

# 2. SNAPSHOT — capture accessibility tree with refs
browser4-cli snapshot -v 0

# 3. INTERACT — use refs from snapshot
browser4-cli fill <ref> "<value>"
browser4-cli press Enter

# 4. RE-SNAPSHOT — verify changes
browser4-cli wait --load networkidle
browser4-cli snapshot -v 0 --auto-diff

# 5. EXTRACT — get data
browser4-cli htmlsnapshot get text "<css-selector>" --all
```

---

## 2. Session & Lifecycle

### Named Sessions

Isolate browser state (cookies, localStorage, tabs) with `-s <name>`:

```bash
browser4-cli -s mysession goto "https://example.com"
browser4-cli -s mysession snapshot
browser4-cli -s mysession close
```

`goto` auto-opens/reconnects — you rarely need to manage sessions manually.

### Session Commands

```bash
# Open a new session (optionally with URL)
browser4-cli open [url] [--headed|--headless] [--profile <path>] [--profile-mode <mode>]

# Navigate — auto-opens if no session exists
browser4-cli goto <url>

# Attach to an existing Chrome/Edge via CDP
browser4-cli attach --cdp chrome                # by channel name
browser4-cli attach --cdp http://localhost:9222   # by CDP URL
browser4-cli attach --cdp 9222                    # by port

# Close
browser4-cli close                                 # current session
browser4-cli close-all                              # all sessions (keep backend)
browser4-cli kill-all                               # stop backend + kill all processes

# Status & list
browser4-cli status                                 # server health, version
browser4-cli list [--all]                           # session list with reuse/refresh status
browser4-cli stop                                   # gracefully stop server
browser4-cli delete-data                            # delete session data
```

### Browser Profile Management

```bash
# Create a profile (e.g., for persistent login)
browser4-cli open --profile /path/to/profile --profile-mode persistent
```

---

## 3. Navigation

```bash
browser4-cli goto <url>          # Navigate — auto-opens session
browser4-cli go-back             # Previous page
browser4-cli go-forward          # Next page
browser4-cli reload              # Reload current page
```

---

## 4. Snapshot (Accessibility Tree)

Captures a YAML accessibility tree with element refs for interaction.

From awaku7/agentcli, Apache-2.0.

More from awaku7/agentcli