Browser automation

Drive Chromium with @eN refs — navigate, click, fill, tabs, network, login, CAPTCHA.

omniscout browser controls your browser. The core loop never changes:

omniscout browser navigate https://example.com   # 1. open a page
omniscout browser snapshot --refs-only           # 2. list @eN element refs
omniscout browser click '@e3'                    # 3. act on a ref
omniscout browser check '@e4'                     # set a checkbox or switch on
omniscout browser uncheck '@e5'                   # set it off
omniscout browser screenshot --out /tmp/out.png  # 4. capture state

Where pages open

By default, pages open in a managed background window — clean, separate from your own browsing. To open pages in your own browser instead, where you stay logged in and pick up where you left off, switch modes:

omniscout settings set browser-automation headful    # your own browser
omniscout settings set browser-automation headless   # managed window (default)

Append --headful or --headless to any single command to override the default just once.

The `@eN` ref model

snapshot lists the elements you can act on (@e1, @e2, …). Every interaction targets a ref. Two rules:

Re-snapshot after every navigation or major page change — refs go stale when the page changes.
Prefer --refs-only for a flat actionable list; drop it for the full tree when you need hierarchy.

omniscout browser snapshot --refs-only
omniscout browser snapshot --overlay   # draw @e labels on the page (debugging/demos)

omniscout browser navigate https://example.com --wait-until domcontentloaded
omniscout browser open https://example.com      # alias of navigate
omniscout browser back
omniscout browser forward
omniscout browser reload
omniscout browser get url                       # current URL
omniscout browser get title                     # page title

navigate accepts --profile (persistent login context), --session (tab group), --new-tab, --headful/--headless, --auto-captcha, and --wait-until. See Daemon & sessions for profiles vs sessions.

By default, the first navigation in a session opens a new tab; later navigations reuse that tab so multi-step flows (checkout, forms) stay on one page. Use --reuse-tab on the first open, or omniscout settings set open_new_tab false, to change that default.

Clicking, typing, selecting

Action	Command	Notes
Click	`browser click '@e3'`	`--button`, `--clicks`, `--mod`, or `--coord x y` for vision agents
Fill (replace)	`browser fill '@e5' "text"`	Replaces existing content
Type (append)	`browser type '@e5' "text"`	Appends; `--delay-ms` between keystrokes
Paste	`browser paste '@e5' "text"`	Inserts at cursor without clearing
Select	`browser select '@e5' "option"`	Native `<select>` elements
Keys	`browser key Enter`	Combos like `cmd+s`, `ctrl+c`
Hover	`browser hover '@e7'`	Or `--coord x y`
Checkbox or switch	`browser check '@e8'` / `browser uncheck '@e8'`	Sets the requested state in Playwright and CDP sessions
Upload	`browser upload '@e9' file.pdf`	Attaches files to `<input type=file>`
Scroll	`browser scroll down`	Page or element, with `--amount`
Check state	`browser is '@e3' visible`	Visibility, enabled, checked, …

fill vs type vs paste: fill clears first (forms), type appends like a human (chats, editors), paste drops text at the cursor (large blobs).

Reading the page

omniscout browser get text              # visible body text
omniscout browser get html              # page HTML (truncated ~500KB)
omniscout browser eval "document.title" # run JavaScript, return the value
omniscout browser extract-visible       # visible text, optional --schema shaping

Waiting

Never sleep blindly — wait for the condition you actually need:

omniscout browser wait text "Order confirmed"
omniscout browser wait selector "#results"
omniscout browser wait networkidle
omniscout browser wait url "*checkout*"
omniscout browser wait --ms 2000 --timeout-ms 30000

wait also supports --ref, --url (match on current URL), and --idle.

Tabs

omniscout browser navigate https://a.com --session multi
omniscout browser navigate https://b.com --new-tab --session multi
omniscout browser tab list --session multi
omniscout browser tab switch 0 --session multi
omniscout browser tab close 1 --session multi

Network & console capture

omniscout browser network start
omniscout browser navigate https://vercel.com/pricing
omniscout browser scroll down --amount 10
omniscout browser network stop
omniscout browser network list --filter "stripe|payment"
omniscout browser network detail 3          # full payload for one entry
omniscout browser network tail              # only entries since last tail

omniscout browser console start
omniscout browser console tail              # JS errors and console messages
omniscout browser console list
omniscout browser console stop

Natural-language actions

For fuzzy targets, let OmniScout resolve them:

omniscout browser observe "the search box"        # find candidate refs
omniscout browser act "click the top story"       # resolve + act
omniscout browser act "search box" --value "local-first agents"
omniscout browser act "submit" --dry-run          # resolve without acting

Verify with a snapshot afterwards — act is convenient but refs are deterministic.

Screenshots, PDFs, mouse

omniscout browser screenshot --out /tmp/page.png
omniscout browser screenshot --full-page --out /tmp/full.png   # top-to-bottom
omniscout browser screenshot --stitched --out /tmp/stitched.png  # scroll + stitch (PNG)
omniscout browser screenshot --ref '@e3' --out /tmp/el.png     # one element
omniscout browser screenshot --ref '#hero' --out /tmp/hero.png # element by CSS selector
omniscout browser screenshot --region 0,200,1280,800 --out /tmp/mid.png  # pixel rectangle
omniscout browser screenshot --delay 2.5 --out /tmp/late.png  # wait for animations
omniscout browser pdf --out /tmp/page.pdf --paper letter
omniscout browser mouse move 400 300
omniscout browser mouse scroll 400 300

Some sites need a human login once. Open a headful window, authenticate, then signal completion from another shell — the profile keeps the cookies for reuse:

# Terminal A (blocks):
omniscout browser login https://github.com/login --profile work

# Terminal B (after you log in):
omniscout browser login --done

# Reuse later:
omniscout browser navigate https://github.com/notifications --profile work

--success-pattern (URL regex) auto-resolves the login; --timeout-ms defaults to 5 minutes. For CAPTCHAs:

omniscout browser captcha --detect-only                    # just report
omniscout browser captcha --solver 2captcha                # none | 2captcha | capsolver | manual
export CAPTCHA_API_KEY=...                                 # or --api-key

navigate also accepts --auto-captcha to resolve challenges right after load.

Cleanup

omniscout browser close                # close the default session
omniscout browser close --all          # close everything

Agent tips

Always snapshot before acting; never reuse refs across navigations.
End every run with browser close --all so the next run starts clean.
Use --session to isolate parallel workflows.
Under --json, pipe snapshots through jq: omniscout browser snapshot | jq '.refs[] | select(.role == "button")'.