> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ericclemmons/agent-native/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

<ParamField path="app" type="string" required>
  Application name or bundle identifier
</ParamField>

### Options

<ParamField query="--interactive" type="boolean">
  Filter to show only interactive elements (buttons, inputs, etc.)
</ParamField>

<ParamField query="--compact" type="boolean">
  Remove empty structural elements with no labels, values, or actions
</ParamField>

<ParamField query="--depth" type="integer" default="8">
  Maximum depth to traverse in the element tree
</ParamField>

<ParamField query="--json" type="boolean">
  Output as JSON instead of formatted text
</ParamField>

## Examples

### Basic snapshot

```bash theme={null}
agent-native snapshot Safari
```

Output:

```bash theme={null}
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

```bash theme={null}
agent-native snapshot Safari --interactive
```

Shows only elements users can interact with:

```bash theme={null}
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

```bash theme={null}
agent-native snapshot Slack --compact --interactive
```

Removes structural containers:

```bash theme={null}
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

```bash theme={null}
agent-native snapshot Terminal --json
```

Output:

```json theme={null}
[
  {
    "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

```bash theme={null}
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

```bash theme={null}
# Snapshot shows: Button "Submit" [AXPress] [ref=n15]
agent-native click @n15
```

### Fill text fields

```bash theme={null}
# Snapshot shows: TextField "Email" = "" [ref=n8]
agent-native fill @n8 "user@example.com"
```

### Check state

```bash theme={null}
# Snapshot shows: Button "Save" [AXPress] [ref=n23]
agent-native is enabled @n23
```

### Get values

```bash theme={null}
# Snapshot shows: TextField "Username" = "john" [ref=n12]
agent-native get value @n12
```

## Interactive element types

With `--interactive` flag, these roles are included:

<Tabs>
  <Tab title="Input elements">
    * `AXButton`
    * `AXTextField`
    * `AXTextArea`
    * `AXSearchField`
    * `AXSecureTextField`
  </Tab>

  <Tab title="Selection elements">
    * `AXCheckBox`
    * `AXRadioButton`
    * `AXPopUpButton`
    * `AXComboBox`
    * `AXSwitch`
    * `AXToggle`
  </Tab>

  <Tab title="Navigation elements">
    * `AXLink`
    * `AXTab`
    * `AXMenuItem`
    * `AXMenuBarItem`
    * `AXMenuButton`
  </Tab>

  <Tab title="Adjustment elements">
    * `AXSlider`
    * `AXStepper`
    * `AXIncrementor`
    * `AXDisclosureTriangle`
    * `AXColorWell`
    * `AXSegmentedControl`
  </Tab>
</Tabs>

## Workflow patterns

### Agent automation workflow

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

<Tip>
  Use `--interactive --compact` together for the cleanest output focused on actionable elements.
</Tip>

<Tip>
  References are stored temporarily. If you restart the CLI, you'll need to create a new snapshot.
</Tip>

<Tip>
  For dynamic UIs, take a new snapshot after major state changes to get fresh references.
</Tip>

<Warning>
  References are specific to the current app state. If the UI changes significantly, existing refs may become invalid.
</Warning>

## Related commands

* [`find`](/commands/discovery#find) - Search for specific elements
* [`tree`](/commands/discovery#tree) - View full hierarchy without refs
* [`inspect`](/commands/discovery#inspect) - View detailed element information
* [`click`](/commands/interaction#click) - Click elements using refs
* [`fill`](/commands/interaction#fill) - Fill text fields using refs