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

# Interaction commands

> Control macOS applications by clicking, typing, and manipulating UI elements

Interaction commands perform actions on UI elements using either element references from snapshots or filter-based selection.

## click

Click an element by performing the `AXPress` action.

```bash theme={null}
agent-native click <target> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` (from snapshot) or app name
</ParamField>

### Options

<ParamField query="--role" type="string">
  Filter by accessibility role
</ParamField>

<ParamField query="--title" type="string">
  Filter by title
</ParamField>

<ParamField query="--label" type="string">
  Filter by label
</ParamField>

<ParamField query="--identifier" type="string">
  Filter by identifier
</ParamField>

<ParamField query="--index" type="integer" default="0">
  Which matching element to click (0-indexed)
</ParamField>

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

### Examples

<CodeGroup>
  ```bash Click by reference theme={null}
  agent-native click @n15
  ```

  ```bash Click by filter theme={null}
  agent-native click Safari --role Button --title "Submit"
  ```

  ```bash Click second match theme={null}
  agent-native click Safari --role Button --label "Continue" --index 1
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Clicked: Button "Submit"
```

<Note>
  The command attempts `AXPress` first, then falls back to `AXConfirm` if press is not available.
</Note>

***

## fill

Clear a text field and type new text.

```bash theme={null}
agent-native fill <target> <text> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` or app name
</ParamField>

<ParamField path="text" type="string" required>
  Text to fill into the field
</ParamField>

### Options

<ParamField query="--role" type="string">
  Filter by role (defaults to `TextField` when using app name)
</ParamField>

<ParamField query="--title" type="string">
  Filter by title
</ParamField>

<ParamField query="--label" type="string">
  Filter by label
</ParamField>

<ParamField query="--index" type="integer" default="0">
  Which matching element to fill
</ParamField>

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

### Examples

<CodeGroup>
  ```bash Fill by reference theme={null}
  agent-native fill @n8 "user@example.com"
  ```

  ```bash Fill by label theme={null}
  agent-native fill Safari --label "Email" "test@example.com"
  ```

  ```bash Fill password field theme={null}
  agent-native fill Safari --role SecureTextField "mypassword123"
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Filled: TextField "Email" with "user@example.com"
```

<Info>
  The `fill` command focuses the element, clears existing content, then sets the new value.
</Info>

***

## type

Type text into an element without clearing existing content.

```bash theme={null}
agent-native type <target> <text> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` or app name
</ParamField>

<ParamField path="text" type="string" required>
  Text to type
</ParamField>

### Options

Same as `fill` command.

### Examples

<CodeGroup>
  ```bash Type into field theme={null}
  agent-native type @n12 "additional text"
  ```

  ```bash Append to existing text theme={null}
  agent-native type Safari --label "Notes" " - updated"
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Typed "additional text" into: TextField "Notes"
```

<Tip>
  Use `type` to append text, or `fill` to replace existing content.
</Tip>

***

## check

Check a checkbox or toggle (idempotent - only clicks if not already checked).

```bash theme={null}
agent-native check <target> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` or app name
</ParamField>

### Options

<ParamField query="--role" type="string">
  Filter by role (defaults to `CheckBox` when using app name)
</ParamField>

<ParamField query="--title" type="string">
  Filter by title
</ParamField>

<ParamField query="--label" type="string">
  Filter by label
</ParamField>

<ParamField query="--index" type="integer" default="0">
  Which matching element to check
</ParamField>

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

### Examples

<CodeGroup>
  ```bash Check by reference theme={null}
  agent-native check @n20
  ```

  ```bash Check by label theme={null}
  agent-native check Safari --label "Show bookmarks"
  ```

  ```bash Check toggle theme={null}
  agent-native check Settings --role Switch --title "Enable notifications"
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Checked: CheckBox "Enable notifications"
```

***

## uncheck

Uncheck a checkbox or toggle (idempotent - only clicks if currently checked).

```bash theme={null}
agent-native uncheck <target> [options]
```

### Arguments and options

Identical to `check` command.

### Examples

<CodeGroup>
  ```bash Uncheck by reference theme={null}
  agent-native uncheck @n21
  ```

  ```bash Uncheck by label theme={null}
  agent-native uncheck Safari --label "Show toolbar"
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Unchecked: CheckBox "Show toolbar"
```

***

## select

Select an option from a popup button or combo box.

```bash theme={null}
agent-native select <target> <option> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` or app name
</ParamField>

