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.

agent-native apps

Options

--format · string · default: "text"

Output format: text or json

Examples

Text output

agent-native apps

Output

Safari (pid 1234)
Slack (pid 5678)
Terminal (pid 9012)

---

find

Find accessibility elements matching filter criteria.

agent-native find <app> [options]

Arguments

app · string · required

Application name or bundle identifier

Options

--role · string

Filter by accessibility role (e.g., Button, TextField)

--title · string

Filter by title (substring match)

--label · string

Filter by accessibility label (substring match)

--identifier · string

Filter by accessibility identifier (substring match)

--value · string

Filter by value (substring match)

--depth · integer · default: "10"

Maximum search depth in the element tree

--max · integer · default: "20"

Maximum number of results to return

--format · string · default: "text"

Output format: text or json

Examples

Find all buttons

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 <target> [options]

Arguments

target · string · required

Target element: @ref (from snapshot) or app name

Options

--role · string

Filter by accessibility role

--title · string

Filter by title

--label · string

Filter by label

--identifier · string

Filter by identifier

--index · integer · default: "0"

Which matching element to inspect (0-indexed)

--json · boolean

Output as JSON

Examples

Inspect by reference

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 <app> [options]

Arguments

app · string · required

Application name or bundle identifier

Options

--depth · integer · default: "5"

Maximum tree depth to display

--format · string · default: "text"

Output format: text or json

Examples

Default depth

agent-native tree Safari

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 <app> [options]

Arguments

app · string · required

Application name or bundle identifier

Options

--interactive · boolean

Show only interactive elements (buttons, text fields, etc.)

--compact · boolean

Remove empty structural elements from output

--depth · integer · default: "8"

Maximum tree depth

--json · boolean

Output as JSON

Examples

Full snapshot

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

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"

Debugging

Use snapshots to explore app structure:

# Find interactive elements
agent-native snapshot MyApp --interactive

# Check what's clickable
agent-native snapshot MyApp --interactive --compact

Testing

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