Command reference - agent-native

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:

Paste current clipboard:
```
agent-native paste Arc
```
Pipe file to clipboard then paste:
```
agent-native paste Arc < image.png
```

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)

Get Started

Core Concepts

Commands

AI Integration

Guides

Reference

​Discovery commands

​apps

​find

​tree

​snapshot

​inspect

​Application commands

​open

​screenshot

​Interaction commands

​click

​fill

​type

​focus

​hover

​check

​uncheck

​select

​action

​Keyboard commands

​key

​paste

​Data retrieval commands

​get text

​get value

​get attr

​get title

​State checking commands

​is enabled

​is focused

​Wait commands

​wait

​Browser commands

​js

Build docs developers (and LLMs) love

Discovery commands

apps

find

tree

snapshot

inspect

Application commands

open

screenshot

Interaction commands

click

fill

type

focus

hover

check

uncheck

select

action

Keyboard commands

key

paste

Data retrieval commands

get text

get value

get attr

get title

State checking commands

is enabled

is focused

Wait commands

wait

Browser commands

js