# 命令行

用 Device MCP 的命令行工具 device-mcp-cli，在“终端”、Shell 脚本和 CI 中操作你的 iPhone、iPad、Android 设备或模拟器。每个命令都可以用 JSON 返回结果。

`device-mcp-cli` 是 Device MCP 的命令行工具。你在 App 中做的事，或让 AI Agent 做的事，都可以在“终端”、Shell 脚本、Makefile 或 CI 中运行：列出设备、截图、读取屏幕、轻点和输入、启动和安装 App、设置位置，以及管理许可证。

每个命令都可以用 JSON 返回结果，因此你的脚本可以用 `jq` 读取结果，无需解析文本。

## 1. 安装
* **Homebrew**：`brew install --cask device-mcp` 会把 `device-mcp-cli` 添加到 `PATH` 中。
* **从网站下载**：在“终端”中运行一次以下命令，把它添加到 `PATH` 中：

```bash
sudo ln -sf "/Applications/Device MCP.app/Contents/MacOS/device-mcp-cli" /usr/local/bin/device-mcp-cli
```

Device MCP 自动更新后，这个链接仍然有效。用以下命令检查：

```bash
device-mcp-cli --version
device-mcp-cli --help                  # every command
device-mcp-cli help apps launch        # one command, with its options
```

## 2. 工作原理
* **命令由 Device MCP 执行。** 设备命令会发送到 Mac 上的 Device MCP App。如果它没有运行，命令会先询问你再打开它：`--launch` 不询问直接打开（适合在脚本中使用），`--no-launch` 从不打开。`status`、`mcp`、`tools` 和 `logs` 从不打开它。
* **指定设备**：添加 `--device`（或 `-d`），后跟设备名称或 UDID。不指定时，命令使用你用 `devices select` 选择的设备，否则使用 Device MCP 中选中的设备。
* **JSON**：任何命令都可以加上 `--json`。错误也会以 JSON 返回。
* **一切由你掌控**：安装和移除 App、打开链接、读取或更改剪贴板以及 Build & Run，都会先在 Device MCP 中询问你，就像 AI Agent 执行这些操作时一样。请参阅[操作审批](ai-agents/approvals.md)。解除设备配对和停用许可证始终会询问。
* **免费版与 Pro**：所有命令都可在 Device MCP Free 上使用，只有 Build & Run、安装 App 和 3D 视图检查器需要 [Device MCP Pro](license.md)。免费版一次只能镜像一台设备。

## 3. 命令
`<device>` 是设备的名称或 UDID。每个命令都接受 `--json`；设备命令接受 `--device`。

### 设备
| 命令 | 作用 |
| --- | --- |
| `devices` | 列出设备：名称、类型、系统、连接方式、状态和 UDID。`--all` 还会列出所有模拟器，以及新建模拟器时可选的机型。 |
| `devices info` | 显示设备的机型、系统、屏幕尺寸、镜像状态和锁定状态。`--settings` 还会显示它的外观和辅助功能设置。 |
| `devices select <device>` | 选择后续命令使用的设备，并在 Device MCP 中显示它。 |
| `devices start-mirroring`、`devices stop-mirroring` | 开始或停止镜像设备。 |
| `devices reconnect` | 重新连接镜像画面卡住的设备。 |
| `devices unpair <device>` | 解除 iPhone 或 iPad 与 Mac 的配对。 |
| `devices remove <device>` | 将设备从 Device MCP 的列表中移除。 |
| `simulators` | 列出 iOS 和 watchOS 模拟器以及 Android 模拟器。 |
| `simulators start <name>` | 启动模拟器，并等待它运行起来。`--model "iPhone 17 Pro"` 会新建一个模拟器。 |
| `simulators stop <name>` | 关闭模拟器。 |

### 屏幕
| 命令 | 作用 |
| --- | --- |
| `screenshot` | 保存一张全分辨率截图。`-o` 指定文件（`.png` 或 `.jpg`）或文件夹；默认保存到 `~/Pictures/Device MCP`。 |
| `record start`、`record stop` | 将屏幕录制为视频，保存到 `~/Movies/Device MCP`。 |
| `elements` | 列出屏幕上的内容：每个元素的类型、标签、值、位置和尺寸，以及 ref（`e12`），供 `tap --ref` 使用。 |

