Opencli Browser

opencli-browser

The first reader of this CLI is an agent, not a human. Every subcommand returns a structured envelope that tells you exactly what matched, how confident the match is, and what to do if it didn't. Lean on those envelopes — do not guess.

This skill is for driving a live browser to accomplish an agent task. If you are building a reusable adapter under ~/.opencli/clis/<site>/ use opencli-adapter-author instead.

---

Prerequisites

opencli doctor

Until doctor is green, nothing else will work. Typical failures: Chrome not running, extension not installed, debug port blocked by 1Password / other extensions. The doctor output tells you which.

---

Session lifecycle

• opencli browser * commands require a <session> positional immediately after browser. Use the same session name for a multi-step flow; use a different name to isolate parallel browser work.
• Use a stable session name for any multi-command or human-paced browser workflow. Example: opencli browser fb-yaya-warmup open https://example.com, then reuse opencli browser fb-yaya-warmup state, extract, click, etc.
• Owned browser sessions keep a tab lease alive between calls. Release it with opencli browser <session> close or let the idle timeout expire.
• opencli browser <session> bind binds the Chrome tab you already have open to that session. Use this for logged-in pages, SSO flows, or pages you manually positioned before handing control to the agent.
• --window foreground|background (or OPENCLI_WINDOW=foreground|background) chooses whether OpenCLI creates/focuses a foreground browser window or uses a background browser window for owned sessions.

Bind Tab

opencli browser gmail bind
opencli browser gmail state
opencli browser gmail click "Search"
opencli browser gmail network
opencli browser gmail unbind

Binding never owns the user window and never closes the user tab. It fails closed if the tab is closed or becomes non-debuggable. Re-run opencli browser <session> bind when you switch to a different real tab.

Navigation is allowed on bound sessions because the session now represents explicit agent ownership of that tab. Tab mutation (tab new, tab select, tab close) is still blocked for bound sessions. Use an owned session when you want OpenCLI to manage tab lifecycle.

Bound sessions have no OpenCLI idle-close timer; the binding lasts until unbind, tab close, window close, or daemon restart.

---

Mental model

1. Selector-first target contract. Every interaction command (click, type, select, get text/value/attributes) takes one <target>, which is either a numeric ref from state/find or a CSS selector. Use --nth <n> to disambiguate multiple CSS matches. 2. Every envelope reports `matches_n` and `match_level`. match_level is exact, stable, or reidentified — the CLI already rescued moderate DOM drift for you, but the level tells you how confident to be. 3. Compact output first, full payload on demand. state is a budget-aware snapshot; get html --as json supports --depth/--children-max/--text-max; network returns shape previews and you re-fetch a single body with --detail <key>. If you emit a giant payload you are burning context you did not need to burn. 4. Structured errors are machine-readable. On failure the CLI emits {error: {code, message, hint?, candidates?}}. Branch on code, not on message strings.

---

Critical rules

1. Always inspect before you act. Run state or find first. Never hard-code a ref or selector from memory across sessions — indices are per-snapshot. 2. Prefer site adapters before raw browser driving. If opencli <site> <command> already covers the task, use that adapter command first (opencli facebook notifications, opencli reddit read, etc.). Use opencli browser ... only for gaps, debugging, or one-off UI flows the adapter does not expose. 3. Prefer numeric ref over CSS once you have it. Numeric refs survive mild DOM shifts because the CLI fingerprints each tagged element. A CSS selector written by hand will break the first time the site re-renders. 4. Read `match_level` after every write. exact = all good. stable = the element is the same but some soft attrs drifted — your action still applied. reidentified = the original ref was gone and the CLI found a unique replacement; double-check you hit the right element. 5. Use the `compound` field for form controls. Do not regex-guess a date format, do not state twice to get the full <select> options list. The compound envelope has the format string, full option list up to 50, options_total for overflow, and accept/multiple for <input type=file>. 6. Verify writes that matter. After type <target> <text>, run get value <target>. After select, run get value. Autocomplete widgets, React controlled inputs, and masked fields all silently eat characters. The CLI cannot detect this for you. 7. `state` → action → `state` after a page change. Navigations, form submits, and SPA route changes invalidate refs. Take a fresh snapshot. Do not reuse refs from before the transition. 8. Chain with `&&` when reusing freshly parsed refs. A chained sequence runs in one shell so the ref you just read from output can be passed directly to the next command. Separate shell invocations keep the named browser session, but any shell-local variables or copied refs from the previous command can go stale after page changes. 9. `eval` is read-only. Wrap the JS in an IIFE and return JSON. If you need to change the page, use the structured click / type / select / keys commands instead — they produce structured output and fingerprints, eval does not. 10. Prefer `network` to screen-scraping. If a page you care about fetches its data from a JSON API, the API is almost always more reliable than scraping the rendered DOM. Capture once, inspect the shape, then --detail <key> the body you need.

