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.

Browser tools for agents Use the capability that fits the task. Discover commands with opencli list <query ; read exact arguments with opencli browser <command help f json . Run opencli doctor when diagnosing a connection problem. Scope and results Page commands require session <name . Reuse that name across a task; different sessions isolate page work. profile <name selects a Chrome profile when needed. Options can follow command arguments: Default output is one JSON value: { "ok": true, "data": ... } . Failures return { "ok": false, "error": { "code": "...", "message": "...", "hint": "..." } } and a nonzero exit code. Diagnostic logs go to stderr. network follow and console follow stream one envelope per line. Help, version and shell completion are inspection/export surfaces; structured help uses help f json . Read the returned data and error fields. When error.outcome is unknown , inspect the affected state before retrying a write. Page targets and interaction state returns URL and interactive element refs. diagnostics also reports page title and available initial state globals; source ax selects the AX tree. find locates elements. Interaction targets accept a ref, CSS selector, or semantic flags such as role , name , label , text , testid . Use nth to resolve deliberate multiple matches. On stale refs, read fresh state or locate the element again; refs describe the observed page. fill replaces a field and verifies its value; type types text. Other actions include click , select , check , upload , drag , keys and dialog . get text value attributes html , extract , screenshot and eval expose page data. eval executes JavaScript in the page and can mutate state. wait xhr selector text download observes an expected condition. Consult help for timeouts and matching rules. tab list new select close manages session tabs. tab accepts the page identity returned by these commands; these are different from numeric native Chrome IDs. frames lists frame targets; eval frame evaluates in a selected frame. bind session research attaches the current user tab. Bound sessions permit navigation but block tab creation, selection and closure. unbind releases the binding without closing the user tab. Owned sessions keep leased tabs until close or idle expiry. window foreground background controls owned windows. Network and scripts network returns captured request keys and response shapes. detail reads a cached request; filter selects shapes; raw exposes response bodies. static adds Acorn AST candidates from loaded scripts, with source locations, methods, query/body parameter names and observed request evidence. EXPR means an unresolved expression. Static candidates are not executed or proven APIs. Check analysisComplete , script errors, omitted scripts and networkSource . An empty live capture can reuse a recent cache; reported provenance distinguishes it. Native Chrome management Native calls need no session and do not attach a page: Use numeric IDs returned by Chrome, replacing the example IDs. describe lists supported methods, signatures, live permissions and official documentation. Native created tabs/windows persist. Mutations touching active OpenCLI session tabs or managed groups return managed resource conflict ; ordinary groups can be created, renamed, recolored, moved and dissolved with tabs.ungroup .

opencli-browser