CLI 命令参考

vphone-cli 是所有操作的命令行入口。不带子命令时默认执行 boot（启动虚拟 iPhone）。任何时候都可以用 --help 查看某个命令的完整选项：

vphone-cli --help
vphone-cli vm create --help

命令总览

boot：启动虚拟机

vphone-cli boot -c <bundle>/config.plist            # 启动指定 VM
vphone-cli boot -c <bundle>/config.plist --dfu      # DFU 模式（刷机用）
vphone-cli boot -c <bundle>/config.plist --resume   # 从挂起点恢复

启动是默认子命令，其 run() 为空，实际由 VPhoneAppDelegate 消费。vm launch 则 re-exec 自身二进制并透传 boot 参数。

vm 族：VM 生命周期

所有 vm 子命令共享 -l/--library-root（默认 ~/.vphone/VMs 或 $VPHONE_LIBRARY_ROOT）。

建机与基础管理

vphone-cli vm create -V dev                          # 端到端建机
vphone-cli vm create -V dev --stage-ipa App.ipa      # 附加待装 IPA（可重复，首启自动安装）
vphone-cli vm list                                   # 列出库内 VM（--json 输出结构化）
vphone-cli vm info <name>                            # 查看单个 VM 详情
vphone-cli vm new <name>                             # 创建空 bundle（--cpu/-m/-d 指定 CPU/内存/磁盘）
vphone-cli vm config <name> --cpu 8 --memory 8G      # 修改 CPU/内存
vphone-cli vm rename <old> <new>                     # 重命名
vphone-cli vm delete <name>                          # 删除（-f 跳过确认）

启动与停止

vphone-cli vm launch <name>                          # 启动（-- 后参数透传给 boot；-v/-vv/-vvv 调日志级别）
vphone-cli vm stop <name>                            # 停止（SIGINT，超时 -t 默认 20s 后 SIGKILL）

复制、快照与归档

vphone-cli vm clone <name> <new>                     # APFS 快速克隆（同设备身份，可直接启动）
vphone-cli vm snapshot save <name> --as <快照名>     # 整盘快照
vphone-cli vm snapshot load <快照名> --into <目标>   # 回滚快照
vphone-cli vm export <name> -o out.tgz               # 导出归档（--include-ipsw 带固件）
vphone-cli vm import -i out.tgz --name <name>        # 导入归档

guest 连接与诊断

vphone-cli vm ssh <name>                             # SSH 进 guest（需 brew 安装 sshpass）
vphone-cli vm scp <name> ...                        # 收发文件
vphone-cli vm check-boot <name>                     # 检查 boot.log（exit 0 成功 / 1 panic / 2 无结论）
vphone-cli vm check-ssh <name>                      # 探测 guest SSH 可达性

SSH 端口约定：0 = 每次启动自动分配临时端口（多 VM 并存推荐），未设置 = 默认 2222，其余值 = 固定端口。

cryptid 反检测（cryptid-redirect）

vphone-cli vm cryptid-redirect <name> --app com.example.app                          # 为已装 App 配置规则
vphone-cli vm cryptid-redirect <name> --app com.example.app --ipa App.ipa            # 连补丁带安装一步到位
vphone-cli vm cryptid-redirect <name> --app com.example.app --remove                 # 移除该 App 的规则

基于 PVFS 为 App 配置 cryptid=1 副本的 REDIRECT + HIDE 规则：App 自读二进制时看到的是"已加密"形态，规避越狱/脱壳检测。规则配置经 HostControl socket 直达运行中的 guest，无需 SSH 或 make target；带 --ipa 时自动停机改装、重装后随启动配置。仅 dev/jb/exp 变体可用（依赖 PVFS）。

fw / restore / cfw 族：固件与刷机

vphone-cli fw prepare                                # 下载/合并 iPhone + cloudOS IPSW 进 bundle（--list 列出可选配对）
vphone-cli fw patch -V dev                          # 按变体对启动链原地打补丁
vphone-cli restore --get-shsh                        # 抓取 SHSH blob（须先 DFU 启动）
vphone-cli restore --offline                         # 离线刷机（用缓存 SHSH）

CFW 类命令操作的是关机状态 VM 的磁盘：须先执行一次 make helper_install，且 VM 必须关机：

vphone-cli cfw install <name> -V dev                 # 完整 CFW 安装（含 boot snapshot 翻转）
vphone-cli cfw install <name> -V dev --stage-ipa App.ipa  # 附加待装 IPA（可重复）
vphone-cli cfw dt-patch <name>                       # 补丁 DeviceTree（--restore 还原）
vphone-cli cfw gpu-patch <name> --auto               # GPU bundle 补丁（重命名 AppleParavirtGPU）
vphone-cli cfw dsc-patch <name> coremotion           # 补丁盘载 dyld cache 中的组件
vphone-cli cfw kernel-patch <name> --dev             # 补丁 kernelcache 并写回 Preboot 卷（免 DFU 重刷，含 MetalPluginName 改写）

