Command reference

Complete reference of all agent-native CLI commands

Complete reference for all commands in the agent-native CLI toolkit.

Discovery commands

apps

List all running GUI applications.

agent-native apps [--format text|json]

--format · text|json · default: "text"

Output format

Example:

agent-native apps

---

find

Find accessibility elements matching filters.

agent-native find <app> [OPTIONS]

app · string · required

Application name

--role · string

Filter by role (e.g., AXButton, AXTextField)

--title · string

Filter by title (substring match)

--label · string

Filter by label (substring match)

--identifier · string

Filter by identifier (substring match)

--value · string

Filter by value (substring match)

--depth · int · default: "10"

Maximum search depth

--max · int · default: "20"

Maximum results to return

--format · text|json · default: "text"

Output format

Example:

agent-native find Safari --role AXButton --title "New Tab"

---

tree

Print the accessibility tree for an application.

agent-native tree <app> [OPTIONS]

app · string · required

Application name

--depth · int · default: "5"

Maximum tree depth

--format · text|json · default: "text"

Output format

Example:

agent-native tree Calculator --depth 3

---

snapshot

Create an accessibility tree snapshot with interactive references (@n1, @n2, etc.).

agent-native snapshot <app> [OPTIONS]

app · string · required

Application name

--interactive · flag

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

--compact · flag

Remove empty structural elements

--depth · int · default: "8"

Maximum tree depth

--json · flag

JSON output

Example:

agent-native snapshot Calculator --interactive

The snapshot command generates @n1, @n2, etc. references that can be used with other commands like click, fill, and get.

---

inspect

Inspect all attributes and actions of an element.

agent-native inspect <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--identifier · string

Filter by identifier

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native inspect @n5
agent-native inspect Calculator --role AXButton --title "5"

Application commands

open

Open or launch an application.

agent-native open <app> [OPTIONS]

app · string · required

Application name or bundle identifier

--format · text|json · default: "text"

Output format

Example:

agent-native open Calculator
agent-native open com.apple.calculator

---

screenshot

Capture a screenshot of an app’s frontmost window.

agent-native screenshot <app> [path] [OPTIONS]

app · string · required

Application name or bundle identifier

path · string

Output path (defaults to auto-generated temp file)

--json · flag

JSON output

Example:

agent-native screenshot Safari ~/Desktop/safari.png

Interaction commands

click

Click an element (performs AXPress action).

agent-native click <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--identifier · string

Filter by identifier

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Examples:

agent-native click @n5
agent-native click Calculator --role AXButton --title "5"

---

fill

Clear a text field and type new text.

agent-native fill <target> <text> [OPTIONS]

target · string · required

Target element: @ref or app name

text · string · required

Text to fill

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Examples:

agent-native fill @n3 "hello world"
agent-native fill TextEdit --role AXTextArea "Document content"

---

type

Type text into an element without clearing existing content.

agent-native type <target> <text> [OPTIONS]

target · string · required

Target element: @ref or app name

text · string · required

Text to type

--role · string

Filter by role (defaults to TextField)

--title · string

Filter by title

--label · string

Filter by label

--identifier · string

Filter by identifier

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native type @n7 "additional text"

---

focus

Focus an element.

agent-native focus <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--identifier · string

Filter by identifier

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native focus @n2

---

hover

Hover over an element (moves cursor to center).

agent-native hover <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native hover @n8

---

check

Check a checkbox or toggle (idempotent).

agent-native check <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role (defaults to CheckBox)

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native check @n12
agent-native check "System Settings" --title "Show scroll bars"

---

uncheck

Uncheck a checkbox or toggle (idempotent).

agent-native uncheck <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role (defaults to CheckBox)

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native uncheck @n12

---

select

Select an option from a popup button or combo box.

agent-native select <target> <option> [OPTIONS]

target · string · required

Target element: @ref or app name

option · string · required

Option to select (by title)

--role · string

Filter by role (defaults to PopUpButton)

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native select @n4 "Medium"

---

action

Perform an arbitrary AX action on an element.

agent-native action <target> <action> [OPTIONS]

target · string · required

Target element: @ref or app name

action · string · required

Action to perform (e.g., AXPress, AXConfirm, AXIncrement)

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--identifier · string

Filter by identifier

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native action @n9 AXIncrement

Use inspect to see available actions for an element.

Keyboard commands

key

Send keystrokes to an application.

agent-native key <app> <keys...> [OPTIONS]

app · string · required

Application name or bundle identifier

keys · string... · required

Keys to send (e.g., cmd+k, escape, “Hello world”)

--json · flag

JSON output

Examples:

agent-native key Safari cmd+t
agent-native key Terminal "echo hello" return
agent-native key TextEdit cmd+shift+s

Supported modifiers:

• cmd or command
• ctrl or control
• alt, option, or opt
• shift

Special keys:

• return, enter, tab, space
• delete, backspace, escape, esc
• left, right, up, down
• home, end, pageup, pagedown
• f1 through f12

---

paste

Paste clipboard contents or a file into an app via Cmd+V.

agent-native paste <app> [path] [OPTIONS]

app · string · required

Application name or bundle identifier

path · string

Path to file to paste (omit to paste clipboard or stdin)

--json · flag

JSON output

Three input modes:

1. Paste current clipboard:

   agent-native paste Arc
   

2. Pipe file to clipboard then paste:

   agent-native paste Arc < image.png
   

3. Copy file to clipboard then paste:

   agent-native paste Arc path/to/image.png
   

Data retrieval commands

get text

Get the text content of an element.

agent-native get text <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native get text @n5

---

get value

Get the value of an input element.

agent-native get value <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native get value @n3

---

get attr

Get a specific attribute of an element.

agent-native get attr <target> <attribute> [OPTIONS]

target · string · required

Target element: @ref or app name

attribute · string · required

Attribute name (e.g., AXRole, AXValue, AXEnabled)

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native get attr @n7 AXEnabled

---

get title

Get the title of the frontmost window of an app.

agent-native get title <app> [OPTIONS]

app · string · required

Application name

--json · flag

JSON output

Example:

agent-native get title Safari

State checking commands

is enabled

Check if an element is enabled.

agent-native is enabled <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native is enabled @n4

---

is focused

Check if an element is focused.

agent-native is focused <target> [OPTIONS]

target · string · required

Target element: @ref or app name

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--index · int · default: "0"

Which match (0-indexed)

--json · flag

JSON output

Example:

agent-native is focused @n3

Wait commands

wait

Wait until an element matching filters appears.

agent-native wait <app> [OPTIONS]

app · string · required

Application name

--role · string

Filter by role

--title · string

Filter by title

--label · string

Filter by label

--identifier · string

Filter by identifier

--timeout · float · default: "10.0"

Timeout in seconds

--interval · float · default: "0.5"

Poll interval in seconds

--format · text|json · default: "text"

Output format

Example:

agent-native wait Safari --role AXButton --title "Done" --timeout 30

Browser commands

js

Execute JavaScript in a browser’s active tab.

agent-native js <app> <code> [OPTIONS]

app · string · required

Browser app name (Arc, Google Chrome, Safari)

code · string · required

JavaScript code to execute

--json · flag

JSON output

Examples:

agent-native js Arc "document.title"
agent-native js Safari "document.querySelectorAll('button').length"
agent-native js Chrome "window.location.href"

You must enable “Allow JavaScript from Apple Events” in the browser’s developer settings.

Supported browsers:

• Arc
• Google Chrome (use “Chrome” as shorthand)
• Safari
• Chromium
• Brave Browser
• Microsoft Edge (use “Edge” as shorthand)