CLI 命令参考

vphone-cli 全部子命令速查：VM 生命周期、固件补丁、DFU 刷机、CFW 安装、guest 控制与端口转发。

CLI 命令参考

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

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

命令总览

分组	命令	作用
启动	`boot`	启动虚拟 iPhone（默认子命令，支持 `--dfu` / `--resume`）
VM 管理	`vm …`	建机、启动、停止、克隆、快照、导入导出等
固件	`fw prepare` / `fw patch`	固件下载合并 / 启动链补丁
刷机	`restore`	DFU 刷机（SHSH、离线刷入）
CFW	`cfw …`	host-mount CFW 安装与单组件补丁
guest 控制	`control …`	触控、截图、文件、App、账号等 guest 内操作
端口转发	`forward …`	运行中 VM 的端口转发管理
网络遥测	`network-status` 等 4 个	代理遥测与运行时策略
环境	`setup` / `preflight` / `build` / `amfidont`	宿主环境诊断与工具构建

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   # 从挂起点恢复

vm 族：VM 生命周期

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

建机与基础管理

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（-c/-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 翻转）；--stage-ipa 附加待装 IPA、--no-keyboard 跳过键盘扩展
vphone-cli cfw dt-patch <name>              # 补丁 DeviceTree（--restore 还原）
vphone-cli cfw gpu-patch <name> --auto      # GPU bundle 补丁
vphone-cli cfw dsc-patch <name> coremotion  # 补丁盘载 dyld cache 中的组件
vphone-cli cfw kernel-patch <name>          # 补丁 kernelcache 并写回（免 DFU 重刷）

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 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）
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 并重推

触控类命令默认回传一张截图，加 --no-screen 关闭。PVFS 规则命令仅 dev/jb/exp 变体可用（规则管理内置 guest 守护进程 vphoned，改动即时生效、无需重启 VM；conf 格式与动作语义见「guest 守护进程 vphoned」篇）。

forward 族：端口转发

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

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

远程 VM 的端口转发在 vphone-manager 的 Network tab（Port Forwards 面板）操作——guest 端口经节点 agent 中继映射到控制端本机回环，见「vphone-manager 多 VM 管理 GUI」与「集群」篇。

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 名称时在终端弹出编号菜单选择。