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:
- Navigate:
vibium go <url>
- Map:
vibium map (get element refs like @e1, @e2)
- Interact: Use refs to click, fill, select — e.g.
vibium click @e1
- 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:
- Try
vibium directly (works if globally installed via npm install -g vibium)
- Fall back to
./clicker/bin/vibium (dev environment, in project root)
- 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 subtreevibium diff map — compare current vs last map (see what changed)
Navigation
vibium go <url> — go to a pagevibium back — go back in historyvibium forward — go forward in historyvibium reload — reload the current pagevibium url — print current URLvibium title — print page title
Reading Content
vibium text — get all page textvibium text "<selector>" — get text of a specific elementvibium 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 → @e1vibium find label "Email" — find input by label → @e1vibium find placeholder "Search" — find by placeholder → @e1vibium find testid "submit-btn" — find by data-testid → @e1vibium find xpath "//div[@class]" — find by XPath → @e1vibium find alt "Logo" — find by alt attribute → @e1vibium find title "Settings" — find by title attribute → @e1vibium 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 elementsvibium 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 elementvibium 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 elementvibium focus "<selector>" — focus an elementvibium hover "<selector>" — hover over an elementvibium 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 optionvibium 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 coordinatesvibium 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 valuevibium attr "<selector>" "<attribute>" — get HTML attribute valuevibium 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 dimensionsvibium viewport <width> <height> — set viewport size (--dpr for device pixel ratio)vibium window — get OS browser window dimensions and statevibium 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 pagevibium 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 cookiesvibium cookies <name> <value> — set a cookievibium 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 pagesvibium page new [url] — open new pagevibium page switch <index|url> — switch pagevibium page close [index] — close page
Debug
vibium highlight "<selector>" — highlight element visually (3 seconds)
Session
vibium start — start a local browser sessionvibium start <url> — start connected to a remote browservibium stop — stop the browser sessionvibium daemon start — start background browservibium daemon status — check if runningvibium daemon stop — stop daemon
Common Patterns
Ref-based workflow (recommended for AI)
vibium go https://example.com
vibium map
vibium click @e1
vibium map
Verify action worked
vibium map
vibium click @e3
vibium diff map
Read a page
vibium go https://example.com && vibium text
Fill a form (end-to-end)
vibium go https://example.com/login
vibium map
vibium fill @e1 "[email protected]"
vibium fill @e2 "secret"
vibium click @e3
vibium wait url "/dashboard"
vibium screenshot -o after-login.png
Scoped map (large pages)
vibium map --selector "nav"
vibium map --selector "#sidebar"
vibium map --selector "form"
Semantic find (no CSS selectors needed)
vibium find text "Sign In"
vibium find label "Email"
vibium click @e1
vibium find placeholder "Search..."
vibium find testid "submit-btn"
vibium find alt "Company logo"
vibium find title "Close"
vibium find xpath "//a[@href='/about']"
Authentication with state persistence
vibium go https://app.example.com/login
vibium fill "input[name=email]" "[email protected]"
vibium fill "input[name=password]" "secret"
vibium click "button[type=submit]"
vibium wait url "/dashboard"
vibium storage -o auth.json
vibium storage restore auth.json
vibium go https://app.example.com/dashboard
Extract structured data
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
vibium go https://example.com && vibium a11y-tree
Remote browser
vibium start ws://remote-host:9515/session
vibium go https://example.com
vibium map
vibium stop
Multi-page workflow
vibium page new https://docs.example.com
vibium text "h1"
vibium page switch 0
Annotated screenshot
vibium screenshot -o annotated.png --annotate
Inspect an element
vibium attr "a" "href"
vibium value "input[name=email]"
vibium is visible ".modal"
Save as PDF
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:
vibium eval 'document.title'
vibium eval 'document.querySelectorAll("li").length'
Complex scripts — use --stdin with a heredoc:
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:
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 |
--headless |
Hide browser window |
--json |
Output as JSON |
-v, --verbose |
Debug logging |
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 secti
