Snapshot command

Create interactive element reference maps for agent automation

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]

Snapshot generates unique references (like @n1, @n2) for each element, allowing you to interact with elements without writing complex selectors.

Arguments

app · string · required

Application name or bundle identifier

Options

--interactive · boolean

Filter to show only interactive elements (buttons, inputs, etc.)

--compact · boolean

Remove empty structural elements with no labels, values, or actions

--depth · integer · default: "8"

Maximum depth to traverse in the element tree

--json · boolean

Output as JSON instead of formatted text

Examples

Basic snapshot

agent-native snapshot Safari

Output:

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

Shows only elements users can interact with:

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

Removes structural containers:

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

Output:

[
  {
    "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

Element format

Button "Submit" [AXPress] [ref=n42] (disabled)
│      │        │         │          │
│      │        │         │          └─ State indicator
│      │        │         └─ Element reference
│      │        └─ Available actions
│      └─ Title/label
└─ Role

Common roles

• Button - Clickable buttons
• TextField - Single-line text input
• TextArea - Multi-line text input
• CheckBox - Toggleable checkbox
• RadioButton - Radio button
• PopUpButton - Dropdown/select menu
• Link - Clickable link
• Tab - Tab in a tab bar
• MenuItem - Menu item
• Window - Application window
• ScrollArea - Scrollable region
• StaticText - Non-editable text

Actions

Actions shown in brackets indicate what operations are possible:

• AXPress - Can be clicked
• AXConfirm - Can be submitted (e.g., text fields)
• AXShowMenu - Can show a context menu
• AXRaise - Can be brought to front
• AXIncrement/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:

Click buttons

# Snapshot shows: Button "Submit" [AXPress] [ref=n15]
agent-native click @n15

Fill text fields

# Snapshot shows: TextField "Email" = "" [ref=n8]
agent-native fill @n8 "[e-mail]"

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:

Input elements

• AXButton
• AXTextField
• AXTextArea
• AXSearchField
• AXSecureTextField

Selection elements

• AXCheckBox
• AXRadioButton
• AXPopUpButton
• AXComboBox
• AXSwitch
• AXToggle

Navigation elements

• AXLink
• AXTab
• AXMenuItem
• AXMenuBarItem
• AXMenuButton

Adjustment elements

• AXSlider
• AXStepper
• AXIncrementor
• AXDisclosureTriangle
• AXColorWell
• AXSegmentedControl

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.

Related commands

• find - Search for specific elements
• tree - View full hierarchy without refs
• inspect - View detailed element information
• click - Click elements using refs
• fill - Fill text fields using refs