---

Sitemaps

If browser open or browser analyze returns sitemap.available: true, switch to opencli-browser-sitemap before continuing a multi-step site flow. The sitemap is prior context for pages, actions, workflows, APIs, and pitfalls; it is not truth. If the browser state disagrees with the sitemap, trust the browser and mark the sitemap stale via opencli-sitemap-author.

---

Target contract (<target> for click / type / select / get text|value|attributes)

<target> ::= <numeric-ref> | <css-selector>

• Numeric ref — the [N] index from state or find. Cheap, resilient to soft DOM drift.
• CSS selector — anything querySelectorAll accepts. Must be unambiguous on write ops, or pair with --nth <n>.

Envelope on success

{ "clicked": true, "target": "3", "matches_n": 1, "match_level": "exact" }

{ "value": "kalevin@example.com", "matches_n": 1, "match_level": "stable" }

match_level

Structured error codes

Branch on these, not on the human message:

Error envelope always includes error.code and error.message. Target errors (selector_not_found, selector_ambiguous, etc.) often add error.candidates: string[] with suggested selectors. option_not_found adds error.available: string[] instead.

---

Command reference

Inspect

Get (read-only)

Interact

Wait

browser wait selector "<css>" [--timeout ms]    # wait until the selector matches
browser wait text "<substring>" [--timeout ms]  # wait until the text appears
browser wait download [pattern] [--timeout ms]  # wait for a Chrome download whose filename/URL/mime contains pattern
browser wait time <seconds>                     # hard sleep, last resort

Default timeout 10000 ms. SPA routes, login redirects, and lazy-loaded lists need wait before state/get.

browser wait download requires Browser Bridge extension 1.0.8+ because it uses Chrome's downloads lifecycle API. Pass a narrow filename or URL substring such as receipt.pdf when possible; an empty pattern waits for the next/recent download in the timeout window. The command reports {downloaded, filename, url, state, elapsedMs} on success and a JSON error envelope on timeout/failure.

Extract

• `web read --url <url>` — One-shot Markdown reader for arbitrary pages. It expands relevant same-origin iframes by default, so old iframe-shell sites work better than with a top-document-only scrape. Use --frames all-same-origin when completeness matters more than Markdown noise. For AJAX shell pages use opencli web read --url <url> --wait-for "<selector>" --wait-until networkidle --diagnose; diagnostics show frame URLs, empty containers, and API-like XHRs. If the value you need is table/API data, switch to browser network or a dedicated adapter instead of relying on Markdown.
• `browser eval <js> [--frame N]` — Run an expression in the page (or in a cross-origin frame via --frame). Wrap in an IIFE and return JSON. Read-only: no document.forms[0].submit(), no clicks, no navigations. If the result is a string, stdout is the raw string; otherwise it's JSON.
• `browser extract [--selector <css>] [--chunk-size N] [--start N]` — Markdown extraction of long-form content with a continuation cursor. Returns {url, title, selector, total_chars, chunk_size, start, end, next_start_char, content}. Loop on next_start_char until it is null. Auto-scopes to <main>/<article>/<body> if you don't pass --selector.

