The snapshot command is the most powerful discovery tool, creating an annotated view of an application’s accessibility tree with element references that can be used for automation.
Overview
agent-native snapshot <app> [options]
@n1, @n2) for each element, allowing you to interact with elements without writing complex selectors.
Arguments
Application name or bundle identifier
Options
Filter to show only interactive elements (buttons, inputs, etc.)
Remove empty structural elements with no labels, values, or actions
Maximum depth to traverse in the element tree
Output as JSON instead of formatted text
Examples
Basic snapshot
agent-native snapshot Safari
Snapshot: Safari (pid 1234) -- 87 elements
---------------------------------------------
Application [ref=n1]
Window "Welcome to Safari" [ref=n2]
Toolbar [ref=n3]
Button "Back" [AXPress] [ref=n4]
Button "Forward" [AXPress] [ref=n5] (disabled)
TextField "Search or enter website name" = "" [AXConfirm] [ref=n6]
Button "Reload" [AXPress] [ref=n7]
Group [ref=n8]
Button "Share" [AXPress, AXShowMenu] [ref=n9]
Button "New Tab" [AXPress] [ref=n10]
Interactive elements only
agent-native snapshot Safari --interactive
Snapshot: Safari (pid 1234) -- 23 elements
---------------------------------------------
Button "Back" [AXPress] [ref=n1]
Button "Forward" [AXPress] [ref=n2] (disabled)
TextField "Search or enter website name" = "" [AXConfirm] [ref=n3]
Button "Reload" [AXPress] [ref=n4]
Button "Share" [AXPress, AXShowMenu] [ref=n5]
Button "New Tab" [AXPress] [ref=n6]
CheckBox "Show favorites" [AXPress] [ref=n7]
PopUpButton "Bookmarks" = "Favorites" [AXPress] [ref=n8]
Compact view
agent-native snapshot Slack --compact --interactive
Snapshot: Slack (pid 5678) -- 15 elements
---------------------------------------------
Button "Back" [AXPress] [ref=n1]
TextField "Search" = "" [ref=n2]
Button "Compose" [AXPress] [ref=n3]
Button "#general" [AXPress] [ref=n4]
Button "#random" [AXPress] [ref=n5]
TextArea "Message #general" = "" [ref=n6]
Button "Send" [AXPress] [ref=n7]
JSON output
agent-native snapshot Terminal --json
[
{
"ref": "n1",
"role": "AXApplication",
"title": null,
"label": null,
"value": null,
"enabled": true,
"actions": [],
"depth": 0
},
{
"ref": "n2",
"role": "AXWindow",
"title": "Terminal — bash",
"label": null,
"value": null,
"enabled": true,
"actions": ["AXRaise"],
"depth": 1
}
]
Understanding snapshot output
Button "Submit" [AXPress] [ref=n42] (disabled)
│ │ │ │ │
│ │ │ │ └─ State indicator
│ │ │ └─ Element reference
│ │ └─ Available actions
│ └─ Title/label
└─ Role
Common roles
Button - Clickable buttonsTextField - Single-line text inputTextArea - Multi-line text inputCheckBox - Toggleable checkboxRadioButton - Radio buttonPopUpButton - Dropdown/select menuLink - Clickable linkTab - Tab in a tab barMenuItem - Menu itemWindow - Application windowScrollArea - Scrollable regionStaticText - Non-editable text
Actions
Actions shown in brackets indicate what operations are possible:
AXPress - Can be clickedAXConfirm - Can be submitted (e.g., text fields)AXShowMenu - Can show a context menuAXRaise - Can be brought to frontAXIncrement/AXDecrement - Can be increased/decreased (sliders, steppers)AXPick - Can be selected (menu items)
State indicators
(disabled) - Element is not currently interactive= "value" - Element has a current value
Using references
References from snapshots can be used in other commands:
# Snapshot shows: Button "Submit" [AXPress] [ref=n15]
agent-native click @n15
Fill text fields
# Snapshot shows: TextField "Email" = "" [ref=n8]
agent-native fill @n8 "[email protected]"
Check state
# Snapshot shows: Button "Save" [AXPress] [ref=n23]
agent-native is enabled @n23
Get values
# Snapshot shows: TextField "Username" = "john" [ref=n12]
agent-native get value @n12
Interactive element types
With --interactive flag, these roles are included:
Workflow patterns
Agent automation workflow
# 1. Create snapshot
agent-native snapshot MyApp --interactive --compact > snapshot.txt
# 2. Agent parses snapshot to find relevant elements
# Example: Find login button ref
# 3. Use refs to automate
agent-native fill @n5 "username"
agent-native fill @n6 "password"
agent-native click @n7 # Login button
# 4. Wait for next state
agent-native wait MyApp --role Button --title "Dashboard"
# 5. Take new snapshot
agent-native snapshot MyApp --interactive --compact
Testing workflow
# Create baseline snapshot
agent-native snapshot TestApp --json > baseline.json
# Run test interactions
agent-native click @n10
agent-native fill @n12 "test data"
# Verify results
agent-native get text @n15
agent-native is enabled @n20
# Compare new snapshot
agent-native snapshot TestApp --json > after.json
diff baseline.json after.json
Debugging workflow
# Full hierarchy for exploration
agent-native snapshot MyApp > full.txt
# Find interactive elements
agent-native snapshot MyApp --interactive > interactive.txt
# Minimal view for quick scan
agent-native snapshot MyApp --interactive --compact > minimal.txt
# Inspect specific element
agent-native inspect @n25
Tips
Use --interactive --compact together for the cleanest output focused on actionable elements.
References are stored temporarily. If you restart the CLI, you’ll need to create a new snapshot.
For dynamic UIs, take a new snapshot after major state changes to get fresh references.
References are specific to the current app state. If the UI changes significantly, existing refs may become invalid.
find - Search for specific elementstree - View full hierarchy without refsinspect - View detailed element informationclick - Click elements using refsfill - Fill text fields using refs