/vibe-check

name: vibe-check
description: Browser automation for AI agents. Use when the user needs to navigate websites, read page content, fill forms, click elements, take screenshots, or manage browser pages.

Vibium Browser Automation — CLI Reference

The `vibium` CLI automates Chrome via the command line. The browser auto-launches on first use (daemon mode keeps it running between commands).

vibium go <url> && vibium map && vibium click @e1 && vibium map

Core Workflow

Every browser automation follows this pattern:

1. **Navigate**: `vibium go <url>` 2. **Map**: `vibium map` (get element refs like `@e1`, `@e2`) 3. **Interact**: Use refs to click, fill, select — e.g. `vibium click @e1` 4. **Re-map**: After navigation or DOM changes, get fresh refs with `vibium map`

Binary Resolution

Before running any commands, resolve the `vibium` binary path once:

1. Try `vibium` directly (works if globally installed via `npm install -g vibium`) 2. Fall back to `./clicker/bin/vibium` (dev environment, in project root) 3. Fall back to `./node_modules/.bin/vibium` (local npm install)

Run `vibium --help` (or the resolved path) to confirm. Use the resolved path for all subsequent commands.

**Windows note:** Use forward slashes in paths (e.g. `./clicker/bin/vibium.exe`) and quote paths containing spaces.

Command Chaining

Chain commands with `&&` to run them sequentially. The chain stops on first error:

vibium go https://example.com && vibium map && vibium click @e3 && vibium diff map

**When to chain:** Use `&&` for sequences that should happen back-to-back (navigate → interact → verify). Run commands separately when you need to inspect output between steps.

**When NOT to chain:** Don't chain commands that depend on parsing the previous output (e.g. reading map output to decide what to click). Run those separately so you can analyze the result first.

Commands

Discovery

• `vibium map` — map interactive elements with @refs (recommended before interacting)
• `vibium map --selector "nav"` — scope map to elements within a CSS subtree
• `vibium diff map` — compare current vs last map (see what changed)

Navigation

• `vibium go <url>` — go to a page
• `vibium back` — go back in history
• `vibium forward` — go forward in history
• `vibium reload` — reload the current page
• `vibium url` — print current URL
• `vibium title` — print page title

Reading Content

• `vibium text` — get all page text
• `vibium text "<selector>"` — get text of a specific element
• `vibium html` — get page HTML (use `--outer` for outerHTML)
• `vibium find "<selector>"` — find element, return `@e1` ref (clickable with `vibium click @e1`)
• `vibium find "<selector>" --all` — find all matching elements → `@e1`, `@e2`, ... (`--limit N`)
• `vibium find text "Sign In"` — find element by text content → `@e1`
• `vibium find label "Email"` — find input by label → `@e1`
• `vibium find placeholder "Search"` — find by placeholder → `@e1`
• `vibium find testid "submit-btn"` — find by data-testid → `@e1`
• `vibium find xpath "//div[@class]"` — find by XPath → `@e1`
• `vibium find alt "Logo"` — find by alt attribute → `@e1`
• `vibium find title "Settings"` — find by title attribute → `@e1`
• `vibium find role <role>` — find element by ARIA role → `@e1` (`--name` for accessible name filter)
• `vibium eval "<js>"` — run JavaScript and print result (`--stdin` to read from stdin)
• `vibium count "<selector>"` — count matching elements
• `vibium screenshot -o file.png` — capture screenshot (`--full-page`, `--annotate`)
• `vibium a11y-tree` — accessibility tree (`--everything` for all nodes)

Interaction

• `vibium click "<selector>"` — click an element (also accepts `@ref` from map)
• `vibium dblclick "<selector>"` — double-click an element
• `vibium type "<selector>" "<text>"` — type into an input (appends to existing value)
• `vibium fill "<selector>" "<text>"` — clear field and type new text (replaces value)
• `vibium press <key> [selector]` — press a key on element or focused element
• `vibium focus "<selector>"` — focus an element
• `vibium hover "<selector>"` — hover over an element
• `vibium scroll [direction]` — scroll page (`--amount N`, `--selector`)
• `vibium scroll into-view "<selector>"` — scroll element into view (centered)
• `vibium keys "<combo>"` — press keys (Enter, Control+a, Shift+Tab)
• `vibium select "<selector>" "<value>"` — pick a dropdown option
• `vibium check "<selector>"` — check a checkbox/radio (idempotent)
• `vibium uncheck "<selector>"` — uncheck a checkbox (idempotent)

Mouse Primitives

• `vibium mouse click [x] [y]` — click at coordinates or current position (`--button 0|1|2`)
• `vibium mouse move <x> <y>` — move mouse to coordinates
• `vibium mouse down` — press mouse button (`--button 0|1|2`)
• `vibium mouse up` — release mouse button (`--button 0|1|2`)
• `vibium drag "<source>" "<target>"` — drag from one element to another

Element State

• `vibium value "<selector>"` — get input/textarea/select value
• `vibium attr "<selector>" "<attribute>"` — get HTML attribute value
• `vibium is visible "<selector>"` — check if element is visible (true/false)
• `vibium is enabled "<selector>"` — check if element is enabled (true/false)
• `vibium is checked "<selector>"` — check if checkbox/radio is checked (true/false)
• `vibium is actionable "<selector>"` — check if element is actionable (true/false)

Waiting

• `vibium wait "<selector>"` — wait for element (`--state visible|hidden|attached`, `--timeout ms`)
• `vibium wait url "<pattern>"` — wait until URL contains substring (`--timeout ms`)
• `vibium wait load` — wait until page is fully loaded (`--timeout ms`)
• `vibium wait text "<text>"` — wait until text appears on page (`--timeout ms`)
• `vibium wait fn "<expression>"` — wait until JS expression returns truthy (`--timeout ms`)
• `vibium sleep <ms>` — pause execution (max 30000ms)

Capture

• `vibium screenshot -o file.png` — capture screenshot (`--full-page