Network

browser network                        # shape preview + cache key list
browser network --detail <key>         # full body for one cached entry
browser network --filter "field1,field2"  # keep only entries whose body shape contains ALL fields as path segments
browser network --all                  # include static resources (usually noise)
browser network --raw                  # full bodies inline — large; use sparingly
browser network --ttl <ms>             # cache TTL (default 24h)

List entries look like {key, method, status, url, ct, size, shape, body_truncated?}. Detail envelope is {key, url, method, status, ct, size, shape, body, body_truncated?, body_full_size?, body_truncation_reason}. Cache lives in ~/.opencli/cache/browser-network/ so you can re-inspect without re-triggering the request.

Default output keeps JSON/XML/plain-text and JS-like API responses, then drops obvious static assets and telemetry by URL. If an expected endpoint is missing, run browser network --all once and check whether an unusual content type or URL filter hid it.

Tabs & session

---

Compound form controls

Every date/time, select, and file input carries a compound field. Use it — do not regex attributes.

Date family

{
  "control": "date",
  "format": "YYYY-MM-DD",
  "current": "2026-04-21",
  "min": "2026-01-01",
  "max": "2026-12-31"
}

control is one of date | time | datetime-local | month | week. format is a concrete template string — type into the field using that exact format, or select by label if the site wraps the native input in a custom widget.

Select

{
  "control": "select",
  "multiple": false,
  "current": "United States",
  "options": [
    { "label": "United States", "value": "us", "selected": true },
    { "label": "Canada", "value": "ca" }
  ],
  "options_total": 137
}

options[] is capped at 50 entries. `current` is always correct even when the selected option is past the cap — it's computed by scanning every option, not from the truncated list. If options_total > options.length and you need an option that isn't in options[], call browser select <target> "<label>" directly — the CLI matches against the live DOM, not the truncated list.

File

{
  "control": "file",
  "multiple": true,
  "current": ["report.pdf", "cover.png"],
  "accept": "application/pdf,image/*"
}

Do not invent file paths. Upload is done via the normal click flow — respect accept when telling the user what to upload.

Where compounds show up

• browser find --css <sel> entries: inline on each match.
• browser get html --as json tree nodes: inline on matching nodes.
• browser state snapshot: in a compounds (N): sidecar keyed by numeric ref, so you can tell at a glance which [N] entries have rich metadata.

---

Cost guide

Think about payload size per call. Budgets exist for a reason.

Rule of thumb: one `state` per page transition, one `find` per follow-up query, one `get`/`click`/`type` per action. If your plan involves >10 calls per page you are probably scraping instead of interacting — consider extract or network.

---

Chaining rules

Good — one shell, live session:

opencli browser hn open "https://news.ycombinator.com" \
  && opencli browser hn state \
  && opencli browser hn click 3

Bad — each line is a fresh shell, refs from call 1 are already forgotten when call 2 runs. (Only a problem if you rely on shell-scoped state; browser refs themselves persist in-page, but interleaving unrelated shells invites races.) Prefer && when the steps are meant to be atomic.

Never chain a write and then an immediate state without a wait if the action causes a network round-trip — you will snapshot the pre-response DOM and make bad decisions off stale data.

---

Recipes

Fill a login form

opencli browser login open "https://example.com/login"
opencli browser login state                          # find [N] for email, password, submit
opencli browser login type 4 "me@example.com"
opencli browser login type 5 "hunter2"
opencli browser login get value 4                    # verify (autocomplete can eat chars)
opencli browser login click 6                        # submit
opencli browser login wait selector "[data-testid=account-menu]" --timeout 15000
opencli browser login state                          # fresh refs on the logged-in page

Pick from a long dropdown

