> ## 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.

# Discovery commands

> Find and explore UI elements in macOS applications

Discovery commands help you locate UI elements and understand the accessibility hierarchy of applications.

## apps

List all running GUI applications.

```bash theme={null}
agent-native apps
```

### Options

<ParamField query="--format" type="string" default="text">
  Output format: `text` or `json`
</ParamField>

### Examples

<CodeGroup>
  ```bash Text output theme={null}
  agent-native apps
  ```

  ```bash JSON output theme={null}
  agent-native apps --format json
  ```
</CodeGroup>

### Output

```bash theme={null}
Safari (pid 1234)
Slack (pid 5678)
Terminal (pid 9012)
```

***

## find

Find accessibility elements matching filter criteria.

```bash theme={null}
agent-native find <app> [options]
```

### Arguments

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

### Options

<ParamField query="--role" type="string">
  Filter by accessibility role (e.g., `Button`, `TextField`)
</ParamField>

<ParamField query="--title" type="string">
  Filter by title (substring match)
</ParamField>

<ParamField query="--label" type="string">
  Filter by accessibility label (substring match)
</ParamField>

<ParamField query="--identifier" type="string">
  Filter by accessibility identifier (substring match)
</ParamField>

<ParamField query="--value" type="string">
  Filter by value (substring match)
</ParamField>

<ParamField query="--depth" type="integer" default="10">
  Maximum search depth in the element tree
</ParamField>

<ParamField query="--max" type="integer" default="20">
  Maximum number of results to return
</ParamField>

<ParamField query="--format" type="string" default="text">
  Output format: `text` or `json`
</ParamField>

### Examples

<CodeGroup>
  ```bash Find all buttons theme={null}
  agent-native find Safari --role Button
  ```

  ```bash Find by title theme={null}
  agent-native find Safari --role Button --title "Submit"
  ```

  ```bash Find text fields theme={null}
  agent-native find Safari --role TextField --max 5
  ```

  ```bash Multiple filters theme={null}
  agent-native find Slack --role Button --label "Send" --depth 15
  ```
</CodeGroup>

### Output

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

<Note>
  The `path` field shows the element's location in the accessibility tree, useful for debugging.
</Note>

***

## inspect

Inspect all attributes and available actions for an element.

```bash theme={null}
agent-native inspect <target> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` (from snapshot) or app name
</ParamField>

### Options

<ParamField query="--role" type="string">
  Filter by accessibility role
</ParamField>

<ParamField query="--title" type="string">
  Filter by title
</ParamField>

<ParamField query="--label" type="string">
  Filter by label
</ParamField>

<ParamField query="--identifier" type="string">
  Filter by identifier
</ParamField>

<ParamField query="--index" type="integer" default="0">
  Which matching element to inspect (0-indexed)
</ParamField>

<ParamField query="--json" type="boolean">
  Output as JSON
</ParamField>

### Examples

<CodeGroup>
  ```bash Inspect by reference theme={null}
  agent-native inspect @n42
  ```

  ```bash Inspect by filter theme={null}
  agent-native inspect Safari --role Button --title "Submit"
  ```

  ```bash JSON output theme={null}
  agent-native inspect @n15 --json
  ```
</CodeGroup>

### Output

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

<Tip>
  Use `inspect` to discover which actions are available for an element before using the `action` command.
</Tip>

***

## tree

Display the accessibility element hierarchy for an application.

```bash theme={null}
agent-native tree <app> [options]
```

### Arguments

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

### Options

<ParamField query="--depth" type="integer" default="5">
  Maximum tree depth to display
</ParamField>

<ParamField query="--format" type="string" default="text">
  Output format: `text` or `json`
</ParamField>

### Examples

<CodeGroup>
  ```bash Default depth theme={null}
  agent-native tree Safari
  ```

  ```bash Deeper tree theme={null}
  agent-native tree Safari --depth 10
  ```

  ```bash JSON output theme={null}
  agent-native tree Terminal --format json
  ```
</CodeGroup>

### Output

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

<Warning>
  Large depth values can produce very long output. Start with the default and increase as needed.
</Warning>

***

## snapshot

Create an annotated snapshot of the accessibility tree with element references for easy interaction.

```bash theme={null}
agent-native snapshot <app> [options]
```

### Arguments

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

### Options

<ParamField query="--interactive" type="boolean">
  Show only interactive elements (buttons, text fields, etc.)
</ParamField>

<ParamField query="--compact" type="boolean">
  Remove empty structural elements from output
</ParamField>

<ParamField query="--depth" type="integer" default="8">
  Maximum tree depth
</ParamField>

<ParamField query="--json" type="boolean">
  Output as JSON
</ParamField>

### Examples

<CodeGroup>
  ```bash Full snapshot theme={null}
  agent-native snapshot Safari
  ```

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

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

  ```bash JSON output theme={null}
  agent-native snapshot Slack --json
  ```
</CodeGroup>

### Output

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

<Note>
  References like `[ref=n4]` can be used in other commands: `agent-native click @n4`
</Note>

### 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

<Tabs>
  <Tab title="Agent automation">
    Agents can use snapshots to understand available UI elements:

    ```bash theme={null}
    # Get snapshot
    snapshot=$(agent-native snapshot Safari --interactive --compact)

    # Parse refs and interact
    agent-native click @n15
    agent-native fill @n6 "https://example.com"
    ```
  </Tab>

  <Tab title="Debugging">
    Use snapshots to explore app structure:

    ```bash theme={null}
    # Find interactive elements
    agent-native snapshot MyApp --interactive

    # Check what's clickable
    agent-native snapshot MyApp --interactive --compact
    ```
  </Tab>

  <Tab title="Testing">
    Create reproducible element references:

    ```bash theme={null}
    # Capture state
    agent-native snapshot TestApp > snapshot.txt

    # Use refs in tests
    agent-native click @n10
    agent-native wait TestApp --role Alert --timeout 5
    ```
  </Tab>
</Tabs>