MacPilot Automation
Use the macpilot CLI tool to automate macOS. MacPilot provides 100+ commands for mouse, keyboard, app, window, UI, clipboard, dialog, shell, and system control. All commands support --json for structured output.
When to Use
Use this skill when the user asks to:
- Automate macOS tasks (open apps, click buttons, type text, navigate menus)
- Control mouse and keyboard programmatically
- Interact with running applications via accessibility APIs
- Chain multiple automation steps into workflows
- Run shell commands or interact with Terminal
- Manage clipboard, notifications, audio, display settings
Prerequisites
MacPilot must be installed at /Applications/MacPilot.app with a symlink at /usr/local/bin/macpilot or ~/bin/macpilot. The app requires Accessibility permission in System Settings > Privacy & Security > Accessibility.
Core Commands Reference
Mouse Control
macpilot click <x> <y> # Left click at coordinates
macpilot doubleclick <x> <y> # Double click
macpilot rightclick <x> <y> # Right click
macpilot move <x> <y> # Move cursor
macpilot drag <x1> <y1> <x2> <y2> # Drag from point to point
macpilot scroll <up|down|left|right> [amount] # Scroll (default: 3)
macpilot mouse-position --json # Get current cursor position
Keyboard Control
macpilot keyboard type "Hello World" # Type text
macpilot keyboard key cmd+c # Press shortcut
macpilot keyboard key enter # Press single key
macpilot chain "type:hello" "key:tab" "type:world" # Chain actions
Modifier keys: cmd, shift, alt, ctrl, fn
Special keys: enter, tab, space, escape, delete, f1-f12, up, down, left, right
App Management
macpilot app open "Safari" # Open/launch app
macpilot app focus "Safari" # Bring app to front
macpilot app frontmost --json # Get frontmost app
macpilot app list --json # List running apps
macpilot app quit "Safari" # Quit app
macpilot app quit "Safari" --force # Force quit
macpilot app hide "Safari" # Hide app
Menu Interaction
macpilot menu click File Open --app Safari # Click menu item
macpilot menu list --app Safari --json # List all menus
macpilot menu list --app Safari --menu File # List specific menu
Clipboard
macpilot clipboard get --json # Read clipboard text
macpilot clipboard set "text" # Set clipboard text
macpilot clipboard image photo.png # Copy image to clipboard
macpilot clipboard info --json # Content type, size, preview
macpilot clipboard types --json # List all UTI types
macpilot clipboard clear --json # Clear clipboard
macpilot clipboard paste --json # Simulate Cmd+V
macpilot clipboard copy file.txt --json # Copy file(s) to clipboard
macpilot clipboard save /tmp/out.png # Save clipboard content to file
# Clipboard history (background daemon, max 50 items)
macpilot clipboard history start --json # Start tracking
macpilot clipboard history stop --json # Stop tracking
macpilot clipboard history list --json # Show history
macpilot clipboard history search "text" # Search history
macpilot clipboard history clear --json # Delete history
Shell Commands
macpilot shell run "ls -la" # Run command, get output
macpilot shell interactive "top" # Open in Terminal
macpilot shell type "git status" # Type into active terminal
macpilot shell paste "long command here" # Paste via clipboard
System Controls
macpilot audio volume get --json # Get volume (0-100)
macpilot audio volume set 50 # Set volume
macpilot audio volume mute # Mute
macpilot display brightness set 75 # Set brightness
macpilot appearance dark # Dark mode
macpilot appearance light # Light mode
macpilot notification send "Title" "Body" # System notification
macpilot notification list --json # List visible notifications
macpilot notification click --title "match" # Click notification by title
macpilot notification dismiss --json # Dismiss top notification
macpilot notification dismiss --all # Dismiss all notifications
macpilot system info --json # System info
macpilot network wifi-name --json # Wi-Fi name
macpilot network ip --json # IP address
Waiting & Synchronization
macpilot wait seconds 2 # Sleep 2 seconds
macpilot wait element "Save" --app TextEdit # Wait for UI element
macpilot wait window "Untitled" --timeout 10 # Wait for window
macpilot watch events --duration 5 --json # Monitor events
Spaces & Dock
macpilot space list --json # List spaces
macpilot space switch right # Switch space
macpilot dock hide # Auto-hide dock
macpilot dock show # Always show dock
Critical Patterns
-
Always focus the app before interacting:
macpilot app focus "AppName"must come before clicking, typing, or menu operations. The first click after focus may be consumed by window activation - click the app's content area first, then click the target. -
Use
--jsonfor parsing: Always add--jsonwhen you need to parse output programmatically. -
Use
ui find-textfor coordinates: When you need to click a specific element, first find its coordinates withmacpilot ui find-text "label" --app AppName --json, then click at the returned position. -
Chain for complex sequences: Use
macpilot chainfor multi-step keyboard workflows instead of multiple separate commands. -
AX value set over keyboard: Setting text field values via
macpilot ui set-valueis more reliable than keyboard typing when focus is uncertain. -
Wait for elements: Use
macpilot wait elementbefore interacting with UI elements that may not have appeared yet.
Example Workflows
Open a URL in Safari
macpilot app open Safari
macpilot wait window Safari --timeout 5
macpilot app focus Safari
macpilot keyboard key cmd+l
macpilot keyboard type "https://example.com"
macpilot keyboard key enter
Copy text from one app to another
macpilot app focus "TextEdit"
macpilot keyboard key cmd+a
macpilot keyboard key cmd+c
macpilot app focus "Notes"
macpilot keyboard key cmd+v
Create a new file in TextEdit
macpilot app open TextEdit
macpilot wait window TextEdit --timeout 5
macpilot keyboard type "Hello from MacPilot!"
macpilot keyboard key cmd+s
macpilot wait seconds 1
macpilot dialog navigate "/Users/me/Desktop"
macpilot dialog set-field "myfile.txt"
macpilot dialog click-button "Save"