171 lines
4.1 KiB
Markdown
171 lines
4.1 KiB
Markdown
# veb
|
|
|
|
Headless browser automation CLI for agents and humans.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pnpm install
|
|
npx playwright install chromium
|
|
pnpm build
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Open a URL (auto-starts browser daemon)
|
|
veb open https://example.com
|
|
|
|
# Click elements
|
|
veb click "#submit-btn"
|
|
veb click "text=Sign In"
|
|
|
|
# Type into inputs
|
|
veb type "#email" hello@example.com
|
|
veb type "#search" "search query"
|
|
|
|
# Press keyboard keys
|
|
veb press Enter
|
|
veb press Tab
|
|
|
|
# Wait for things
|
|
veb wait "#loading" # wait for selector
|
|
veb wait --text "Welcome" # wait for text
|
|
veb wait 2000 # wait 2 seconds
|
|
|
|
# Take screenshots
|
|
veb screenshot page.png
|
|
veb screenshot --full page.png # full page
|
|
veb screenshot -s "#hero" # specific element
|
|
|
|
# Get accessibility snapshot (great for AI agents)
|
|
veb snapshot
|
|
|
|
# Extract HTML content
|
|
veb extract "table"
|
|
veb extract "#main"
|
|
|
|
# Evaluate JavaScript
|
|
veb eval "document.title"
|
|
veb eval "window.location.href"
|
|
|
|
# Scroll the page
|
|
veb scroll down 500
|
|
veb scroll up
|
|
veb scroll -s "#container" down
|
|
|
|
# Interact with dropdowns
|
|
veb select "#country" "US"
|
|
|
|
# Hover over elements
|
|
veb hover "#menu"
|
|
|
|
# Tab management
|
|
veb tab new # Open new tab
|
|
veb tab list # List all tabs
|
|
veb tab 0 # Switch to tab 0
|
|
veb tab close # Close current tab
|
|
veb tab close 1 # Close tab 1
|
|
|
|
# Window management
|
|
veb window new # Open new window
|
|
|
|
# Session management (isolate multiple agents)
|
|
veb --session agent1 open example.com
|
|
veb --session agent2 open google.com
|
|
veb session list # List active sessions
|
|
VEB_SESSION=agent1 veb eval "document.title"
|
|
|
|
# Close browser (stops daemon)
|
|
veb close
|
|
```
|
|
|
|
## Agent Mode
|
|
|
|
Use `--json` flag for machine-readable output:
|
|
|
|
```bash
|
|
veb open https://example.com --json
|
|
# {"id":"abc123","success":true,"data":{"url":"https://example.com/","title":"Example Domain"}}
|
|
|
|
veb snapshot --json
|
|
# {"id":"def456","success":true,"data":{"snapshot":"..."}}
|
|
```
|
|
|
|
## How It Works
|
|
|
|
veb runs a background daemon that keeps the browser open between commands. The first command automatically starts the daemon. Use `veb close` to shut it down.
|
|
|
|
## Commands Reference
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `open <url>` | Navigate to a URL |
|
|
| `click <selector>` | Click an element |
|
|
| `type <selector> <text>` | Type text into an element |
|
|
| `press <key>` | Press a keyboard key |
|
|
| `wait <selector\|text\|ms>` | Wait for condition |
|
|
| `screenshot [path]` | Take a screenshot |
|
|
| `snapshot` | Get accessibility tree |
|
|
| `extract <selector>` | Get element HTML |
|
|
| `eval <script>` | Run JavaScript |
|
|
| `scroll <dir> [amount]` | Scroll page |
|
|
| `hover <selector>` | Hover over element |
|
|
| `select <selector> <val>` | Select dropdown option |
|
|
| `tab new` | Open new tab |
|
|
| `tab list` | List all tabs |
|
|
| `tab <index>` | Switch to tab |
|
|
| `tab close [index]` | Close tab |
|
|
| `window new` | Open new window |
|
|
| `session` | Show current session |
|
|
| `session list` | List active sessions |
|
|
| `close` | Close browser |
|
|
|
|
## Sessions
|
|
|
|
Sessions allow multiple agents to use veb simultaneously without interfering with each other. Each session runs its own isolated browser instance.
|
|
|
|
```bash
|
|
# Using --session flag
|
|
veb --session agent1 open https://site-a.com
|
|
veb --session agent2 open https://site-b.com
|
|
|
|
# Using environment variable
|
|
export VEB_SESSION=agent1
|
|
veb open https://example.com
|
|
veb click "#button"
|
|
|
|
# List all running sessions
|
|
veb session list
|
|
|
|
# Close a specific session
|
|
veb --session agent1 close
|
|
```
|
|
|
|
Sessions are identified by name. If no session is specified, the "default" session is used.
|
|
|
|
## Options
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `--session <name>` | Use isolated browser session |
|
|
| `--json` | Output raw JSON |
|
|
| `--full, -f` | Full page screenshot |
|
|
| `--text, -t` | Wait for text |
|
|
| `--selector, -s` | Target element |
|
|
| `--debug` | Show debug timing info |
|
|
| `--help, -h` | Show help |
|
|
|
|
## Selectors
|
|
|
|
veb supports all Playwright selectors:
|
|
|
|
- CSS: `#id`, `.class`, `div.container`
|
|
- Text: `text=Click me`, `"Click me"`
|
|
- XPath: `xpath=//button`
|
|
- Role: `role=button[name="Submit"]`
|
|
|
|
## License
|
|
|
|
MIT
|