Complete examples

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

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

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:

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

#!/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

#!/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

#!/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

#!/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

#!/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

Use snapshot to explore UI

Start with a snapshot to see all available elements:

agent-native snapshot Calculator --interactive

This shows you the refs and structure you can interact with.

Use tree for deeper inspection

The tree command shows the full accessibility hierarchy:

agent-native tree Safari --depth 10

Increase depth to see more nested elements.

Inspect specific elements

Use inspect to see all attributes and available actions:

agent-native inspect @n5

This shows you exactly what attributes you can filter by.

Add delays between actions

Some UI elements need time to respond:

agent-native click @n5
sleep 0.5
agent-native click @n6

Use wait instead of sleep

The wait command is more reliable than sleep:

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

Check JSON output for scripting

Use --json flag for easier parsing:

agent-native apps --format json | jq '.'
agent-native click @n5 --json | jq '.success'

Get Started

Core Concepts

Commands

AI Integration

Guides

Reference

Calculator automation

Basic calculation

Using filters instead of refs

Complex calculation

TextEdit automation

Create and save a document

Find and replace

Format text

Finder automation

Navigate to folder

Create new folder

Search for files

Change view options

Safari automation

Navigate to URL and extract content

Fill form and submit

Open multiple tabs

Check if element exists

System Settings automation

Navigate to specific pane

Toggle setting

Advanced patterns

Conditional automation

Retry with timeout

Parallel automation

Loop through elements

Wait for element with custom logic

Debugging tips

Build docs developers (and LLMs) love

Get Started

Core Concepts

Commands

AI Integration

Guides

Reference

Documentation Index

​Calculator automation

​Basic calculation

​Using filters instead of refs

​Complex calculation

​TextEdit automation

​Create and save a document

​Find and replace

​Format text

​Finder automation

​Navigate to folder

​Create new folder

​Search for files

​Change view options

​Safari automation

​Navigate to URL and extract content

​Fill form and submit

​Open multiple tabs

​Check if element exists

​System Settings automation

​Navigate to specific pane

​Toggle setting

​Change dropdown setting

​Advanced patterns

​Conditional automation

​Retry with timeout

​Parallel automation

​Loop through elements

​Wait for element with custom logic

​Debugging tips

Build docs developers (and LLMs) love

Calculator automation

Basic calculation

Using filters instead of refs

Complex calculation

TextEdit automation

Create and save a document

Find and replace

Format text

Finder automation

Navigate to folder

Create new folder

Search for files

Change view options

Safari automation

Navigate to URL and extract content

Fill form and submit

Open multiple tabs

Check if element exists

System Settings automation

Navigate to specific pane

Toggle setting

Change dropdown setting

Advanced patterns

Conditional automation

Retry with timeout

Parallel automation

Loop through elements

Wait for element with custom logic

Debugging tips