Skip to main content

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

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

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

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

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

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

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"

Build docs developers (and LLMs) love

Get started for freeTalk to us