> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reticle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Reticle is a dev-only, localhost-only verification layer for AI coding agents. It reads program truth (network, state, console, routing, animations, framework state) from inside a running web app and returns a deterministic verdict with evidence. It is not a screenshot tool and not a browser automation library.
> Only `reticle_act_and_wait` and `reticle_assert` produce a verdict. Every other tool moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
> A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown; never weaken a check to make it pass.
> Package names are scoped `@reticlehq/*` and the CLI is `reticle`. Install with `npx reticle init`. The complete tool surface is on the `/usage` page; `/agent-cheatsheet` is the one-screen version.

# reticle_query

> Find elements by Testing-Library semantics. Role, text, label, placeholder, testid, alt, or React component, including inside open shadow roots.

`reticle_query` answers "where is the thing I mean?" without dumping the whole page into your context window. It queries the way a testing library does. By role, label, text, testid. So your agent binds to meaning rather than to DOM structure that a refactor will move.

## Example

```json theme={"dark"}
{ "by": "role", "value": "button", "limit": 6 }
```

Real response from a running app:

```json theme={"dark"}
{
  "count": 7,
  "elements": [
    {
      "ref": "e18",
      "role": "button",
      "name": "Overview",
      "visible": true,
      "source": "src/components/Sidebar.tsx:41",
      "states": ["present", "visible", "enabled"]
    },
    {
      "ref": "e20",
      "role": "button",
      "name": "Compose",
      "visible": true,
      "source": "src/components/Sidebar.tsx:41",
      "states": ["present", "visible", "enabled"]
    }
  ],
  "total": 7,
  "truncated": true,
  "cost": { "bytes": 938, "tokens": 235 }
}
```

Seven buttons, each with a `ref` to act on and a source file to open, for 235 tokens.

## Arguments

| Argument     | What it does                                                               |
| ------------ | -------------------------------------------------------------------------- |
| `by`         | `role` · `text` · `label` · `placeholder` · `testid` · `alt` · `component` |
| `value`      | The query value for that strategy                                          |
| `name`       | Accessible-name filter. Narrows a broad `role` query                       |
| `scope`      | CSS selector or ref, to search inside a subtree                            |
| `limit`      | Cap the descriptors returned. Cuts tokens hard on broad queries            |
| `count_only` | Return just `{ count }`, around 30x smaller                                |
| `attrs`      | Extra attributes per match, e.g. `['href']` to inventory links             |
| `self`       | Return the `scope` element itself instead of searching inside it           |

Every argument also has a predicate spelling, so `{ "role": "button" }` works as shorthand for `{ "by": "role", "value": "button" }`.

## Use `count_only` when you only need a number

"Are there still three rows?" does not require three row descriptors:

```json theme={"dark"}
{ "by": "testid", "value": "todo-row", "count_only": true }
```

## Reading the response

`ref` is the handle for every other tool: `act`, `inspect`, `state`. It stays valid until the element leaves the DOM, so you do not need to re-snapshot between actions on the same element.

`source` appears when `@reticlehq/react` is installed. Note that all five sidebar buttons above report `Sidebar.tsx:41`. That is the line where the component renders them in a loop, which is exactly the line you want to edit.

`truncated: true` with `total: 7` means `limit` cut the list, not that Reticle ran out of room.

`states` distinguishes `present` from `visible` from `enabled`. An element can be all three and still be covered by a modal. [`reticle_inspect`](/tools-inspect) reports `occluded` for that.

<Tip>
  Query by `testid` when you can. Role and text queries survive refactors well; testids survive
  redesigns, translations, and the day someone rewrites your button labels for the marketing team.
</Tip>