control 族：控制运行中的 guest

经 HostControl socket（默认 vm/vphone.sock）操作运行中的 VM，响应以 JSON 输出：

vphone-cli control tap 300 500                        # 点击（1290×2796 像素坐标）
vphone-cli control swipe 200 800 200 200              # 滑动（绝对坐标）
vphone-cli control swipe up 30                        # 滑动（相对语义：方向 direction/percent，支持 up/down/left/right）
vphone-cli control key home                           # 按键（home/power/volup/voldown）
vphone-cli control type "hello"                       # 输入文本
vphone-cli control screenshot shot.png --full          # 全分辨率截图
vphone-cli control app list --filter user             # 列出用户 App
vphone-cli control app launch <bundle-id>             # 启动 App（--url 携带 URL）
vphone-cli control install-ipa app.ipa                # 安装 IPA
vphone-cli control file ls /var/mobile                # guest 文件操作（get/put/mkdir/rm/mv/settime）
vphone-cli control clipboard get                      # 读剪贴板（set <文本> 写入）
vphone-cli control location set 39.9 116.4            # GPS 模拟（纬度 经度，--alt/--speed 等可选）
vphone-cli control ping                               # 连通性检查
vphone-cli control pvfs-list                          # 查看 PVFS 每进程文件视图规则
vphone-cli control pvfs-apply --file rules.conf       # 推送宿主侧规则文件（即时生效）
vphone-cli control pvfs-reload                        # 重读 guest 内 conf 并重推
vphone-cli control service list                       # 列出 guest 内 launchd 服务
vphone-cli control service restart <label>            # 启动/重启/停止/强杀服务（start/restart/stop/kill）
vphone-cli control service disable <label>            # 持久禁用服务（跨 VM 重启生效，≤32 label/次）
vphone-cli control service enable <label>             # 恢复被禁用的服务
vphone-cli control service disabled-list              # 列出被持久禁用的服务 label
vphone-cli control service-profile status             # 查看按 catalog 分组的服务禁用状态
vphone-cli control service-profile on                 # 按 catalog 分组批量禁用后台服务
vphone-cli control service-profile off                # 恢复全部 catalog 托管服务
vphone-cli control process kill <pid>                 # 向 guest 进程发信号（--signal KILL 强杀）
vphone-cli control list-processes                     # 列出 guest 内进程（pid/name/cpu/mem）
vphone-cli control guest-metrics                      # 取 guest 系统级指标（CPU/内存/进程数/uptime）
vphone-cli control guest-reboot                       # 用户态重启 guest（launchd 重建全部用户态进程，kernel 不动）

触控类命令默认回传一张截图，加 --no-screen 关闭。swipe 支持两种形式：绝对坐标（x1 y1 x2 y2）和相对语义（direction percent，direction 为 up/down/left/right）。PVFS 规则命令仅 dev/jb/exp 变体可用。service-profile 基于 config/services_catalog.json 分组批量禁用后台服务，禁用持久化跨重启。guest-reboot 后 vphoned ~40s 回归，期间其他 control 命令报 guest not connected 属预期。

forward 族：端口转发

管理运行中 VM 的 vsock 端口转发（不持久化，重启清零）：

vphone-cli forward add "tcp:8080->tcp:80"            # 添加转发（端口 0 = 临时端口）
vphone-cli forward add "socks5:1080"                 # SOCKS5 代理
vphone-cli forward list                              # 列出全部转发（--json 看诊断字段，含 last_relay_error）
vphone-cli forward remove fwd-1                      # 按 id 删除

远程 VM 的端口转发在 vphone-manager 的 Network tab（Port Forwards 面板）操作——guest 端口经节点 agent 中继映射到控制端本机回环。

network-* 族：网络遥测

vphone-cli network-status                            # 代理遥测状态摘要（--json）
vphone-cli network-flows                             # 列出网络流
vphone-cli network-events                            # 订阅遥测事件流
vphone-cli network-control --udp-policy block        # 更新运行时策略（direct/block）

环境诊断与工具

vphone-cli preflight                  # 宿主可启动性诊断（--assert-bootable 供脚本用）
vphone-cli setup                      # 自举/验证宿主 Python 环境（--force 重建）
vphone-cli build dropbear             # 交叉编译 iOS dropbear
vphone-cli build ios-tools            # 编译部署 guest 调试工具

通用约定

• 日志级别：-v / -vv / -vvv 逐级提升（工具细节 → guest 串口 → 内部 trace）。
• 参数来源：命令行旗标优先，缺省时读环境变量（如 VPHONE_LIBRARY_ROOT、IPHONE_SOURCE）。
• 资源定位：多数命令支持 -p/--project-root 覆盖资源目录，默认从二进制位置自动推断。
• 交互选择：省略 VM 名称时在终端弹出编号菜单选择。
• 超时对齐：control 的 account/file/install-ipa 等命令客户端超时特意大于服务端超时，避免客户端先超时产生伪"read failed"。