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

# Complete examples

> Real-world automation examples using agent-native

End-to-end examples demonstrating common automation patterns with agent-native.

## Calculator automation

Automate the macOS Calculator app to perform calculations.

### Basic calculation

Perform a simple calculation: 5 + 3 = 8

```bash theme={null}
# Open Calculator
agent-native open Calculator

# Take a snapshot to see available buttons
agent-native snapshot Calculator --interactive

# Click buttons using refs from snapshot
agent-native click @n5   # 5
agent-native click @n12  # +
agent-native click @n7   # 3
agent-native click @n18  # =

# Get the result
agent-native get text Calculator --role AXStaticText
```

### Using filters instead of refs

Same calculation using title filters:

```bash theme={null}
agent-native open Calculator

agent-native click Calculator --role AXButton --title "5"
agent-native click Calculator --role AXButton --title "+"
agent-native click Calculator --role AXButton --title "3"
agent-native click Calculator --role AXButton --title "="

agent-native get text Calculator --role AXStaticText
```

### Complex calculation

Perform (15 + 7) × 2:

```bash theme={null}
agent-native open Calculator

# Type 15
agent-native click Calculator --role AXButton --title "1"
agent-native click Calculator --role AXButton --title "5"

# Add 7
agent-native click Calculator --role AXButton --title "+"
agent-native click Calculator --role AXButton --title "7"

# Equals
agent-native click Calculator --role AXButton --title "="

# Multiply by 2
agent-native click Calculator --role AXButton --title "×"
agent-native click Calculator --role AXButton --title "2"
agent-native click Calculator --role AXButton --title "="

# Result: 44
agent-native get text Calculator --role AXStaticText
```

## TextEdit automation

Automate TextEdit for document creation and editing.

### Create and save a document

```bash theme={null}
# Open TextEdit
agent-native open TextEdit

# Wait for window to appear
agent-native wait TextEdit --role AXWindow --timeout 5

# Take snapshot to find text area
agent-native snapshot TextEdit --interactive

# Fill the text area
agent-native fill @n3 "This is my document content.

It has multiple paragraphs.

Created with agent-native."

# Save the document (Cmd+S)
agent-native key TextEdit cmd+s

# Wait for save dialog
agent-native wait TextEdit --role AXTextField --label "Save As" --timeout 3

# Fill filename
agent-native fill TextEdit --role AXTextField --label "Save As" "my-document.txt"

# Click Save button
agent-native click TextEdit --role AXButton --title "Save"
```

### Find and replace

```bash theme={null}
# Open TextEdit with existing document
agent-native open TextEdit

# Open Find dialog (Cmd+F)
agent-native key TextEdit cmd+f

# Wait for find field
agent-native wait TextEdit --role AXSearchField --timeout 3

# Enter search term
agent-native fill TextEdit --role AXSearchField "old text"

# Click "Replace All" button
agent-native click TextEdit --role AXButton --title "Replace All"

# Fill replacement text
agent-native fill TextEdit --role AXTextField "new text"

# Confirm replacement
agent-native click TextEdit --role AXButton --title "Replace"
```

### Format text

```bash theme={null}
# Open TextEdit
agent-native open TextEdit

# Type some text
agent-native fill TextEdit --role AXTextArea "Hello, world!"

# Select all (Cmd+A)
agent-native key TextEdit cmd+a

# Make it bold (Cmd+B)
agent-native key TextEdit cmd+b

# Increase font size
agent-native key TextEdit cmd+plus cmd+plus cmd+plus

# Take a screenshot
agent-native screenshot TextEdit ~/Desktop/formatted-text.png
```

## Finder automation

Automate Finder for file management tasks.

### Navigate to folder

```bash theme={null}
# Open Finder
agent-native open Finder

# Use Cmd+Shift+G to open "Go to Folder"
agent-native key Finder cmd+shift+g

# Wait for path field
agent-native wait Finder --role AXTextField --timeout 3

# Enter path
agent-native fill Finder --role AXTextField "~/Documents"

# Press Enter
agent-native key Finder return

# Wait for folder to load
sleep 1

# Take a screenshot
agent-native screenshot Finder ~/Desktop/documents-folder.png
```

### Create new folder