### 触控和按键
| 命令 | 作用 |
| --- | --- |
| `tap` | 按文字（`--text "Sign In"`）或 ref（`--ref e12`）轻点元素，或轻点某个坐标点（`-x 120 -y 640`）。`--double` 轻点两下，`--long` 长按。 |
| `type <text>` | 在当前聚焦的输入框中输入。`--field "Email"` 填写一个输入框：轻点它、清空，然后输入。`--submit` 按下 Return 键。`-` 从管道或文件读取文本。 |
| `scroll up\|down\|left\|right` | 滚动。`--distance 300` 让内容正好移动 300 点。 |
| `swipe --from x,y --to x,y` | 从一个点滑动到另一个点。 |
| `press <button>` | 按下 `home`、`lock`、`volume_up`、`volume_down`、`mute`、`siri` 或 `back`。 |
| `key <key>` | 按下键盘按键，可配合 `--modifier command` 等修饰键。 |
| `gesture <gesture>` | `go_home`、`app_switcher`、`control_center`、`notification_center` 或 `spotlight`。 |
| `rotate <orientation>` | `portrait`、`landscape_left`、`landscape_right` 或 `portrait_upside_down`。 |
| `hide-keyboard` | 隐藏屏幕键盘。 |
| `wait-for <text>` | 等待文字出现在屏幕上（`--gone`：等待它消失），最多等待 `--timeout` 秒。 |
| `alert accept\|dismiss` | 回应系统弹窗，例如权限请求。`--button` 按文字轻点某个按钮。 |

### App
| 命令 | 作用 |
| --- | --- |
| `apps` | 列出已安装的 App：名称、Bundle ID 和版本。`--user` 只列出你安装的 App。 |
| `apps foreground` | 显示前台的 App 及其 Bundle ID。 |
| `apps launch <app>` | 按 Bundle ID 或名称启动 App。测试启动时可使用 `--language`、`--locale`、`--arg` 和 `--env`。 |
| `apps terminate <bundle-id>` | 退出正在运行的 App。 |
| `apps install <path>` | 安装 `.ipa`、`.app` 或 `.apk`。需要 Device MCP Pro。 |
| `apps uninstall <bundle-id>` | 移除 App 及其数据。 |
| `apps container <bundle-id>` | 将为开发而安装的 App 的数据下载为 `.xcappdata` 包，与 Xcode 相同。 |
| `open-url <url>` | 打开网页或深层链接（`myapp://…`）。 |
| `build-and-run <project>` | 构建 Xcode 项目，然后安装并启动它。需要 Device MCP Pro。请参阅 [Build & Run](ai-agents/build-and-run.md)。 |
| `crashes` | 列出崩溃报告，最新的排在前面。`--app` 按 App 筛选。 |
| `crashes show <path>` | 显示崩溃报告：什么崩溃了、在哪里崩溃。`--app` 显示某个 App 最近一次崩溃。 |

### 设备设置
| 命令 | 作用 |
| --- | --- |
| `location set <latitude> <longitude>` | 模拟位置。`location clear` 恢复真实位置。 |
| `appearance light\|dark` | 将设备切换为浅色或深色模式。 |
| `clipboard get`、`clipboard set <text>` | 读取或替换设备剪贴板上的文本。 |

### Device MCP
| 命令 | 作用 |
| --- | --- |
| `status` | 显示 Device MCP 是否正在运行，以及它的版本、MCP 服务器和你的许可证。 |
| `app open`、`app quit` | 在后台打开 Device MCP，或退出它。 |
| `mcp` | 显示 MCP 服务器是否已打开，以及它的地址。`mcp on` 和 `mcp off` 用于打开和关闭它。 |
| `mcp setup claude\|codex` | 将 Device MCP 添加到 Claude Code 或 Codex。`--print` 只显示命令，不执行。 |
| `mcp config` | 输出其他 MCP 客户端（例如 Cursor）使用的 JSON。 |
| `license` | 显示你的许可证：免费版，或许可证的方案、密钥、席位和涵盖的版本。 |
| `license activate <key>` | 在这台 Mac 上激活许可证密钥。 |
| `license revoke` | 在这台 Mac 上停用许可证并释放其席位。 |
| `logs` | 输出 Device MCP 的日志，用于 Bug 报告。`-f` 持续输出新的日志行。 |

### 其他
| 命令 | 作用 |
| --- | --- |
| `call <tool> [name=value…]` | 像 AI Agent 那样，运行 Device MCP 的任意 MCP 工具。 |
| `tools` | 列出这些工具及其参数。 |

