Search the accessibility tree for elements matching specific criteria. Supports filtering by role, name, value, and text content. Can return all matches, a count, or specific matches by index.
Usage agent-desktop find [OPTIONS]
Parameters Filter search to a specific application by name. If omitted, searches the focused application.
Match by accessibility role (e.g., button, textfield, checkbox, link, menuitem).
Match by accessible name or label. Case-insensitive substring match.
Match by current value. Case-insensitive substring match.
Match by text in name, value, title, or description. Case-insensitive substring match.
Return only the match count, not the actual elements.
Return only the first match.
Return only the last match.
Return the Nth match (0-indexed).
Response (Default) Array of matching elements. Reference ID (e.g., @e3) if the element is interactive.
Display name or description. Falls back to (unnamed <role>) if no name is available.
Current value (for text fields, sliders, etc.).
Whether this element received a ref ID (is interactive).
Array of ancestor labels showing the element’s location in the tree (e.g., ["window:Documents", "group:Toolbar"]).
Response (Count Mode) Total number of matching elements.
Response (First/Last/Nth Mode) Single matching element (same structure as elements in matches array), or null if no match found.
Examples agent-desktop find --role button --app Finder
{ "version" : "1.0" , "ok" : true , "command" : "find" , "data" : { "matches" : [ { "ref" : "@e1" , "role" : "button" , "name" : "Back" , "interactive" : true , "path" : [ "window:Documents" , "group:Toolbar" ] }, { "ref" : "@e5" , "role" : "button" , "name" : "Forward" , "interactive" : true , "path" : [ "window:Documents" , "group:Toolbar" ] }, { "ref" : "@e12" , "role" : "button" , "name" : "List View" , "interactive" : true , "path" : [ "window:Documents" , "group:View Options" ] } ] } }
Find element by name agent-desktop find --name "Save" --app TextEdit
{ "version" : "1.0" , "ok" : true , "command" : "find" , "data" : { "matches" : [ { "ref" : "@e8" , "role" : "button" , "name" : "Save" , "interactive" : true , "path" : [ "window:Untitled" , "group:Toolbar" ] }, { "ref" : "@e23" , "role" : "menuitem" , "name" : "Save" , "interactive" : true , "path" : [ "menubar" , "menu:File" ] } ] } }
Find text field with specific value agent-desktop find --role textfield --value "quarterly report"
{ "version" : "1.0" , "ok" : true , "command" : "find" , "data" : { "matches" : [ { "ref" : "@e7" , "role" : "textfield" , "name" : "File Name" , "value" : "quarterly report" , "interactive" : true , "path" : [ "window:Save" , "group:Content" ] } ] } }
Count matches agent-desktop find --role checkbox --count --app "System Settings"
{ "version" : "1.0" , "ok" : true , "command" : "find" , "data" : { "count" : 12 } }
Get first match agent-desktop find --text "OK" --first
{ "version" : "1.0" , "ok" : true , "command" : "find" , "data" : { "match" : { "ref" : "@e14" , "role" : "button" , "name" : "OK" , "interactive" : true , "path" : [ "window:Preferences" , "group:Dialog" ] } } }
Get Nth match agent-desktop find --role menuitem --nth 2
{ "version" : "1.0" , "ok" : true , "command" : "find" , "data" : { "match" : { "ref" : "@e11" , "role" : "menuitem" , "name" : "Open…" , "interactive" : true , "path" : [ "menubar" , "menu:File" ] } } }
No matches found agent-desktop find --name "NonExistent"
{ "version" : "1.0" , "ok" : true , "command" : "find" , "data" : { "matches" : [] } }
First match when none exist agent-desktop find --name "NonExistent" --first
{ "version" : "1.0" , "ok" : true , "command" : "find" , "data" : { "match" : null } }
Error Cases Application not found { "version" : "1.0" , "ok" : false , "command" : "find" , "error" : { "code" : "APP_NOT_FOUND" , "message" : "No windows found for app 'InvalidApp'" } }
Permission denied { "version" : "1.0" , "ok" : false , "command" : "find" , "error" : { "code" : "PERM_DENIED" , "message" : "Accessibility permission not granted" , "suggestion" : "Open System Settings > Privacy & Security > Accessibility and add your terminal" } }
Notes
All text matching is case-insensitive and uses substring matching .
The --text parameter searches across name, value, title, AND description fields.
Multiple filter parameters are combined with AND logic (all must match).
The search traverses the entire accessibility tree in depth-first order .
Only the first snapshot is taken; the command does not poll for changes.
The path field shows the element’s location using the format role:name for each ancestor.
--count, --first, --last, and --nth are mutually exclusive.
See Also
snapshot - Capture the full accessibility treeget - Read element properties by refis - Check element states 
