click, fill, hover, keypress, scroll, drag, wait-for, dialog, screenshot, bounds, and tabs. Most commands target a numeric probe ID from sightmap snapshot or a component query, a CSS-shaped expression that matches Sightmap component names and properties.
All commands on this page except
tabs subcommands resolve a session with --addr (default localhost:7892) and --tab. Pass --tab whenever two or more content tabs are open. Session lifecycle commands are documented under Browser sessions.Component queries
Probe IDs belong to one extraction. A later extraction reassigns them, and a page re-render can replace the target node. Component queries reduce that risk by extracting the live tree and applying the corpus immediately before acting. Prefer queries on pages that re-render often. Queries match component names and extracted property values, not DOM selectors:
The only predicate operators are
= (exact), ^= (prefix), and *= (substring). Quote values that contain spaces. --sightmap-dir (default .sightmap) selects the corpus that resolves the query.
A query that matches zero or several components returns an error. For an ambiguous query, the CLI lists each candidate and its properties so you can add a predicate or #N index:
browser click
Clicks an element. The target is a probe ID, a component query, or raw --x and --y coordinates. Before dispatching, it scrolls the target to the center of the viewport and verifies that its center is the top-most element there. It errors instead of silently doing nothing when the target cannot be positioned in the viewport, or is covered by another element (an open overlay or modal). On success it echoes a confirmation with the real post-scroll coordinates, e.g. clicked CartNavButton @ (674,30). A click may trigger navigation that settles after the command returns (client-side SPA routing is asynchronous); click does not wait for it. Follow an action that should navigate with an explicit wait-for on the destination — the same act-then-wait split Playwright and Selenium use. (--x/--y coordinate clicks skip the scroll-and-verify step.)
browser fill
Types a value into an input. Takes two positionals: the target (probe ID or component query) and the value. After typing it reads the value back and errors when a non-empty value was typed but the field is still empty — the signature of a React-controlled input where plain typing doesn’t stick; retry with --clear, which clears via the native value setter first. On success it echoes filled TARGET = "value" to stderr.
browser hover
Moves the pointer over an element, such as a menu or tooltip trigger. It accepts the same targets as click: a probe ID, component query, or --x and --y. On success it echoes a confirmation to stderr.
browser keypress
Sends a key event to the focused element. Click or fill a field first when it needs focus. The key name is a positional argument, such as Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, or Space. On success it echoes pressed KEY to stderr.
browser scroll
Scrolls the page by pixel deltas, scrolls a component into view, or does both. When both are set, --component-id brings the target into view before applying the deltas. On success it echoes what it scrolled to stderr.
browser drag
Drags an element by pixel deltas. The target is a positional probe ID from snapshot output; this command does not accept component queries. On success it echoes dragged TARGET by (dx,dy) to stderr.
browser wait-for
Waits for exactly one condition. It is the explicit step boundary after an action that triggers navigation or asynchronous rendering: act, then wait-for the postcondition. On success it echoes what it matched to stderr; on timeout it exits 1 with a message like wait-for: timed out after 10000ms waiting for selector "...".
The semantic conditions are corpus-aware and auto-retry until they hold: --view waits until the current URL resolves to a named sightmap view, and --component waits until a component query (name plus optional property filters, e.g. WorkItemRow[key="FALCON-7"]) matches at least one node on the live page. --url (a plain URL substring, not a glob or regex), --selector, and --load are the raw DOM/URL escape hatches — prefer --view/--component when the destination is in the corpus, since they absorb dynamic path segments and wait for real rendered content rather than a URL proxy.
browser dialog
Resolves a blocking JavaScript dialog (alert, confirm, prompt). The action is a positional argument: accept or dismiss. On success it echoes accepted dialog / dismissed dialog to stderr; when no dialog is open it reports that clearly instead of surfacing a raw CDP error.
browser screenshot
Captures the current viewport as a PNG. If the PNG attempt times out, the command retries as JPEG unless you pass --no-retry. Pass --component or --selector to clip the capture to a single element’s bounding box instead of the whole viewport.
browser bounds reports); an off-screen target errors with no in-viewport match to clip to.
browser bounds
Prints bounding boxes as JSON, with viewport percentages and raw pixels. Query by positional component names, by raw CSS selector, or use --all for every matched component. Component-name lookup is exact and case-insensitive by default; it does not use the component-query language. The command skips offscreen matches unless you pass --include-offscreen.
browser tabs
Tab management for the session. browser start prints your tab’s ID; tabs list shows every open content tab.
Typical flow
1
Read the page
sightmap snapshot prints component names, extracted properties, and probe IDs (Capturing pages).2
Act by identity
Use a component query, such as
browser click 'ProductCard[name^="Weber"] AddToCartButton' or browser fill --clear SearchInput 'garden hose'.3
Wait for the result
browser wait-for --url '/cart' (or --selector/--load) before the next action.4
Verify
Run another snapshot to read the new state. To inspect it visually, run
browser screenshot --out after.png and use browser bounds to locate components.