## 4. 示例
### 登录并检查结果
为 App 做一次冒烟测试，可放在 Shell 脚本或 CI 步骤中：

```bash
set -e
device-mcp-cli apps launch com.example.myapp --launch
device-mcp-cli wait-for "Sign In"
device-mcp-cli type "test@example.com" --field "Email"
device-mcp-cli type - --field "Password" < password.txt
device-mcp-cli tap --text "Sign In"
device-mcp-cli wait-for "Welcome" --timeout 20 || {
  device-mcp-cli screenshot -o failure.png
  exit 1
}
```

### 为每台设备截图
```bash
device-mcp-cli devices --json |
  jq -r '.devices[] | select(.state == "ready" or .state == "running") | .udid' |
  while read -r udid; do device-mcp-cli screenshot --device "$udid" -o ~/Desktop/; done
```

### 轻点屏幕上的元素
`elements` 会列出屏幕上的元素及其 ref。用 `jq` 找到其中一个，然后轻点它：

```bash
REF=$(device-mcp-cli elements --json | jq -r '.elements[] | select(.label == "General") | .ref')
device-mcp-cli tap --ref "$REF"
```

### 换一种语言和地点测试 App
```bash
device-mcp-cli apps launch com.example.myapp --language fr --locale fr_FR
device-mcp-cli location set 48.8584 2.2945
device-mcp-cli open-url "myapp://map"
device-mcp-cli appearance dark
```

### 在新模拟器上构建并运行
```bash
device-mcp-cli simulators start --model "iPhone 17 Pro" --launch
device-mcp-cli build-and-run ~/Projects/MyApp/MyApp.xcodeproj --scheme MyApp
device-mcp-cli screenshot -o ~/Desktop/myapp.png
```

### 录制 Bug
```bash
device-mcp-cli record start
# reproduce the bug on the device
device-mcp-cli record stop
```

### 设置一台 Mac
在 CI 用的 Mac 或新同事的 Mac 上：

```bash
device-mcp-cli license activate --launch < license-key.txt
device-mcp-cli mcp on
device-mcp-cli mcp setup claude
device-mcp-cli status
```

## 5. JSON 与退出码
使用 `--json` 时，命令会输出一个 JSON 对象。例如 `device-mcp-cli devices --json`：

```json
{
  "devices" : [
    {
      "connection" : "USB",
      "current" : true,
      "kind" : "iphone",
      "mirroringStopped" : false,
      "model" : "iPhone 17 Pro",
      "name" : "My iPhone",
      "osVersion" : "27.0.1",
      "platform" : "iOS",
      "state" : "ready",
      "udid" : "00008150-000A1B2C3D4E5F60"
    }
  ]
}
```

设备的 `kind` 为 `iphone`、`ipad`、`watch`、`android`、`simulator` 或 `emulator`。它的 `state` 为 `ready`、`locked`、`blocked`（附带 `issue` 和 `fix`，说明原因和解决方法）、`connecting`、`running`、`shut_down`、`booting`、`shutting_down`、`creating` 或 `starting`。

出错时，命令会输出 `{"error": {"code": "…", "message": "…"}}`：

| 错误代码 | 退出码 | 含义 |
| --- | --- | --- |
| `not_running` | 69 | Device MCP 没有运行且未被打开，或者在回应前退出了。 |
| `no_answer` | 69 | Device MCP 正在运行但没有回应：请更新它，或退出后重新打开。 |
| `not_installed` | 69 | 未安装 Device MCP。 |
| `invalid_arguments` | 64 | 参数错误，或许可证密钥格式不正确。 |
| `pro_required` | 1 | 该命令需要 Device MCP Pro。 |
| `not_approved` | 1 | 你在 Device MCP 中拒绝了该操作，或者无人回应。 |
| `timed_out` | 1 | Device MCP 未能及时完成。 |
| `cancelled` | 1 | 你选择了“否”。 |
| `failed` | 1 | 其他任何错误：消息会说明原因。 |

命令成功时，退出码为 0。

## 6. 配合 AI Agent 使用
你的 Agent 也可以使用命令行，例如为 App 编写测试脚本或 CI 步骤：

* *“写一个脚本，在我的 iPhone 上登录，如果首页没有加载出来就判定失败。”*
* *“添加一个 CI 步骤，为新手引导的每个页面截图。”*

Agent 运行的命令会以 **device-mcp-cli** 的名称显示在 **Agent** 标签页中。请参阅 [Agent 活动](ai-agents/agent-activity.md)。