ios-simulator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iOS Simulator Automation

iOS Simulator自动化

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.

该Skill提供一个仅支持Node.js的CLI封装，基于以下工具：

```
xcrun simctl
```
：用于模拟器/设备/应用管理
```
idb
```
：用于无障碍树检查以及合成UI输入（点击/文本输入/按钮操作）

它专为AI Agent设计：默认输出简洁结构化内容，可选择启用详细输出。

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

必须运行在macOS系统上，且需安装Xcode Command Line Tools（或Xcode）。
如果ClawdBot网关不是macOS系统，请在连接的macOS节点上运行这些命令（详见下方“远程macOS节点”）。
```
idb
```
为可选依赖，但如需进行UI树检查/语义化点击操作则必须安装。（安装步骤见下文。）

Quick start

快速开始

bash

undefined

bash

undefined

1) Sanity check

1) 完整性检查

node {baseDir}/scripts/ios-sim.mjs health

2) List simulators (compact)

2) 列出模拟器（精简模式）

node {baseDir}/scripts/ios-sim.mjs list

3) Select a default simulator (writes .ios-sim-state.json in the current dir)

3) 选择默认模拟器（在当前目录写入.ios-sim-state.json文件）

node {baseDir}/scripts/ios-sim.mjs select --name "iPhone" --runtime "iOS" --boot

4) Install + launch an .app

4) 安装并启动.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)

5) 检查当前UI（需要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

6) 截图

node {baseDir}/scripts/ios-sim.mjs screenshot --out artifacts/screen.png

undefined

node {baseDir}/scripts/ios-sim.mjs screenshot --out artifacts/screen.png

undefined

Remote macOS node

远程macOS节点

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.

若你不在macOS系统上，可使用ClawdBot的节点执行功能（例如带

host: node

/node工具的

exec

命令）在macOS节点上运行相同命令。确保该Skill文件夹已存在于该节点，或先将其复制过去。

Output conventions (token-efficient)

输出规范（高效利用Token）

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.

默认输出：单行JSON（简洁的摘要对象）。
添加
```
--pretty
```
参数可格式化输出JSON。
添加
```
--text
```
参数可获取简短的人类可读摘要（仅部分命令支持）。
可能产生大量输出的命令（如
```
ui tree
```
、
```
list --full
```
）需主动启用。

State / default UDID

状态/默认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
```

select

命令会写入一个状态文件（默认路径：

./.ios-sim-state.json

），用于存储选定的UDID。所有命令均支持

--udid <UUID>

参数，若未指定则会读取状态文件中的值。

可通过以下方式覆盖状态文件路径：

```
IOS_SIM_STATE_FILE=/path/to/state.json
```

Dependency notes

依赖说明

Xcode / simctl availability

Xcode / simctl可用性

xcrun

cannot find

simctl

, ensure Xcode CLI tools are selected (via Xcode settings or

xcode-select

) and run the first-launch setup:

```
xcodebuild -runFirstLaunch
```

若

xcrun

无法找到

simctl

，请确保已选择Xcode CLI工具（可通过Xcode设置或

xcode-select

命令），并运行首次启动设置：

```
xcodebuild -runFirstLaunch
```

idb (for accessibility automation)

idb（用于无障碍自动化）

Install

idb_companion

and the

idb

CLI:

bash

brew tap facebook/fb
brew install idb-companion
python3 -m pip install --upgrade fb-idb

安装

idb_companion

和

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`

等级	命令	说明
安全	`list` , `health` , `boot` , `shutdown` , `screenshot` , `ui *`	无数据丢失风险
注意	`privacy ` , `push` , `clipboard ` , `openurl`	会修改模拟器/应用状态
危险	`erase` , `delete`	需要添加 `--yes` 参数确认

Command index

命令索引

All commands live under:

bash

node {baseDir}/scripts/ios-sim.mjs <command> [subcommand] [flags]

所有命令均使用以下格式：

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>

```
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 ...]

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)

screenshot --out <file.png> [--udid ...]

record-video --out <file.mp4> [--udid ...]

（按Ctrl+C停止）

Clipboard / URL

剪贴板/URL

```
clipboard get [--udid ...]
```

clipboard set --text <text> [--udid ...]

```
openurl --url <url> [--udid ...]
```

```
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 ...]

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

logs show [--last 5m] [--predicate <expr>] [--udid ...]

Accessibility-driven UI automation (requires idb)

基于无障碍功能的UI自动化（需要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

```
ui summary [--limit 12]
```
```
ui tree
```
（完整UI JSON数组）
```
ui find --query <text> [--limit 20]
```
```
ui tap --query <text>
```
（查找并点击最佳匹配项）
```
ui tap --x <num> --y <num>
```
（基于坐标的原始点击）
```
ui type --text <text>
```

ui button --name HOME|LOCK|SIRI|SIDE_BUTTON|APPLE_PAY

Troubleshooting

故障排除

See: references/TROUBLESHOOTING.md

详见：references/TROUBLESHOOTING.md