opencli browser form state                          # sidebar shows [12] <select name=country>
opencli browser form find --css "select[name=country]"
# the compound.options_total is 137, but compound.current is "" — unselected.
opencli browser form select 12 "Uruguay"
opencli browser form get value 12                   # { value: "uy", match_level: "exact" }

Pick from a custom React dropdown

Use this for Radix, shadcn, Material UI, Mercury-style category fields, and other controls that are not native <select>.

opencli browser mercury state                          # find category trigger ref
# If the trigger/option is not clear, use AX:
opencli browser mercury state --source ax              # look for combobox/button/listbox/option names
opencli browser mercury click 7                        # click category trigger
opencli browser mercury state --source ax              # fresh refs after the portal/listbox opens
opencli browser mercury click 12                       # click option
opencli browser mercury get text 7                     # verify visible selected label

Do not use browser select on these widgets. browser select is only for native <select> elements. Custom dropdowns should be driven with state -> click trigger -> state -> click option -> verify.

Compare DOM vs AX observation

When deciding whether AX refs are better for a page, collect metrics without sharing page contents:

opencli browser compare state --compare-sources

Report sources.dom.refs, sources.ax.refs, frame_sections, approx_tokens, elapsed_ms, and any per-source error. Use this before arguing that AX should become the default on a site.

Scrape a list via network instead of DOM

opencli browser hn open "https://news.ycombinator.com"
opencli browser hn network --filter "title,score"
# -> find the /topstories entry, note its key
opencli browser hn network --detail topstories-a1b2

Read a long article in chunks

opencli browser article open "https://blog.example.com/long-post"
opencli browser article extract --chunk-size 8000
# -> content + next_start_char: 8000
opencli browser article extract --start 8000 --chunk-size 8000
# ...until next_start_char is null

Cross-origin iframe

opencli browser checkout frames
# -> [{"index": 0, "url": "https://checkout.stripe.com/...", ...}]
opencli browser checkout eval "(() => document.querySelector('input[name=cardnumber]')?.value)()" --frame 0

browser state --source ax may omit cross-origin iframe contents or fail to route actions into them when Chrome does not expose an attachable OOPIF target to the extension. In that case use browser frames + browser eval --frame, a normal DOM state, or navigate/bind directly to the iframe URL when possible.

---

Pitfalls

• Do not submit forms via `eval "document.forms[0].submit()"` — modern sites intercept with JS handlers and silently drop the call. Either click the submit button via its ref, or (if you know the GET URL) just open it directly.
• Do not reuse refs across a page transition. wait for the new state, then re-state. Old refs will either 404 or (worse) reidentify onto a similarly-shaped element on the new page.
• `match_level: reidentified` is a warning, not an error. The action went through, but if you are chaining 5 more writes that all depend on that being the right element, verify with a get text or get value before continuing.
• Budget-aware commands silently cap. get html --as json with default budgets will return truncated: {...}. If your downstream logic needs the whole subtree, raise --depth / --children-max or tighten the selector.
• `autocomplete: true` on a `type` response is not an error. It means a suggestion popup is open and your value isn't committed yet. Typically keys Enter to accept the first suggestion, or click the one you want.
• `network --filter` is AND-semantics on path segments. --filter "title,score" keeps entries whose body shape contains both title and score as path segments, at any depth. It is not a regex.
• Screenshots are for humans, not for agents. Use state + find unless the page is genuinely visual (captcha, chart). Screenshots burn tokens and rarely add signal an agent can act on.

---

Troubleshooting

---

See also

• opencli-adapter-author — turning what you just figured out into a reusable ~/.opencli/clis/<site>/<command>.js.
• opencli-browser-sitemap — consuming site sitemap context while driving a browser task.
• opencli-sitemap-author — creating or updating sitemap knowledge when you discover a durable path or stale entry.
• opencli-autofix — when an existing adapter breaks, this skill walks you through --trace retain-on-failure evidence and filing a fix.