Discovery commands help you locate UI elements and understand the accessibility hierarchy of applications.
apps List all running GUI applications.
Options Output format: text or json
Examples Output Safari (pid 1234 ) Slack (pid 5678 ) Terminal (pid 9012 )
find Find accessibility elements matching filter criteria.
agent-native find < ap p > [options]
Arguments Application name or bundle identifier
Options Filter by accessibility role (e.g., Button, TextField)
Filter by title (substring match)
Filter by accessibility label (substring match)
Filter by accessibility identifier (substring match)
Filter by value (substring match)
Maximum search depth in the element tree
Maximum number of results to return
Output format: text or json
Examples Find all buttons
Find by
Find text fields
Multiple filters
agent-native find Safari --role Button
Output Found 3 element ( s ) in Safari: --------------------------------------------- [0] Button "Back" path: Application/Window[0]/Toolbar/Button[0] [1] Button "Forward" path: Application/Window[0]/Toolbar/Button[1] [2] Button "Reload" path: Application/Window[0]/Toolbar/Button[2]
The path field shows the element’s location in the accessibility tree, useful for debugging.
inspect Inspect all attributes and available actions for an element.
agent-native inspect < targe t > [options]
Arguments Target element: @ref (from snapshot) or app name
Options Filter by accessibility role
Which matching element to inspect (0-indexed)
Examples Inspect by reference
Inspect by filter
JSON output
agent-native inspect @n42
Output Element: Button "Submit" Path: Application/Window[0]/Group[1]/Button[3] --- Attributes --- AXDescription: Submit the form AXEnabled: true AXFocused: false AXFrame: {{100, 200 }, {80, 32 }} AXPosition: {100, 200 } AXRole: AXButton AXRoleDescription: button AXSize: {80, 32 } AXTitle: Submit --- Actions --- AXPress AXShowMenu
Use inspect to discover which actions are available for an element before using the action command.
tree Display the accessibility element hierarchy for an application.
agent-native tree < ap p > [options]
Arguments Application name or bundle identifier
Options Maximum tree depth to display
Output format: text or json
Examples Default depth
Deeper tree
JSON output
Output Accessibility tree for Safari (pid 1234 ): --------------------------------------------- Application Window "Welcome to Safari" Toolbar Button "Back" Button "Forward" TextField "Search or enter website name" Button "Reload" Group ScrollArea WebArea Group StaticText "Welcome to Safari"
Large depth values can produce very long output. Start with the default and increase as needed.
snapshot Create an annotated snapshot of the accessibility tree with element references for easy interaction.
agent-native snapshot < ap p > [options]
Arguments Application name or bundle identifier
Options Show only interactive elements (buttons, text fields, etc.)
Remove empty structural elements from output
Examples Full snapshot
Interactive elements only
Compact view
JSON output
agent-native snapshot Safari
Output Snapshot: Safari (pid 1234 ) -- 47 elements --------------------------------------------- Application [ref=n1] Window "Welcome to Safari" [ref=n2] Toolbar [ref=n3] Button "Back" [AXPress] [ref = n4] Button "Forward" [AXPress] [ref = n5] TextField "Search or enter website name" = "" [AXConfirm] [ref = n6] Button "Reload" [AXPress] [ref = n7] Group [ref=n8] ScrollArea [ref=n9] WebArea [ref=n10]
References like [ref=n4] can be used in other commands: agent-native click @n4
Interactive roles When using --interactive, these element types are included:
Buttons and menu items
Text fields and text areas
Checkboxes and radio buttons
Popup buttons and combo boxes
Sliders and steppers
Links and tabs
Switches and toggles
Search fields
Use cases Agent automation
Debugging
Testing
Agents can use snapshots to understand available UI elements: # Get snapshot snapshot = $( agent-native snapshot Safari --interactive --compact ) # Parse refs and interact agent-native click @n15 agent-native fill @n6 "https://example.com"
Use snapshots to explore app structure: # Find interactive elements agent-native snapshot MyApp --interactive # Check what's clickable agent-native snapshot MyApp --interactive --compact
Create reproducible element references: # Capture state agent-native snapshot TestApp > snapshot.txt # Use refs in tests agent-native click @n10 agent-native wait TestApp --role Alert --timeout 5