跳到正文

文档 命令行 命令行

命令

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中询问 会针对脚本的每个版本询问你一次。
    • 关闭 会拒绝。