Core Usage

Most of the time the @ref you get from snapshot is all you need. But sometimes a ref goes stale, the target is buried in a hidden state, or you simply don't want to snapshot first. This page covers the other ways to lock onto a target — the find semantic locators, raw CSS, coordinate clicks — plus the ladder that escalates to eval when structured locating runs out.

When not to use @ref

@ref is the fastest path, but it is built on top of each snapshot and expires the moment the page changes. In the situations below, reaching straight for a semantic locator or CSS is less work:

• The page is simple, and running a separate snapshot just to locate one button isn't worth it;
• refs keep going stale (after navigation, form submission, or a dynamic re-render);
• you already know the element's role, visible text, label, or a stable selector.

find semantic locators

find locates elements by semantics instead of a ref: role + name, visible text, form label, placeholder, data-testid, or "first / Nth" match. On a hit, chain an action verb directly (click / fill / type / hover …). find label matches more than <label> elements — it also matches aria-label and aria-labelledby, so icon buttons and custom controls labeled only via ARIA can be found too.

$ chrome-use find role button click --name "Submit"
$ chrome-use find text "Sign In" click
$ chrome-use find text "Sign In" click --exact     # exact match only
$ chrome-use find label "Email" fill "user@test.com"
$ chrome-use find label "Close" click            # hits an icon button with only aria-label="Close"
$ chrome-use find placeholder "Search" type "query"
$ chrome-use find testid "submit-btn" click
$ chrome-use find first ".card" click
$ chrome-use find nth 2 ".card" hover

Raw CSS selectors

Any action verb can take a CSS selector directly, no find required:

$ chrome-use click "#submit"
$ chrome-use fill "input[name=email]" "user@test.com"
$ chrome-use click "button.primary"

The escalation ladder

Locating an element follows a ladder from cheap to all-purpose. Walk down it in order, and don't get stuck grinding on one rung:

click's auto-scroll and DOM fallback

click first scrolls the element into the viewport; if a coordinate click is occluded, it automatically falls back to the DOM's .click(). If a click reports success but nothing happens — the classic being an autocomplete / menu <li> that closes the instant it loses focus — retry that one click in DOM click mode, or just eval:

# retry this click in DOM click mode
$ AGENT_BROWSER_CLICK_MODE=dom chrome-use click @e3

# or select and click the item directly with JS
$ chrome-use eval "document.querySelector('#stubborn').click()"

Clicking by coordinates

When the only handle you have is a coordinate — a canvas, a marker from a screenshot, a target with no stable selector — click the pixel point directly:

$ chrome-use click 449 320            # click viewport coords (x y)
$ chrome-use click 449,320            # same, comma form
$ chrome-use click --coords 449,320   # same, explicit flag

Where find can't reach

Both find and CSS selectors are based on the page DOM (querySelectorAll), so they report "Element not found" for two kinds of elements — even though snapshot -i plainly lists them (snapshots go through the CDP accessibility tree, which pierces both), and get text can read them too:

• elements inside a closed shadow root;
• elements inside a cross-origin iframe.

Next steps