6. Selectors

--query takes a CSS-like selector over the layer tree of the current page (--page for another, --all-pages for all):

Selector	Matches
frame, text, instance, component, rectangle, …	By type (lowercase Plugin API type).
#nd-3f9a0c1e7b2d	By id.
[name="Login"], [name^="Btn"], [name*="icon"], [name~=/^h\d$/]	By name: equal, prefix, contains, regex.
[component="Button"], [variant.State="Hover"]	Instances of a component or variant.
[style.fill="Brand/Primary"], [var="color/brand"]	Nodes using a style or variable.
[layout=vertical], [visible=false], [locked]	By property.
:contains("Sign in")	Text content.
:selected, :root, :top	Live selection, page, top-level frames.
A B, A > B, A, B, :not(…), :has(…)	Descendant, child, union, negation, has.

ud find --query '…' lists matches. A command that expects one node fails with exit 2 when a query matches several, unless --each runs it once per match or the command accepts many nodes.