bunwv

Headless browser automation using a persistent WebView session. The daemon keeps a single WebView instance alive so page state (DOM, modals, forms, SPA routes, scroll position) persists across commands.

Agent-first usage patterns

bunwv is designed for AI agents driving it via discrete tool calls. A few contracts to rely on:

• Successful verbs print nothing on stdout and exit 0. click, type, navigate, press, scroll, scroll-to, clear, submit, resize, back/forward/reload, close, exists, wait-for, wait-for-gone, cdp-subscribe, cdp-unsubscribe all follow this. Read verbs (status, evaluate, events, console, cdp, cdp-subscriptions, screenshot, sessions) print their result.
• Errors are JSON on stderr with a stable exit code. Branch on exit code, not stderr text:
  • 0 ok, 1 generic, 2 usage, 3 timeout, 4 element-not-found, 5 daemon-unreachable, 6 batch-partial (only in batch --keep-going).
• console.error/console.warn auto-surface during verbs. If the page logs an error while a verb runs, bunwv prints {"console":[…]} to stderr. You see the failure without a second call.
• Cursor-pull for events. events --since <seq> returns entries newer than the cursor plus a new cursor. Keep the cursor across turns; refetch after actions. If the buffer evicted older entries, the response includes "truncated":true,"oldest":<seq>.
• File paths for binary output. bunwv screenshot writes bytes to /tmp/bunwv-screenshot-<session>.png by default and prints the path on stdout. Use the Read tool on that path to see the image.
• --json for uniform envelopes. Any command with --json returns {ok, data?, error?, exitCode} as a single JSON line. Use it when you prefer one shape over terse output.
• Flexible flag syntax. --flag value, --flag=value, and repeated flags (e.g. --mod Shift --mod Control) all work. Flags may appear before or after the command: bunwv --json status and bunwv status --json are equivalent.
• BUNWV_SESSION env var — set it once and --session becomes optional.

Commands