<ParamField path="option" type="string" required>
  Title of the option to select
</ParamField>

### Options

<ParamField query="--role" type="string">
  Filter by role (defaults to `PopUpButton` when using app name)
</ParamField>

<ParamField query="--title" type="string">
  Filter by title
</ParamField>

<ParamField query="--label" type="string">
  Filter by label
</ParamField>

<ParamField query="--index" type="integer" default="0">
  Which matching element to use
</ParamField>

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

### Examples

<CodeGroup>
  ```bash Select by reference theme={null}
  agent-native select @n18 "Dark Mode"
  ```

  ```bash Select from dropdown theme={null}
  agent-native select Settings --label "Theme" "System"
  ```

  ```bash Select from combo box theme={null}
  agent-native select Safari --role ComboBox --title "Encoding" "UTF-8"
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Selected "Dark Mode" in: PopUpButton "Theme"
```

<Info>
  The command clicks the popup button, waits briefly for the menu to appear, then clicks the menu item matching the option title.
</Info>

***

## focus

Set keyboard focus to an element.

```bash theme={null}
agent-native focus <target> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` or app name
</ParamField>

### Options

Standard filter options: `--role`, `--title`, `--label`, `--identifier`, `--index`, `--json`

### Examples

<CodeGroup>
  ```bash Focus by reference theme={null}
  agent-native focus @n10
  ```

  ```bash Focus search field theme={null}
  agent-native focus Safari --role SearchField
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Focused: SearchField "Search"
```

***

## hover

Move the mouse cursor to the center of an element.

```bash theme={null}
agent-native hover <target> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` or app name
</ParamField>

### Options

Standard filter options (no `--identifier` support)

### Examples

<CodeGroup>
  ```bash Hover by reference theme={null}
  agent-native hover @n25
  ```

  ```bash Hover button theme={null}
  agent-native hover Safari --role Button --title "Downloads"
  ```
</CodeGroup>

### Output

```bash theme={null}
OK Hovered: Button "Downloads"
```

<Note>
  Hovering can trigger tooltips and hover states but does not click the element.
</Note>

***

## action

Perform an arbitrary accessibility action on an element.

```bash theme={null}
agent-native action <target> <action> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` or app name
</ParamField>

<ParamField path="action" type="string" required>
  Accessibility action to perform (e.g., `AXPress`, `AXConfirm`, `AXIncrement`)
</ParamField>

### Options

Standard filter options: `--role`, `--title`, `--label`, `--identifier`, `--index`, `--json`

### Examples

<CodeGroup>
  ```bash Custom action theme={null}
  agent-native action @n30 AXIncrement
  ```

  ```bash Show menu theme={null}
  agent-native action Safari --role Button --title "File" AXShowMenu
  ```

  ```bash Raise window theme={null}
  agent-native action Safari --role Window AXRaise
  ```
</CodeGroup>

### Output

```bash theme={null}
OK AXIncrement on: Stepper "Volume"
```

<Warning>
  If the specified action is not available for the element, a warning is shown but the command still attempts the action.
</Warning>

### Common actions

* `AXPress` - Click/activate
* `AXConfirm` - Confirm/submit
* `AXShowMenu` - Show context menu
* `AXIncrement` - Increase value
* `AXDecrement` - Decrease value
* `AXRaise` - Bring to front
* `AXCancel` - Cancel operation
* `AXPick` - Pick/select item

<Tip>
  Use `inspect` command to see which actions are available for an element.
</Tip>

## Workflow examples

### Login form automation

```bash theme={null}
# Get snapshot
agent-native snapshot MyApp --interactive

# Fill credentials
agent-native fill @n5 "username@example.com"
agent-native fill @n6 "mypassword"

# Check "Remember me"
agent-native check @n7

# Submit
agent-native click @n8
```

### Form with dropdown

```bash theme={null}
# Fill text fields
agent-native fill @n10 "John Doe"
agent-native fill @n11 "john@example.com"

# Select from dropdown
agent-native select @n12 "United States"

# Submit form
agent-native click @n13
```

### Multi-step wizard

```bash theme={null}
# Step 1
agent-native fill @n5 "Company Name"
agent-native click @n6  # Next button

# Wait for next page
agent-native wait MyApp --role Button --title "Previous"

# Step 2
agent-native check @n10
agent-native check @n11
agent-native click @n12  # Next button

# Step 3
agent-native fill @n15 "Additional notes"
agent-native click @n16  # Finish button
```