| name | webcmd-browser |
| description | Use when an agent needs to drive a real Chrome window via webcmd — 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. Not for writing adapters — see webcmd-adapter-author for that. |
| allowed-tools | Bash(webcmd:*), Read, Edit, Write |
webcmd-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 ~/.webcmd/clis/<site>/ use webcmd-adapter-author instead.
Adapter fallback gate
Before starting a raw browser session, filter webcmd list -f json at the source using request-derived terms across site, name, description, and columns; follow webcmd-usage for the command shape. Any truncation warning means adapter discovery is incomplete: narrow the filter and inspect again. Absence from truncated output never proves that no adapter exists.
Raw webcmd browser use is allowed only after both conditions hold:
- The complete, non-truncated filtered registry result for the missing capability is exactly
[].
- A complete, non-truncated
webcmd plugin search <capability> -f json result returns no match and no error.
If plugin search returns a match, offer installation. If its output is truncated, refine the query or output and inspect again. If it errors, report the error and stop instead of opening the browser.
Prerequisites
webcmd doctor
Until doctor is green, browser commands will not work. Registry and plugin discovery do not require doctor. Typical failures: Chrome not running, extension not installed, debug port blocked by 1Password / other extensions. The doctor output tells you which.
Session lifecycle
webcmd 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:
webcmd browser fb-yaya-warmup open https://example.com, then reuse webcmd browser fb-yaya-warmup state, extract, click, etc.
- Owned browser sessions keep a tab lease alive between calls. Release it with
webcmd browser <session> close or let the idle timeout expire.
webcmd browser <session> bind --page <page-id> binds an existing webcmd-managed Cloak tab to that session. Use this after the user manually logs in or navigates inside a visible Cloak window.--window foreground|background (or WEBCMD_WINDOW=foreground|background) chooses whether Webcmd creates/focuses a foreground browser window or uses a background browser window for owned sessions.
Bind Tab
webcmd browser gmail tab list
webcmd browser gmail bind --page page-123
webcmd browser gmail state
webcmd browser gmail click "Search"
webcmd browser gmail network
webcmd browser gmail unbind
Binding is explicit: run tab list, choose the Cloak tab's page id or index, then bind that tab to the named session. It fails closed if the tab is closed or the page id/index is stale. Re-run webcmd browser <session> bind --page <page-id> when the user switches to a different Cloak tab.
Navigation is allowed on bound sessions because the session now represents explicit agent ownership of that Cloak tab. Tab mutation (tab new, tab select, tab close) works on webcmd-managed Cloak tabs.
Bound sessions use the normal Webcmd session lifecycle; unbind releases the Cloak session lease, and tab/window/daemon close also ends the binding.
Mental model
- 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.
- 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.
- 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.
- Structured errors are machine-readable. On failure the CLI emits
{error: {code, message, hint?, candidates?}}. Branch on code, not on message strings.
Critical rules
- 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.
- Prefer site adapters before raw browser driving. Complete the adapter fallback gate above. If
webcmd <site> <command> already covers the task, use that adapter command first (webcmd facebook notifications, webcmd reddit read, webcmd chatgpt model <level>, etc.). Use webcmd browser ... only for gaps, debugging, or one-off UI flows the adapter does not expose.
- 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.
- 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.
- 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>.
- 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.
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.- 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.
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.- 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 webcmd-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 webcmd-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
| 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...> [--role R --name N] [--nth N] | Attaches local file path(s) to an input[type=file] via CDP. With semantic flags, omit target and pass files as positionals. Returns {uploaded, files, file_names, target, matches_n, match_level, multiple?, accept?}. |
browser drag [source] [target] [--from-role R --from-name N] [--to-role R --to-name N] [--from-nth N] [--to-nth N] | Mouse-based drag from one resolved element center to another. Works for mouse-listener drag libraries; native HTML5 dataTransfer drops may need a site-specific fallback. Returns {dragged, source, target, source_matches_n, target_matches_n, ...}. |
browser type [target] <text> [--role R --name N] [--nth N] | Clicks first, then types. With semantic flags, omit target and pass text as the only positional. Returns {typed, text, target, matches_n, match_level, autocomplete}. autocomplete: true means a combobox/datalist popup appeared after typing — you almost always need keys Enter or a follow-up click on the suggestion to commit the value. |
browser fill [target] <text> [--role R --name N] [--nth N] | Exact replacement for input, textarea, and contenteditable targets. With semantic flags, omit target and pass text as the only positional. Returns {filled, verified, text, actual, matches_n, match_level}. Use this when you need raw text set and verified, not keyboard/autocomplete behavior. Pipeline form supports { fill: { ref, text, submit: true } }. |
browser select [target] <option> [--role R --name N] [--nth N] | Matches native <select> option by label first, then value. With semantic flags, omit target and pass option as the only positional. Use compound from find/state to see exactly what labels are available. |
browser keys <key> | Enter, Escape, Tab, Control+a, etc. Runs against the focused element. |
browser scroll <direction> [--amount px] | up / down. Default amount 500. |
Wait
browser wait selector "<css>" [--timeout ms]
browser wait text "<substring>" [--timeout ms]
browser wait download [pattern] [--timeout ms]
browser wait time <seconds>
Default timeout 10000 ms. SPA routes, login redirects, and lazy-loaded lists need wait before state/get.
browser wait download uses the CloakBrowser runtime download lifecycle. 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 webcmd 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
browser network --detail <key>
browser network --filter "field1,field2"
browser network --all
browser network --raw
browser network --ttl <ms>
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 ~/.webcmd/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
| command | purpose |
|---|
browser tab list | JSON array of {index, page, url, title, active}. The page string is the tab identity you pass as <targetId> to tab select / tab close, or to --tab <targetId> on any subcommand. (--tab's placeholder is historical — the value is always page.) |
browser tab new [url] | Open a new tab. Prints the new page string. |
browser tab select [targetId] | Make a tab the default. All subcommands accept --tab <targetId> to target one without changing the default. |
browser tab close [targetId] | Close by page. |
browser back | History back on the active tab. |
browser close | Release the current owned browser session when done. |
browser <session> bind --page <page-id> | Bind an existing Cloak tab to the named browser session. |
browser <session> bind --index <n> | Bind an existing Cloak tab by index from tab list. |
browser <session> unbind | Release the named Cloak browser session lease. |
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.
| command | rough cost | when to use |
|---|
state | medium (bounded by internal budget) | First call on any page, after every nav, when you need refs. |
find --css <sel> | small | You already know the selector — one query, compact entries. |
get title / get url | tiny | Sanity checks between steps. |
get text/value/attributes | tiny per call | Verifying one specific field. |
get html (raw) | can be huge | Avoid on unbounded pages. Always pair with --selector and a budget. |
get html --as json --depth 3 --children-max 20 | medium | When you need to reason about structure, not a specific field. |
screenshot | large | Only when the page is visual (CAPTCHA, charts). Prefer state. |
extract | medium per chunk | Long-form reading. Loop via next_start_char. |
network (default) | small | First look at APIs. |
network --detail <key> | varies | Pull one body. |
network --raw | huge | Only after --filter narrowed the candidate set. |
eval "JSON.stringify(...)" | controlled | Targeted extraction when none of the above fit. |
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:
webcmd browser hn open "https://news.ycombinator.com" \
&& webcmd browser hn state \
&& webcmd 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
webcmd browser login open "https://example.com/login"
webcmd browser login state
webcmd browser login type 4 "me@example.com"
webcmd browser login type 5 "hunter2"
webcmd browser login get value 4
webcmd browser login click 6
webcmd browser login wait selector "[data-testid=account-menu]" --timeout 15000
webcmd browser login state
Pick from a long dropdown
webcmd browser form state
webcmd browser form find --css "select[name=country]"
webcmd browser form select 12 "Uruguay"
webcmd browser form get value 12
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>.
webcmd browser mercury state
webcmd browser mercury state --source ax
webcmd browser mercury click 7
webcmd browser mercury state --source ax
webcmd browser mercury click 12
webcmd browser mercury get text 7
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:
webcmd 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
webcmd browser hn open "https://news.ycombinator.com"
webcmd browser hn network --filter "title,score"
webcmd browser hn network --detail topstories-a1b2
Read a long article in chunks
webcmd browser article open "https://blog.example.com/long-post"
webcmd browser article extract --chunk-size 8000
webcmd browser article extract --start 8000 --chunk-size 8000
Cross-origin iframe
webcmd browser checkout frames
webcmd 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
| symptom | fix |
|---|
webcmd doctor red: "Browser not connected" | Start Chrome with --remote-debugging-port=9222, or build the Webcmd Browser Bridge and load the repository's extension/ directory as an unpacked extension. |
attach failed: chrome-extension://... | Disable 1Password / other CDP-hungry extensions temporarily. |
selector_not_found right after state | Page mutated. wait selector "..." then retry. |
stale_ref across every command | You are reusing refs from a prior page. Re-state. |
click succeeds but nothing happens | The element is probably a decorative wrapper stealing clicks from the real target. find --css "..." with a narrower selector and retry on the inner element. |
type appears to finish but value is wrong | Autocomplete, masked input, or React controlled re-render. Verify with get value. Add keys Enter or re-type. |
webcmd list -f json output is truncated | Adapter discovery is incomplete. Filter at the source with request-derived terms and narrow until the complete result is []; do not start browser fallback yet. |
Giant get html output | Pass --selector + --as json --depth 3 --children-max 20 --text-max 200. |
| Network cache seems stale | Bump --ttl down, or let it expire. The cache lives at ~/.webcmd/cache/browser-network/. |
See also
webcmd-adapter-author — turning what you just figured out into a reusable ~/.webcmd/clis/<site>/<command>.js.webcmd-browser-sitemap — consuming site sitemap context while driving a browser task.webcmd-sitemap-author — creating or updating sitemap knowledge when you discover a durable path or stale entry.webcmd-autofix — when an existing adapter breaks, this skill walks you through --trace retain-on-failure evidence and filing a fix.
