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

# Commands overview

> Complete guide to agent-native CLI commands for macOS app automation

agent-native provides a comprehensive set of commands for automating macOS applications through the Accessibility API. Commands are organized into logical categories for different automation tasks.

## Command categories

### Discovery commands

Find and explore application UI elements:

* `apps` - List all running GUI applications
* `find` - Search for elements matching specific criteria
* `inspect` - View detailed element attributes and actions
* `tree` - Display the accessibility hierarchy
* `snapshot` - Create an interactive element reference map

### Interaction commands

Perform actions on UI elements:

* `click` - Click buttons and interactive elements
* `fill` - Clear and fill text fields
* `type` - Type text into elements
* `check` / `uncheck` - Toggle checkboxes
* `select` - Choose options from dropdowns
* `focus` - Set keyboard focus
* `hover` - Move cursor to element
* `action` - Execute arbitrary accessibility actions

### State commands

Read element properties and values:

* `get text` - Extract text content
* `get value` - Read input values
* `get attr` - Query specific attributes
* `get title` - Get window title
* `is enabled` - Check if element is enabled
* `is focused` - Check if element has focus

### Wait commands

Pause execution until conditions are met:

* `wait` - Wait for element to appear with timeout

### Keyboard commands

Send keyboard input:

* `key` - Send keystrokes and shortcuts
* `paste` - Paste clipboard or file content

### Screenshot commands

Capture visual output:

* `screenshot` - Capture app window images

## Common patterns

### Using element references

Many commands support `@ref` syntax for targeting elements from a snapshot:

```bash theme={null}
# Create snapshot with refs
agent-native snapshot Safari

# Use refs in commands
agent-native click @n42
agent-native fill @n15 "hello@example.com"
agent-native get text @n8
```

### Filter-based element selection

Commands accept filters to locate elements:

```bash theme={null}
# By role
agent-native click Safari --role Button --title "Submit"

# By label
agent-native fill Safari --label "Email" "user@example.com"

# By identifier
agent-native click Safari --identifier "login-button"

# Multiple filters
agent-native find Safari --role TextField --label "Password"
```

### JSON output

Most commands support `--json` flag for structured output:

```bash theme={null}
agent-native apps --format json
agent-native click @n5 --json
agent-native get value @n10 --json
```

## Command syntax

### Target specification

Commands use two target types:

<ParamField path="@ref" type="string">
  Element reference from snapshot (e.g., `@n1`, `@n42`)
</ParamField>

<ParamField path="app" type="string">
  Application name or bundle identifier (e.g., `Safari`, `com.apple.Safari`)
</ParamField>

### Common options

These options appear across multiple commands:

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

<ParamField query="--title" type="string">
  Filter by element 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="--index" type="integer" default="0">
  Which matching element to use (0-indexed)
</ParamField>

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

## Next steps

<CardGroup cols={2}>
  <Card title="Discovery commands" icon="magnifying-glass" href="/commands/discovery">
    Learn how to find and explore UI elements
  </Card>

  <Card title="Interaction commands" icon="hand-pointer" href="/commands/interaction">
    Control apps by clicking and typing
  </Card>

  <Card title="State commands" icon="list-check" href="/commands/state">
    Read element properties and values
  </Card>

  <Card title="Keyboard commands" icon="keyboard" href="/commands/keyboard">
    Send keystrokes and shortcuts
  </Card>
</CardGroup>