---
name: browser
description: Automate browsers with the Vibium CLI. Use to navigate websites, inspect pages, fill forms, extract page data, debug UI behavior, capture screenshots and recordings, or delegate browser goals with vibium run.
---

# Vibium Browser Automation — CLI Reference

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

Use this skill for browser automation, exploration, debugging, and recording.
Choose explicit CLI commands when you know the steps, or use `vibium run`
when a model should work out how to accomplish a browser goal.

For an independent acceptance verdict, use the `check` skill if installed,
or `vibium check "<claim>"`. Run’s `completed` result and your own browser
observations do not substitute for that invocation.

## Core Workflow

For direct browser commands, use 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.

## Browser readiness

During initial setup, run `vibium ready browser --json` with the engine/channel
that the workflow will use. It inspects installed browser and driver files
without launching them or touching existing sessions. Passing confirms the
installation, not browser launch or BiDi connectivity. If installation is missing, use the reported `vibium install`
command and retry. Direct browser work does not need AI configuration.
Do not rerun readiness before every action when setup is unchanged.

## Delegate a browser goal with Run

Use `vibium run "<goal>"` when the task is clear but the sequence of browser
actions needs investigation. For known steps, use the commands below directly.
Run uses the existing local Chrome or Firefox session and a fresh model context.
Keep the same `--session` or `VIBIUM_SESSION` throughout the workflow.

Load the project's configured AI settings in the shell running the CLI. Settings
in an environment file must use exported assignments (`export NAME=value`).
Run `vibium ready ai --json` during initial setup or after configuration changes;
`result.ready: true` means the provider tool round-trip passed. Never print
credentials. Direct browser commands do not require a model or AI readiness.

With a settings page already open:

```sh
vibium run "Change the timezone to America/Chicago and save it" --json -o browser-run.zip
```

`vibium "<multiword goal>"` is shorthand for Run. Use explicit `run` in scripts
or when the prompt could be mistaken for a command.

Read `result.status` (`completed` or `not_completed`), the summary, and evidence.
Execution failures return an error. If independent verification is needed,
follow with the `check` skill or `vibium check "<claim>"` in the same session;
Check starts another fresh model context.

`-o` saves a recording to a new path. An existing recording is exported without
stopping it. A browser that Run starts closes afterward unless `--keep-open`
is set; a browser already open stays open. Run can change application state.

Run and Check share `VIBIUM_AI_*` defaults. Per-call `--provider`, `--model`,
`--ai-base-url`, and `--reasoning-effort` also work with `vibium ready ai`. When changing
provider, supply a model explicitly; inherited endpoint and effort settings
are cleared. Credentials remain in the provider's environment variable.
Use the project's chosen provider rather than silently switching it.

## 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 set "<selector>"` — check a checkbox/radio (idempotent)
- `vibium unset "<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 set "<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`, `-o path` — defaults to a timestamped `record-<date>.zip`, so reruns never overwrite)
- `vibium record stop` — stop recording and save ZIP (`-o path` overrides the start path; the output names the saved file)

Recordings can include a video track of the session (Firefox 154+, local
browsers). By default video is recorded when the engine supports it and
skipped otherwise — the stop result says which. Pass `--video` to require
it (fails with an explanatory error on Chrome), `--video=false` to disable,
and `--video-size 1280x720` / `--video-fps 30` to override the viewport
defaults. The video lands inside the recording ZIP next to the trace
(`video/<context>.webm`); it films the page that was active at start and
does not follow tab switches. Remote browser connections record every
track except video; `--video-remote keep` records anyway and leaves the
file on the remote host (the stop output names its path there).

```
vibium record start --video -o run.zip
# ... actions ...
vibium record stop
# Saved run.zip (23 steps, 14s video)
```

### 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 new --isolated [url]` — open page with its own cookies/storage
- `vibium page switch <index|url>` — switch page
- `vibium page close [index|page id]` — 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
- `vibium --session <name> <command>` — run against an isolated daemon and browser

## Common Patterns

### Ref-based workflow (recommended for AI)
```sh
vibium go https://example.com
vibium map
vibium click @e1
vibium map  # re-map after interaction
```

### Check action worked
```sh
vibium map
vibium click @e3
vibium diff map  # see what changed
```

### Read a page
```sh
vibium go https://example.com && vibium text
```

### Fill a form (end-to-end)
```sh
vibium go https://example.com/login
vibium map
# Look at map output to identify form fields
vibium fill @e1 "user@example.com"
vibium fill @e2 "secret"
vibium click @e3
vibium wait url "/dashboard"
vibium screenshot -o after-login.png
```

### Scoped map (large pages)
```sh
vibium map --selector "nav"        # Only map elements in <nav>
vibium map --selector "#sidebar"   # Only map elements in #sidebar
vibium map --selector "form"       # Only map form controls
```

### Semantic find (no CSS selectors needed)
```sh
vibium find text "Sign In"             # → @e1 [button] "Sign In"
vibium find label "Email"              # → @e1 [input] placeholder="Email"
vibium click @e1                       # Click the found element
vibium find placeholder "Search..."    # → @e1 [input] placeholder="Search..."
vibium find testid "submit-btn"        # → @e1 [button] "Submit"
vibium find alt "Company logo"         # → @e1 [img] alt="Company logo"
vibium find title "Close"              # → @e1 [button] title="Close"
vibium find xpath "//a[@href='/about']"  # → @e1 [a] "About"
```