```bash theme={null}
# Open Finder
agent-native open Finder

# Navigate to location (see above)
agent-native key Finder cmd+shift+g
agent-native wait Finder --role AXTextField --timeout 3
agent-native fill Finder --role AXTextField "~/Desktop"
agent-native key Finder return

sleep 1

# Create new folder (Cmd+Shift+N)
agent-native key Finder cmd+shift+n

# Wait for folder name field
agent-native wait Finder --role AXTextField --timeout 3

# Name the folder
agent-native fill Finder --role AXTextField "My New Folder"

# Press Enter to confirm
agent-native key Finder return
```

### Search for files

```bash theme={null}
# Open Finder
agent-native open Finder

# Focus search field (Cmd+F)
agent-native key Finder cmd+f

# Wait for search field
agent-native wait Finder --role AXSearchField --timeout 3

# Enter search query
agent-native fill Finder --role AXSearchField "*.pdf"

# Wait for results
sleep 2

# Get count of results
agent-native get text Finder --role AXStaticText
```

### Change view options

```bash theme={null}
# Open Finder
agent-native open Finder

# Take snapshot to see view options
agent-native snapshot Finder --interactive

# Switch to list view
agent-native click Finder --role AXButton --label "List View"

# Or use keyboard shortcuts
# Icon view: Cmd+1
# List view: Cmd+2  
# Column view: Cmd+3
# Gallery view: Cmd+4
agent-native key Finder cmd+2
```

## Safari automation

Automate Safari for web browsing tasks.

### Navigate to URL and extract content

```bash theme={null}
# Open Safari
agent-native open Safari

# Focus address bar (Cmd+L)
agent-native key Safari cmd+l

# Type URL
agent-native key Safari "example.com" return

# Wait for page load
sleep 3

# Execute JavaScript to get page title
agent-native js Safari "document.title"

# Get all links
agent-native js Safari "Array.from(document.querySelectorAll('a')).map(a => a.href).join('\\n')"

# Take screenshot
agent-native screenshot Safari ~/Desktop/webpage.png
```

### Fill form and submit

```bash theme={null}
# Open Safari and navigate to form page
agent-native open Safari
agent-native key Safari cmd+l
agent-native key Safari "example.com/form" return

sleep 3

# Fill form fields using JavaScript
agent-native js Safari "document.querySelector('#name').value = 'John Doe'"
agent-native js Safari "document.querySelector('#email').value = 'john@example.com'"
agent-native js Safari "document.querySelector('#message').value = 'Hello from agent-native'"

# Submit form
agent-native js Safari "document.querySelector('form').submit()"
```

### Open multiple tabs

```bash theme={null}
# Open Safari
agent-native open Safari

# Open new tabs
agent-native key Safari cmd+t
agent-native key Safari "github.com" return
sleep 2

agent-native key Safari cmd+t
agent-native key Safari "stackoverflow.com" return
sleep 2

agent-native key Safari cmd+t
agent-native key Safari "apple.com" return
sleep 2

# Switch between tabs (Cmd+Shift+[ and Cmd+Shift+])
agent-native key Safari cmd+shift+[

# Get current tab title
agent-native js Safari "document.title"
```

### Check if element exists

```bash theme={null}
# Navigate to page
agent-native open Safari
agent-native key Safari cmd+l
agent-native key Safari "example.com" return
sleep 3

# Check if button exists
result=$(agent-native js Safari "document.querySelector('#submit-button') !== null")

if [ "$result" = "true" ]; then
    echo "Button found!"
    agent-native js Safari "document.querySelector('#submit-button').click()"
else
    echo "Button not found"
fi
```

## System Settings automation

Automate System Settings (formerly System Preferences).

### Navigate to specific pane

```bash theme={null}
# Open System Settings
agent-native open "System Settings"

# Wait for window
agent-native wait "System Settings" --role AXWindow --timeout 5

# Take snapshot
agent-native snapshot "System Settings" --interactive

# Click on Appearance
agent-native click "System Settings" --role AXButton --title "Appearance"

# Wait for pane to load
sleep 1

# Take screenshot
agent-native screenshot "System Settings" ~/Desktop/appearance-settings.png
```

### Toggle setting

```bash theme={null}
# Open System Settings > Accessibility
agent-native open "System Settings"
agent-native wait "System Settings" --role AXWindow --timeout 5

# Navigate to Accessibility
agent-native click "System Settings" --role AXButton --title "Accessibility"
sleep 1

# Take snapshot to find toggle
agent-native snapshot "System Settings" --interactive

# Toggle a setting
agent-native check @n15

# Verify it's enabled
agent-native is enabled @n15
```

### Change dropdown setting

