vibe-check

What this skill does

# 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:

```sh
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`, `--annotate`)
- `vibium pdf -o file.pdf` — save page as PDF

### Dialogs
- `vibium dialog accept [text]` — accept dialog (optionally with prompt text)
- `vibium dialog dismiss` — dismiss dialog

### Emulation
- `vibium viewport` — get current viewport dimensions
- `vibium viewport <width> <height>` — set viewport size (`--dpr` for device pixel ratio)
- `vibium window` — get OS browser window dimensions and state
- `vibium window <width> <height> [x] [y]` — set window size and position (`--state`)
- `vibium media` — override CSS media features (`--color-scheme`, `--reduced-motion`, `--forced-colors`, `--contrast`, `--media`)
- `vibium geolocation <lat> <lng>` — override geolocation (`--accuracy`)
- `vibium content "<html>"` — replace page HTML (`--stdin` to read from stdin)

### Frames
- `vibium frames` — list all iframes on the page
- `vibium frame "<nameOrUrl>"` — find a frame by name or URL substring

### File Upload
- `vibium upload "<selector>" <files...>` — set files on input[type=file]

### Recording
- `vibium record start` — start recording (`--screenshots`, `--snapshots`, `--name`)
- `vibium record stop` — stop recording and save ZIP (`-o path`)

### Cookies
- `vibium cookies` — list all cookies
- `vibium cookies <name> <value>` — set a cookie
- `vibium cookies clear` — clear all cookies

### Storage State
- `vibium storage` — export cookies + localStorage + sessionStorage (`-o state.json`)
- `vibium storage restore <path>` — restore state from JSON file

### Downloads
- `vibium download dir <path>` — set download directory

### Pages
- `vibium pages` — list open pages
- `vibium page new [url]` — open new page
- `vibium page switch <index|url>` — switch page
- `vibium page close [index]` — close page

### Debug
- `vibium highlight "<selector>"` — highlight element visually (3 seconds)

### Session
- `vibium start` — start a local browser session
- `vibium start <url>` — start connected to a remote browser
- `vibium stop` — stop the browser session
- `vibium daemon start` — start background browser
- `vibium daemon status` — check if running
- `vibium daemon stop` — stop daemon

## Common Patterns

### Ref-based workflow (recommended for AI)
```sh
vibium go ht