veb

Headless browser automation CLI for agents and humans.

Installation

pnpm install
npx playwright install chromium
pnpm build

Quick Start

veb open example.com
veb click "#submit"
veb fill "#email" "test@example.com"
veb get text "h1"
veb screenshot page.png
veb close

Commands

Core Commands

veb open <url>              # Navigate to URL
veb click <sel>             # Click element
veb type <sel> <text>       # Type into element
veb fill <sel> <text>       # Clear and fill
veb press <key>             # Press key (Enter, Tab, Control+a)
veb keydown <key>           # Hold key down
veb keyup <key>             # Release key
veb insert <text>           # Insert text (no key events)
veb hover <sel>             # Hover element
veb select <sel> <val>      # Select dropdown option
veb multiselect <sel> <v1> <v2>  # Multi-select
veb check <sel>             # Check checkbox
veb uncheck <sel>           # Uncheck checkbox
veb scroll <dir> [px]       # Scroll (up/down/left/right)
veb scrollinto <sel>        # Scroll element into view
veb drag <src> <tgt>        # Drag and drop
veb upload <sel> <files>    # Upload files
veb download [path]         # Wait for download
veb screenshot [path]       # Take screenshot (--full for full page)
veb pdf <path>              # Save as PDF
veb snapshot                # Accessibility tree (best for AI)
veb eval <js>               # Run JavaScript
veb close                   # Close browser

Get Info

veb get text <sel>          # Get text content
veb get html <sel>          # Get innerHTML
veb get value <sel>         # Get input value
veb get attr <sel> <attr>   # Get attribute
veb get title               # Get page title
veb get url                 # Get current URL
veb get count <sel>         # Count matching elements
veb get box <sel>           # Get bounding box

Check State

veb is visible <sel>        # Check if visible
veb is enabled <sel>        # Check if enabled
veb is checked <sel>        # Check if checked

Find Elements (Semantic Locators)

veb find role <role> <action> [value]       # By ARIA role
veb find text <text> <action>               # By text content
veb find label <label> <action> [value]     # By label
veb find placeholder <ph> <action> [value]  # By placeholder
veb find alt <text> <action>                # By alt text
veb find title <text> <action>              # By title attr
veb find testid <id> <action> [value]       # By data-testid
veb find first <sel> <action> [value]       # First match
veb find last <sel> <action> [value]        # Last match
veb find nth <n> <sel> <action> [value]     # Nth match

Actions: click, fill, check, hover, text

Examples:

veb find role button click --name "Submit"
veb find text "Sign In" click
veb find label "Email" fill "test@test.com"
veb find first ".item" click
veb find nth 2 "a" text

Wait

veb wait <selector>         # Wait for element
veb wait <ms>               # Wait for time
veb wait --text "Welcome"   # Wait for text
veb wait --url "**/dash"    # Wait for URL pattern
veb wait --load networkidle # Wait for load state
veb wait --fn "window.ready === true"  # Wait for JS condition

Load states: load, domcontentloaded, networkidle

Mouse Control

veb mouse move <x> <y>      # Move mouse
veb mouse down [button]     # Press button (left/right/middle)
veb mouse up [button]       # Release button
veb mouse wheel <dy> [dx]   # Scroll wheel

Browser Settings

veb set viewport <w> <h>    # Set viewport size
veb set device <name>       # Emulate device ("iPhone 14")
veb set geo <lat> <lng>     # Set geolocation
veb set offline [on|off]    # Toggle offline mode
veb set headers <json>      # Extra HTTP headers
veb set credentials <u> <p> # HTTP basic auth
veb set media [dark|light|print]  # Emulate media

Cookies & Storage

veb cookies                 # Get all cookies
veb cookies set <json>      # Set cookies
veb cookies clear           # Clear cookies

veb storage local           # Get all localStorage
veb storage local <key>     # Get specific key
veb storage local set <k> <v>  # Set value
veb storage local clear     # Clear all

veb storage session         # Same for sessionStorage

Network

veb network route <url>              # Intercept requests
veb network route <url> --abort      # Block requests
veb network route <url> --body <json>  # Mock response
veb network unroute [url]            # Remove routes
veb network requests                 # View tracked requests
veb network requests --filter api    # Filter requests
veb response <url>                   # Get response body (waits for matching request)

Tabs & Windows

veb tab                     # List tabs
veb tab new                 # New tab
veb tab <n>                 # Switch to tab n
veb tab close [n]           # Close tab
veb window new              # New window

Frames

veb frame <sel>             # Switch to iframe
veb frame main              # Back to main frame

Dialogs

veb dialog accept [text]    # Accept (with optional prompt text)
veb dialog dismiss          # Dismiss

Debug

veb trace start             # Start recording trace
veb trace stop <path>       # Stop and save trace
veb console                 # View console messages
veb console --clear         # Clear console
veb errors                  # View page errors
veb highlight <sel>         # Highlight element
veb state save <path>       # Save auth state
veb state load <path>       # Load auth state
veb initscript <js>         # Run JS on every page load

Navigation

veb back                    # Go back
veb forward                 # Go forward
veb reload                  # Reload page

Sessions

veb session                 # Show current session
veb session list            # List active sessions

Options

Option	Description
--session <name>	Use isolated session (or VEB_SESSION env)
--json	JSON output (for agents)
--full, -f	Full page screenshot
--name, -n	Locator name filter
--exact	Exact text match
--debug	Debug output

Sessions

Run multiple isolated browser instances:

# Different sessions
veb --session agent1 open site-a.com
veb --session agent2 open site-b.com

# Or via environment
VEB_SESSION=agent1 veb click "#btn"

# List all
veb session list

Selectors

# CSS
veb click "#id"
veb click ".class"
veb click "div > button"

# Text
veb click "text=Submit"

# XPath
veb click "xpath=//button"

# Semantic (recommended)
veb find role button click --name "Submit"
veb find label "Email" fill "test@test.com"

Agent Mode

Use --json for machine-readable output:

veb snapshot --json
veb get text "h1" --json
veb is visible ".modal" --json

License

MIT