Use when an agent needs to drive a real Chrome window via opencli — inspect a page, fill forms, click through logged-in flows, or extract data ad-hoc. Covers the selector-first target contract, compound form fields, stale-ref handling, network capture, and the agent-native envelopes the CLI returns.

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 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 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 , opencli chatgpt model <level , 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) 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 match level level meaning you should exact Fingerprint agreed on tag + strong IDs with at most one soft drift Proceed. stable Tag + strong IDs still agree, soft signals (aria label, role, text) drifted Proceed, but if what you typed/clicked matters, re check with get value or state . reidentified Original ref was gone; a unique live element matched the fingerprint and was re tagged with the old ref Double check you hit the right element before chaining more writes. Structured error codes Branch on these, not on the human message: code meaning not found Numeric ref is no longer in the DOM. Re state . stale ref Ref exists but the element at that ref changed identity. Re state . invalid selector CSS was rejected by querySelectorAll . Fix the selector. selector not found CSS matches 0 elements. Try find with a looser selector. selector ambiguous CSS matches 1 and no nth . Add nth or narrow the selector. selector nth out of range nth beyond match count. option not found select couldn't find an option matching that label/value. Error envelope includes available: string[] of the real option labels. not a select select was called on a non <select element. 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 command purpose browser state Snapshot: text tree with [N] refs, scroll hints, hidden interactive hints, compounds (N): sidecar for date/select/file refs. browser state source ax Opt in accessibility tree snapshot. Use when custom controls, portals, or iframe contents are hard to identify in normal state . AX refs can recover stale React re renders by role/name/nth and can route same origin iframe refs. Cross origin iframe refs are best effort because Chrome may not expose attachable OOPIF targets to extensions. browser state compare sources Metrics only DOM vs AX comparison for deciding whether AX should become default. It prints counts and sizes, not page text, so it is safer to share for validation. browser find css <sel [ limit N] [ text max N] Run a CSS query and return one entry per match with {nth, ref, tag, role, text, attrs, visible, compound?} . Allocates refs for matches the prior snapshot didn't tag. Cheap alternative to state when you already know the selector. browser find role button name Save Semantic locator query. Also supports label , text , and testid . Use before raw CSS when a control has accessible labels. browser frames List cross origin iframe targets. Pass the index to frame on eval . browser screenshot [path] Viewport PNG. No path → base64 to stdout. Prefer state when you just need structure. browser screenshot annotate [path] Visual ref map. Refreshes DOM refs and overlays visible [N] labels so the screenshot maps back to browser click <ref targets. Use for icon only controls, visual layouts, charts, or when text state is ambiguous. Get (read only) command returns browser get title plain text browser get url plain text browser get text <target [ nth N] {value, matches n, match level} browser get value <target [ nth N] {value, matches n, match level} browser get attributes <target [ nth N] {value: {attr: val, ...}, matches n, match level} browser get text role option name Travel Semantic locator read without a prior state call. Same flags as browser find . browser get html [ selector <css ] [ as html\ json] [ depth N] [ children max N] [ text max N] [ max N] Raw HTML, or structured tree. JSON tree nodes have {tag, attrs, text, children[], compound?} . Truncation reported via truncated: {depth?, children dropped?, text truncated?} . Interact command notes browser click <target [ nth N] Returns {clicked, target, matches n, match level} . browser click role button name Submit Semantic click. Write actions require a unique match; ambiguous locators return candidates instead of clicking the first match. browser hover [target] [ role R name N] [ nth N] Moves the mouse over an element. Use for hover menus/tooltips before taking state or clicking submenu items. Returns {hovered, target, matches n, match level} . browser focus [target] [ role R name N] [ nth N] Focuses an element without typing. Useful before keys or when a page reacts to focus/blur. Returns {focused, target, matches n, match level} . browser dblclick [target] [ role R name N] [ nth N] Double clicks an element via native mouse events when available. Returns {dblclicked, target, matches n, match level} . browser check [target] [ role R name N] [ nth N] Ensures checkbox/radio/aria checked control is checked. Returns {checked, changed, target, matches n, match level, kind} . Prefer this over blind click when target state matters. browser uncheck [target] [ role R name N] [ nth N] Ensures checkbox/aria checked control is unchecked. Radio buttons cannot be unchecked directly; select another radio in the group instead. browser upload [target] <file...

opencli-browser