### Authentication with state persistence
```sh
# Log in once and save state
vibium go https://app.example.com/login
vibium fill "input[name=email]" "user@example.com"
vibium fill "input[name=password]" "secret"
vibium click "button[type=submit]"
vibium wait url "/dashboard"
vibium storage -o auth.json

# Restore in a later session (skips login)
vibium storage restore auth.json
vibium go https://app.example.com/dashboard
```

### Extract structured data
```sh
vibium go https://example.com
vibium eval "JSON.stringify([...document.querySelectorAll('a')].map(a => ({text: a.textContent.trim(), href: a.href})))"
```

### Check page structure without rendering
```sh
vibium go https://example.com && vibium a11y-tree
```

### Remote browser
```sh
vibium start ws://remote-host:9515/session
vibium go https://example.com
vibium map
vibium stop
```

### Concurrent sessions (isolated browsers)
```sh
# Two scripts on one host, each with its own daemon and browser
export VIBIUM_SESSION=checkout-tests
vibium go https://example.com/checkout
vibium daemon stop

# Or per command, to drive two browsers from one script
vibium --session buyer go https://shop.example.com
vibium --session seller go https://shop.example.com/admin
```

### Isolated pages (one browser, separate cookies/storage)
```sh
# Lighter than a session: two logins in one browser, no second launch
vibium page new --isolated https://shop.example.com   # prints (page: <id>)
vibium page new --isolated https://shop.example.com
vibium page close <id>   # also removes the page's isolated context
```

### Multi-page workflow
```sh
vibium page new https://docs.example.com
vibium text "h1"
vibium page switch 0
```

### Annotated screenshot
```sh
vibium screenshot -o annotated.png --annotate
```

### Inspect an element
```sh
vibium attr "a" "href"
vibium value "input[name=email]"
vibium is visible ".modal"
```

### Save as PDF
```sh
vibium go https://example.com && vibium pdf -o page.pdf
```

## Eval / JavaScript

`vibium eval` is the escape hatch for any DOM query or mutation the CLI doesn't cover directly.

**Simple expressions** — use single quotes:
```sh
vibium eval 'document.title'
vibium eval 'document.querySelectorAll("li").length'
```

**Complex scripts** — use `--stdin` with a heredoc:
```sh
vibium eval --stdin <<'EOF'
const rows = [...document.querySelectorAll('table tbody tr')];
JSON.stringify(rows.map(r => {
  const cells = r.querySelectorAll('td');
  return { name: cells[0].textContent.trim(), price: cells[1].textContent.trim() };
}));
EOF
```

**JSON output** — use `--json` to get machine-readable output:
```sh
vibium eval --json 'JSON.stringify({url: location.href, title: document.title})'
```

**Important:** `eval` returns the expression result. If your script doesn't return a value, you'll get `null`. Always make sure the last expression evaluates to the data you want.

## Timeouts and Waiting

All interaction commands (`click`, `fill`, `type`, etc.) auto-wait for the target element to be actionable. You usually don't need explicit waits.

Use explicit waits when:
- **Waiting for navigation:** `vibium wait url "/dashboard"` — after clicking a link that navigates
- **Waiting for content:** `vibium wait text "Success"` — after form submission, wait for confirmation
- **Waiting for element:** `vibium wait ".modal"` — wait for a modal to appear
- **Waiting for page load:** `vibium wait load` — after navigation to a slow page
- **Waiting for JS condition:** `vibium wait fn "window.appReady === true"` — wait for app initialization
- **Fixed delay (last resort):** `vibium sleep 2000` — only when no better signal exists (max 30s)

All wait commands accept `--timeout <ms>` (default varies by command).

## Ref Lifecycle

Refs (`@e1`, `@e2`) are invalidated when the page changes. Always re-map after:
- Clicking links or buttons that navigate
- Form submissions
- Dynamic content loading (dropdowns, modals)

## Global Flags

| Flag | Description |
|------|-------------|
| `--engine <name>` | Browser engine: `chrome` (default) or `firefox` (env: `VIBIUM_ENGINE`) |
| `--channel <ch>` | Engine release channel — Firefox: `release` (default) or `beta`; Chrome: `stable` (default), `beta`, `dev`, or `canary` (env: `VIBIUM_ENGINE_CHANNEL`) |
| `--headless` | Hide browser window |
| `--json` | Output as JSON |
| `-v, --verbose` | Debug logging |
| `--session <name>` | Isolated daemon + browser for concurrent use (env: `VIBIUM_SESSION`) |

## Tips

- All click/type/hover/fill actions auto-wait for the element to be actionable
- All selector arguments also accept `@ref` from `vibium map`
- Use `vibium map` before interacting to discover interactive elements
- Use `vibium map --selector` to reduce noise on large pages
- Use `vibium fill` to replace a field's value, `vibium type` to append to it
- Use `vibium find text` / `find label` / `find testid` for semantic element lookup (more reliable than CSS selectors)
- Use `vibium find role` for ARIA-role-based lookup
- Use `vibium a11y-tree` to understand page structure without visual rendering
- Use `vibium text "<selector>"` to read specific sections
- Use `vibium diff map` after interactions to see what changed
- `vibium eval` is the escape hatch for complex DOM queries
- `vibium set`/`vibium unset` are idempotent — safe to call without checking state first
- Screenshots save to the current directory by default (`-o` to change)
- Use `vibium storage` / `vibium storage restore` to persist auth across sessions
- Without `--session`, all commands on a host share one daemon and one browser — set `VIBIUM_SESSION` when running concurrently