```bash theme={null}
# Open System Settings
agent-native open "System Settings"

# Navigate to Desktop & Dock
agent-native click "System Settings" --role AXButton --title "Desktop & Dock"
sleep 1

# Take snapshot
agent-native snapshot "System Settings" --interactive

# Find popup button and select option
agent-native select @n8 "Medium"
```

## Advanced patterns

### Conditional automation

```bash theme={null}
#!/bin/bash

# Check if Calculator is running
apps=$(agent-native apps --format json)

if echo "$apps" | grep -q "Calculator"; then
    echo "Calculator is already running"
else
    echo "Opening Calculator"
    agent-native open Calculator
fi

# Check if button is enabled before clicking
enabled=$(agent-native is enabled Calculator --role AXButton --title "=" --json)

if echo "$enabled" | grep -q '"enabled":true'; then
    agent-native click Calculator --role AXButton --title "="
else
    echo "Button is disabled"
fi
```

### Retry with timeout

```bash theme={null}
#!/bin/bash

# Try to click button, retry if it fails
max_attempts=5
attempt=1

while [ $attempt -le $max_attempts ]; do
    echo "Attempt $attempt of $max_attempts"
    
    if agent-native click Safari --role AXButton --title "Submit" 2>/dev/null; then
        echo "Click succeeded"
        break
    else
        echo "Click failed, waiting..."
        sleep 2
        attempt=$((attempt + 1))
    fi
done

if [ $attempt -gt $max_attempts ]; then
    echo "Failed after $max_attempts attempts"
    exit 1
fi
```

### Parallel automation

```bash theme={null}
#!/bin/bash

# Open multiple apps in parallel
agent-native open Calculator &
agent-native open TextEdit &
agent-native open Safari &

# Wait for all to finish
wait

echo "All apps opened"

# Take screenshots of all windows
agent-native screenshot Calculator ~/Desktop/calc.png &
agent-native screenshot TextEdit ~/Desktop/textedit.png &
agent-native screenshot Safari ~/Desktop/safari.png &

wait

echo "All screenshots captured"
```

### Loop through elements

```bash theme={null}
#!/bin/bash

# Get all buttons in Calculator
agent-native find Calculator --role AXButton --format json > buttons.json

# Parse and iterate (requires jq)
buttons=$(cat buttons.json | jq -r '.[].title // empty')

echo "Found buttons:"
while IFS= read -r title; do
    echo "  - $title"
done <<< "$buttons"
```

### Wait for element with custom logic

```bash theme={null}
#!/bin/bash

# Wait for element with custom condition
timeout=30
interval=1
elapsed=0

while [ $elapsed -lt $timeout ]; do
    # Check if element exists and is enabled
    if agent-native find Safari --role AXButton --title "Done" --max 1 2>/dev/null | grep -q "Done"; then
        enabled=$(agent-native is enabled Safari --role AXButton --title "Done")
        if [ "$enabled" = "true" ]; then
            echo "Element found and enabled"
            break
        fi
    fi
    
    sleep $interval
    elapsed=$((elapsed + interval))
done

if [ $elapsed -ge $timeout ]; then
    echo "Timeout waiting for element"
    exit 1
fi
```

## Debugging tips

<Accordion title="Use snapshot to explore UI">
  Start with a snapshot to see all available elements:

  ```bash theme={null}
  agent-native snapshot Calculator --interactive
  ```

  This shows you the refs and structure you can interact with.
</Accordion>

<Accordion title="Use tree for deeper inspection">
  The tree command shows the full accessibility hierarchy:

  ```bash theme={null}
  agent-native tree Safari --depth 10
  ```

  Increase depth to see more nested elements.
</Accordion>

<Accordion title="Inspect specific elements">
  Use inspect to see all attributes and available actions:

  ```bash theme={null}
  agent-native inspect @n5
  ```

  This shows you exactly what attributes you can filter by.
</Accordion>

<Accordion title="Add delays between actions">
  Some UI elements need time to respond:

  ```bash theme={null}
  agent-native click @n5
  sleep 0.5
  agent-native click @n6
  ```
</Accordion>

<Accordion title="Use wait instead of sleep">
  The wait command is more reliable than sleep:

  ```bash theme={null}
  agent-native wait Safari --role AXButton --title "Done" --timeout 10
  ```
</Accordion>

<Accordion title="Check JSON output for scripting">
  Use `--json` flag for easier parsing:

  ```bash theme={null}
  agent-native apps --format json | jq '.'
  agent-native click @n5 --json | jq '.success'
  ```
</Accordion>