Browser

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:

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:

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)