命令
vmpal 是 VMPal 的命令行工具,用法类似 docker 或 gh。本页先简要列出所有命令,再介绍值得了解的规则。运行 vmpal help <command> 可查看某个命令的选项,运行 vmpal help <topic> 可阅读指南。
表格中的 <VM> 指虚拟机的名称、ID 或 ID 的前 4 个或更多字符,或者其 .vmpal 文件夹的路径。vmpal list 会列出这些信息。
交给 AI 智能体
你的 AI 智能体可以替你完成这一切。VMPal 向它提供每个命令的帮助和指南,因此它可以替你编写或运行这些命令。把它连接到 VMPal,然后向它提出请求,例如:
- “哪个 vmpal 命令可以把文件夹拷贝到我的 Windows 虚拟机中?”
- “克隆我的 Ubuntu 虚拟机,在克隆中运行测试,然后删除它。”
虚拟机
| 命令 | 作用 |
|---|---|
vmpal list |
列出你的虚拟机,以及每台虚拟机的当前状态 |
vmpal info <VM> |
显示一台虚拟机的完整信息 |
vmpal systems |
列出可以安装的系统及其 ID,并说明哪些可以设为“仅终端” |
vmpal create <system> --wait |
创建虚拟机,并等待它安装完成、可以运行命令 |
vmpal create --file <path> |
从 IPSW 或 ISO 文件安装,而不是使用系统 ID |
vmpal create <system> --terminal-only |
安装不带桌面的 Linux |
vmpal create <system> --password-file <path> |
把新虚拟机的密码写入一个只有你能读取的文件 |
vmpal clone <VM> |
克隆一台已关机的虚拟机。克隆立即可用 |
vmpal clone <VM> --shut-down |
先将虚拟机关机,再克隆它 |
vmpal clone <VM> --start --wait |
同时启动克隆,并等待它可以运行命令 |
vmpal set <VM> --cpus 4 --memory 8 |
更改虚拟机的设置,例如硬件、共享文件夹、端口、网络和登录。vmpal help set 列出全部设置 |
vmpal set <VM> --display 1440x900@2x |
让虚拟机的显示器保持指定的尺寸(以点为单位)和缩放比例(1x 或 2x),无论在哪个屏幕上或在后台都不变。窗口会按比例缩放显示它,克隆也会保留这个设置。适用于 UI 测试和截图。window 会让显示器重新跟随窗口 |
vmpal set <VM> --render-scale 75 |
让 Windows 虚拟机的显示器按窗口每边 75% 或 50% 的尺寸渲染,再用 MetalFX 放大。对于受 GPU 限制的游戏,数值越低越流畅,画面也越柔和。100 恢复为全尺寸 |
vmpal set <VM> --user <name> |
告诉 VMPal 虚拟机中账户的名称,适用于不是由 VMPal 创建的账户,或在虚拟机中改过名的账户。它不会在虚拟机中重命名任何东西 |
vmpal delete <VM> |
把虚拟机移到废纸篓 |
vmpal delete <VM> --force |
先将正在运行的虚拟机强制关机,再移到废纸篓 |
vmpal delete <VM> --permanently |
永久删除,不经过废纸篓 |
vmpal import <path> |
导入来自另一台 Mac 的 .vmpalvm 文件,或 Parallels 虚拟机。.vmpal 文件夹会在原位置添加 |
vmpal move <VM> <location> |
把已关机的虚拟机移到 VMPal 的另一个位置。--wait 会等待移动完成 |
vmpal compress <VM> |
把虚拟机打包成 .vmpalvm 文件,以便在另一台 Mac 上使用。除非用 --output 另行指定,否则文件会放在桌面上 |
vmpal cancel <VM> |
停止虚拟机的下载或移动 |
vmpal cancel |
停止正在进行的导入或压缩 |
vmpal help create 列出了 create 的其他选项:--name、--cpus、--memory、--disk、--location、--user、用于 Linux 的 --install-updates、用于 Windows 的 --sign-in-automatically、--start-at-login,以及 --no-agent-control。
CPU、内存、GPU 和其他一些设置要等虚拟机关机并重新启动后才会生效。vmpal restart <VM> --apply-settings 可以替你完成这一步。
电源
| 命令 | 作用 |
|---|---|
vmpal start <VM> --wait |
启动虚拟机,并等待它可以运行命令 |
vmpal start <VM> --background |
启动虚拟机,但不打开它的窗口。vmpal show 可以打开窗口 |
vmpal start <VM> --recovery |
以 macOS 恢复模式启动 macOS 虚拟机 |
vmpal stop <VM> |
将虚拟机关机 |
vmpal stop <VM> --force |
立即强制关机,就像拔掉电源 |
vmpal pause <VM> |
暂停正在运行的虚拟机 |
vmpal resume <VM> |
让已暂停的虚拟机继续运行 |
vmpal suspend <VM> |
把虚拟机的会话保存到磁盘并关闭它。vmpal start 会从中断的地方继续 |
vmpal restart <VM> |
重启虚拟机中的系统 |
vmpal restart <VM> --apply-settings |
先关机再重新启动,让需要重启才能生效的设置生效 |
vmpal restart <VM> --reset |
立即重启,就像按下重置按钮 |
vmpal show <VM> |
把正在运行的虚拟机的窗口移到最前面 |
vmpal show <VM> --apps-on-mac |
把 Windows 虚拟机中的应用分别显示为独立的 Mac 窗口,与 显示 › 在Mac上运行Windows应用 相同。开启 GPU 加速的 Linux 虚拟机也可以这样,与 显示 › 在Mac上运行Linux应用 相同。虚拟机下次也会以这种方式打开 |
vmpal show <VM> --window |
改回显示虚拟机的窗口,而不是它的各个应用 |
vmpal wait <VM> |
等待虚拟机可以运行命令。默认 10 分钟后放弃 |
vmpal wait <VM> --until stopped |
改为等待它变为 stopped。--until 还接受 running 和 installed |
等待的时限:start、stop 和 clone --start 为 5 分钟;start --wait、clone --start --wait、restart --wait 和 wait 为 10 分钟;create --wait、move --wait 和 compress --wait 为 2 小时。--timeout 可以设置其他时限,最长 24 小时。
虚拟机内部
| 命令 | 作用 |
|---|---|
vmpal exec <VM> -- <command> |
在虚拟机中运行命令,类似 docker exec。输出会实时显示 |
vmpal exec <VM> --arch x64 -- <command> |
对于同时为 arm64 和 x64 构建的程序,运行其 x64 部分。--arch arm64 运行另一部分 |
vmpal cp <from> <to> |
把文件拷贝进或拷贝出虚拟机,类似 docker cp。虚拟机一侧写作 <VM>:<path> |
vmpal run <VM> -- <command> |
在已关机虚拟机的全新克隆中运行命令,就像全新的 CI 运行器。--copy-in 和 --copy-out 用于拷贝文件。之后 VMPal 会删除克隆。CI/CD 介绍了用法 |
vmpal ssh <VM> |
用这台 Mac 的 ssh 登录“仅终端”Linux 虚拟机。你会得到输入和终端 |
vmpal ssh <VM> -- <command> |
通过 ssh 在其中运行命令 |
vmpal ssh <VM> --tty -- <command> |
同时为命令提供终端,类似 ssh -t,适用于 top 等程序 |
vmpal sign-in <VM> |
用 VMPal 保存的密码在登录界面登录 |
vmpal ui <VM> ... |
读取屏幕上的窗口、按钮和文字,以及 Windows 的 UAC 等系统提示(vmpal ui <VM> tree),还能点按、输入和截图。vmpal ui help 介绍了用法 |
vmpal status <VM> |
显示虚拟机能否运行命令、它的屏幕,以及谁在控制它的输入 |
vmpal send-files <VM> <path>... |
把文件放到虚拟机用户的桌面上,就像把文件拖放到那里一样 |
vmpal reinstall-tools <VM> |
在虚拟机中重新安装 VMPal Tools |
快照
快照会保存虚拟机当前的状态,以便日后回到这个状态。
| 命令 | 作用 |
|---|---|
vmpal snapshot <VM> [name] |
拍摄快照 |
vmpal snapshots <VM> |
列出虚拟机的快照 |
vmpal revert <VM> [name] |
复原到某个快照。不指定名称时,复原到最新的快照 |
vmpal revert <VM> --snapshot-first |
先把当前状态保存为新快照,再复原 |
vmpal rename-snapshot <VM> <snapshot> <new name> |
重命名快照 |
vmpal delete-snapshot <VM> <snapshot> |
永久删除快照 |
Hub
这些命令用于管理 VMPal Hub 中的脚本。脚本是由 VMPal 保存并替你运行的 shell 或 PowerShell 脚本。你的 AI 智能体可以用 VMPal 的 MCP 工具完成同样的操作。
<script> 是脚本的名称(不区分大小写)或 ID。
| 命令 | 作用 |
|---|---|
vmpal script create <name> --file <path> |
把脚本添加到 VMPal 的 Hub。--file - 从标准输入读取脚本。如果名称与其他脚本重复,会加上编号,例如“Test App 2” |
vmpal script edit <script> |
更改脚本的名称(--name)、内容(--file)、设置或运行位置。--no-targets 让它不在任何地方运行 |
vmpal script show <script> |
显示脚本的设置、运行位置、最近 5 次运行及其日志路径,以及脚本内容 |
vmpal script list |
列出所有脚本,以及它们的语言、颜色和运行位置 |
vmpal script run <script> --wait |
立即运行脚本,并等待各次运行结束 |
vmpal script stop <script> |
停止脚本正在等待或正在进行的运行。--run <ID> 只停止其中一次 |
vmpal script runs <script> |
列出脚本的运行记录,最新的在前,包括 ID、状态和失败原因:最近结束的 50 次,以及正在等待或正在进行的运行。--limit <n> 设置数量,最多 100 |
vmpal script log <script> |
打印最新一次运行的日志。--run <ID> 打印另一次运行的日志。--tail <bytes> 只打印日志的末尾 |
vmpal script duplicate <script> |
复制脚本,副本在 Hub 列表中紧跟在原脚本之后 |
vmpal script move <script> --before <script> |
在 Hub 的列表中上下移动脚本。--to-end 把它移到末尾 |
vmpal script delete <script> |
删除脚本及其运行记录和日志。正在进行的运行会停止 |
以下选项用于选择脚本的运行位置,script create、script edit 和 script run 都接受它们。
| 选项 | 脚本的运行位置 |
|---|---|
--run-in <VM> |
虚拟机的全新克隆,即用完即弃的副本,就像全新的 CI 运行器 |
--run-in-place <VM> |
虚拟机本身 |
--host |
这台 Mac,以你的身份运行 |
script run只在本次运行中使用这些选项。script edit用这些选项替换原来的运行位置。- 一次运行最多等待其虚拟机 30 分钟,例如等待虚拟机关机后再克隆它。
以下选项用于更改脚本的设置,适用于 script create 和 script edit:
| 选项 | 设置的内容 |
|---|---|
--language powershell |
设为 PowerShell 脚本。.ps1 文件本身就是 PowerShell 脚本 |
--timeout <duration> |
一次运行最长可以持续多久。默认 1 小时,最长 24 小时 |
--color <color> |
为脚本在 Hub 中的行着色:red、orange、yellow、green、mint、teal、cyan、blue、indigo、purple、pink、brown 或 gray。在 script edit 中,--color none 会去掉颜色 |
script run --wait 的退出方式与 CI 作业相同,因此它的退出码会告诉你各次运行是否成功。在 script run 中,--timeout 是 vmpal 等待各次运行的时长,而不是一次运行可以持续的时长。默认情况下,它会等待脚本的超时时间再加 35 分钟。
手机和平板电脑
用名称指定 VMPal“远程”部分中的 iPhone、iPad、iOS 模拟器或 Android 设备,参见手机和平板电脑。vmpal start <phone> 会连接设备,之后 vmpal ui <phone> 就能像操作虚拟机一样使用它的屏幕。
| 命令 | 作用 |
|---|---|
vmpal device <phone> install <path> |
安装应用:为该 iPhone 签名的 .app 或 .ipa、模拟器的 .app,或 Android 的 .apk |
vmpal device <phone> launch <bundle ID> |
启动应用(如果它正在运行,会先结束它),并保留它打印的输出。应用自身的参数放在 -- 之后。--no-console 不保留任何输出 |
vmpal device <phone> logs <bundle ID> |
显示自 launch 启动应用以来它打印的内容。在 Android 上是它的 logcat。--lines <n> 可调整显示的行数 |
vmpal device <phone> crashes [<bundle ID>] |
显示应用的崩溃报告,最新的在前。vmpal device <phone> crash <report> 读取其中一份 |
vmpal device <phone> apps |
显示已安装的应用,不含系统应用 |
vmpal device <phone> terminate <bundle ID> |
结束应用。uninstall 会卸载它 |
vmpal device <phone> rotate landscape-left |
旋转设备:portrait、landscape-left、landscape-right 或 upside-down |
vmpal device <phone> button home |
按下按钮:home、volume-up 或 volume-down,在 Android 上还有 back、recents 或 power |
vmpal device <phone> open-url <url> |
打开网页,或应用自己的链接 |
vmpal device <phone> pinch --scale 2 |
用两根手指捏合,默认在屏幕中央,也可以用 --x 和 --y 指定位置(0 到 1)。大于 1 表示放大 |
vmpal device <phone> release |
结束 VMPal 在 iPhone 或 iPad 上的测试会话,以便 Xcode 在上面运行你自己的 UI 测试 |
其他
| 命令 | 作用 |
|---|---|
vmpal library |
显示 VMPal 的位置、系统映像文件,以及正在进行的下载、导入或压缩 |
vmpal add-location <path> |
添加一个供 VMPal 存放虚拟机的文件夹,例如在另一个磁盘上 |
vmpal remove-location <path> |
把文件夹从 VMPal 的列表中移除。其中的虚拟机仍留在原处 |
vmpal delete-base-os <id> |
把系统映像文件移到废纸篓 |
vmpal diagnostics |
把 VMPal 的日志、崩溃报告和虚拟机设置打包成 zip 文件用于错误报告,并告诉你如何发送。不包含密码 |
vmpal diagnostics <VM> |
对单台虚拟机执行相同操作:包含它的完整日志,且只包含它的文件 |
vmpal diagnostics --problem <text> |
为错误报告描述出了什么问题 |
vmpal tool <name> [<json>] |
按名称调用 VMPal 的某个 MCP 工具,参数以 JSON 形式给出。--file <path> 从文件读取参数,- 表示从标准输入读取。--show-password 会在结果中保留虚拟机的密码 |
vmpal help |
列出所有命令 |
vmpal help <command> |
显示某个命令的选项和指南 |
vmpal help <topic> |
阅读指南:setup、ci、exec、cp、sign-in 或 ui |
值得了解的规则
在虚拟机中运行命令
- 智能体控制。
exec、cp、run、ssh、ui和sign-in只有在虚拟机允许智能体控制时才能使用,等待虚拟机可以运行命令的操作(例如start --wait)也是如此。除非有人关闭过,否则它是打开的。要重新打开它,请运行vmpal set <VM> --agent-control on。 - 没有 shell。
exec直接运行程序本身,不经过 shell。如需使用管道和&&,请自己启动 shell:vmpal exec "Ubuntu" -- /bin/sh -c 'make && make test'。 - 文本输出。
exec把输出当作文本读取,这会改变二进制输出。请用cp拷贝二进制文件。 - 管理员。
--admin以管理员身份运行命令。在 macOS 虚拟机中,必须先由管理员在虚拟机中批准。vmpal help exec介绍了方法。 - 时间限制。
exec会在 2 小时后停止命令,cp则是 1 小时。--timeout可以设置其他时限,最长 24 小时。较旧的 VMPal Tools 只允许 10 分钟。 - 没有输入。 通过
exec运行的命令得不到任何输入。在“仅终端”虚拟机中,vmpal ssh可以提供输入。 - 拷贝文件夹。
cp的行为类似cp -R。例如,vmpal cp . "Ubuntu:src"会把当前文件夹的内容拷贝到src中。 - 登录。 Windows 只有在有人登录后才会运行命令。因此,
create --wait、start --wait、wait、clone --start --wait、restart --wait和run会用 VMPal 保存的密码替你登录,在 Windows 或 macOS 的登录界面都是如此。--no-sign-in可以关闭此行为。要让 Windows 每次启动时自动登录,请运行vmpal set <VM> --sign-in-automatically on。
退出码
和任何命令行工具一样,退出码会告诉你的脚本或 CI 作业命令是否成功。
| 命令 | 退出码 |
|---|---|
exec 和 run |
所运行命令自身的退出码。超时为 124,vmpal 无法运行命令时为 125,收到信号 N 时为 128 + N;命令的退出码超出 0 到 255 的范围时为 1,例如 Windows 的 0xC0000005,vmpal 会把它打印出来 |
ssh |
ssh 自身的退出码。无法连接时为 255,vmpal 无法启动 ssh 时为 125 |
script run --wait |
所有运行都成功时为 0。否则,只有一次运行时为该次运行自身的退出码,其他情况为 1 |
| 其他所有命令 | 成功时为 0,失败时为 1,命令行有误时为 2 |
脚本
- 这台 Mac 上的脚本以你的身份运行。 因此,每当
vmpal要让脚本在这台 Mac 上运行时,VMPal 都会检查它的这台 Mac 上的脚本设置。这包括--host、对在这台 Mac 上运行的脚本执行script run,以及为这类脚本提交新内容。这项设置有三个选项:- 允许(由智能体询问你) 是默认选项,不询问就直接放行。
- 在VMPal中询问 会针对脚本的每个版本询问你一次。
- 关闭 会拒绝。