LLM-friendly automation CLI for iOS apps
npm install agent-iosCLI for LLM-friendly iOS Simulator automation. Get accessibility snapshots, tap elements by reference, type text, and more.
``bash`
npm install -g agent-ios
agent-ios setup # Clones WebDriverAgent to ~/WebDriverAgent
- macOS with Xcode + Command Line Tools
- Node.js 18+
`bash`
agent-ios start-session --sim "iPhone 15" # Boot simulator + start WDA
agent-ios snapshot # Get accessibility tree with refs
agent-ios tap @e5 # Tap element by ref
agent-ios type @e10 "Hello World" # Type text into element
agent-ios stop-session # Stop session
`bash`
agent-ios start-session [--sim
agent-ios stop-session # Stop WDA and daemon
agent-ios status # Check daemon/simulator/WDA status
agent-ios list-sims # List available simulators
`bash`
agent-ios install
agent-ios launch
agent-ios terminate
`bash`
agent-ios snapshot # Get accessibility tree as JSON with refs
agent-ios screenshot [--out
agent-ios tap # Tap element (e.g., @e5)
agent-ios type
agent-ios clear # Clear text field
agent-ios swipe
agent-ios wait [--timeout
`bash`
agent-ios alert-accept # Accept current alert
agent-ios alert-dismiss # Dismiss current alert
agent-ios alert-button
All commands return JSON:
`json`
{"success": true, "data": {...}}
{"success": false, "error": "..."}
`json`
{
"timestamp": "2025-01-16T10:00:00Z",
"elements": [
{
"ref": "@e1",
"type": "XCUIElementTypeButton",
"label": "Log in",
"identifier": "loginButton",
"value": null,
"frame": { "x": 12, "y": 780, "w": 351, "h": 48 },
"enabled": true,
"visible": true,
"children": ["@e2"]
}
],
"tree": "@e0",
"refMap": {
"@e1": {
"type": "XCUIElementTypeButton",
"label": "Log in",
"identifier": "loginButton"
}
}
}
- ref: Opaque reference for use in commands (tap @e1)refMap
- : Quick lookup of ref to type/label/identifiertree
- : Root element refchildren
- Elements are flat with refs (no deep nesting)
| Variable | Default | Description |
| ------------------- | ------------------ | ------------------------------------ |
| WDA_PATH | ~/WebDriverAgent | Path to WebDriverAgent |WDA_PORT
| | 8100 | WDA HTTP port |IOS_AGENT_SESSION
| | default | Session name (for multiple sessions) |
`
CLI (agent-ios) → Unix Socket → Node.js Daemon → HTTP → WebDriverAgent → iOS Simulator
The daemon manages WDA lifecycle and maintains element ref mappings between snapshots.
WDA build slow? First build compiles WebDriverAgent. Watch progress:
`bash`
tail -f /tmp/agent-ios-wda.log
Element not found? UI changed since last snapshot. Run snapshot again to get fresh refs.
Simulator not booting? Ensure Xcode CLI tools are set:
`bash``
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
MIT