Introduction
# iOS Simulator Automation
This skill provides a **Node-only** CLI wrapper around: - `xcrun simctl` for simulator/device/app management - `idb` for **accessibility-tree** inspection + synthesised UI input (tap/text/button)
It is designed for **AI agents**: minimal, structured output by default, with opt-in detail.
## Important constraints
- **Must run on macOS** with Xcode Command Line Tools (or Xcode) available. - If the ClawdBot gateway is not macOS, run these commands on a connected **macOS node** (see “Remote macOS node” below). - `idb` is optional, but required for UI tree / semantic tapping. (Install steps below.)
## Quick start
```bash # 1) Sanity check node {baseDir}/scripts/ios-sim.mjs health
# 2) List simulators (compact) node {baseDir}/scripts/ios-sim.mjs list
# 3) Select a default simulator (writes .ios-sim-state.json in the current dir) node {baseDir}/scripts/ios-sim.mjs select --name "iPhone" --runtime "iOS" --boot
# 4) Install + launch an .app node {baseDir}/scripts/ios-sim.mjs app install --app path/to/MyApp.app node {baseDir}/scripts/ios-sim.mjs app launch --bundle-id com.example.MyApp
# 5) Inspect current UI (requires idb) node {baseDir}/scripts/ios-sim.mjs ui summary node {baseDir}/scripts/ios-sim.mjs ui tap --query "Log in" node {baseDir}/scripts/ios-sim.mjs ui type --text "hello world"
# 6) Screenshot node {baseDir}/scripts/ios-sim.mjs screenshot --out artifacts/screen.png ```
## Remote macOS node
If you are not on macOS, run the same commands on the macOS node using ClawdBot’s node execution (e.g. `exec` with `host: node` / node tools). Ensure the skill folder exists on that node, or copy it there.
## Output conventions (token-efficient)
- Default output: **single-line JSON** (small summary object). - Add `--pretty` to pretty-print JSON. - Add `--text` for a short human-readable summary (when provided by the command). - Commands that can be huge (`ui tree`, `list --full`) are **opt-in**.
## State / default UDID
`select` writes a state file (default: `./.ios-sim-state.json`) that stores the chosen UDID. All commands accept `--udid <UUID>` and otherwise fall back to the state file.
Override location with: - `IOS_SIM_STATE_FILE=/path/to/state.json`
## Dependency notes
### Xcode / simctl availability If `xcrun` cannot find `simctl`, ensure Xcode CLI tools are selected (via Xcode settings or `xcode-select`) and run the first-launch setup: - `xcodebuild -runFirstLaunch`
### idb (for accessibility automation) Install `idb_companion` and the `idb` CLI: ```bash brew tap facebook/fb brew install idb-companion python3 -m pip install --upgrade fb-idb ```
## Safety tiers
| Tier | Commands | Notes | |------|----------|------| | SAFE | `list`, `health`, `boot`, `shutdown`, `screenshot`, `ui *` | No data loss | | CAUTION | `privacy *`, `push`, `clipboard *`, `openurl` | Alters simulator/app state | | DANGEROUS | `erase`, `delete` | Requires `--yes` |
## Command index
All commands live under: ```bash node {baseDir}/scripts/ios-sim.mjs <command> [subcommand] [flags] ```
### Core simulator lifecycle - `list [--full]` - `select --name <substr> [--runtime <substr>] [--boot]` - `boot [--udid <uuid>] [--wait]` - `shutdown [--udid <uuid>|--all]` - `erase --yes [--udid <uuid>|--all]` - `delete --yes [--udid <uuid>]` - `create --name <name> --device-type <substr> --runtime <substr>`
### App management - `app install --app <path/to/App.app> [--udid ...]` - `app uninstall --bundle-id <id> [--udid ...]` - `app launch --bundle-id <id> [--udid ...] [-- <args...>]` - `app terminate --bundle-id <id> [--udid ...]` - `app container --bundle-id <id> [--type data|app] [--udid ...]`
### Screenshots & video - `screenshot --out <file.png> [--udid ...]` - `record-video --out <file.mp4> [--udid ...]` (runs until Ctrl+C)
### Clipboard / URL - `clipboard get [--udid ...]` - `clipboard set --text <text> [--udid ...]` - `openurl --url <url> [--udid ...]`
### Simulator permissions & push notifications - `privacy grant --bundle-id <id> --service <svc[,svc...]> [--udid ...]` - `privacy revoke --bundle-id <id> --service <svc[,svc...]> [--udid ...]` - `privacy reset --bundle-id <id> --service <svc[,svc...]> [--udid ...]` - `push --bundle-id <id> --payload <json-string> [--udid ...]`
### Logs - `logs show [--last 5m] [--predicate <expr>] [--udid ...]`
### Accessibility-driven UI automation (requires idb) - `ui summary [--limit 12]` - `ui tree` (full UI JSON array) - `ui find --query <text> [--limit 20]` - `ui tap --query <text>` (find + tap best match) - `ui tap --x <num> --y <num>` (raw coordinate tap) - `ui type --text <text>` - `ui button --name HOME|LOCK|SIRI|SIDE_BUTTON|APPLE_PAY`
## Troubleshooting
See: [references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md)