命令行
vmpal 是 VMPal 的命令行工具,用法类似 docker 或 gh。你可以在终端、自己的脚本和 CI 中使用它。它可以创建和启动虚拟机、在虚拟机中运行命令,以及把文件拷贝进出虚拟机。它还能把虚拟机的屏幕读取为由窗口、按钮和文字组成的列表,能截图,也能在虚拟机中点按和输入。此外,它还能创建并运行 VMPal Hub 中的脚本。
交给 AI 智能体
使用 vmpal 最快的方式,是交给你的编程智能体。VMPal 会向智能体提供与你的 VMPal 版本相符的 vmpal 完整帮助和指南。智能体会替你编写命令或脚本,并加以解释。如果它能使用这台 Mac 上的终端,还会直接运行它们。安装 vmpal 需要你的管理员密码,所以如果还没有安装,智能体会给出命令,由你自己运行。
- 在 VMPal 中打开 设置 › AI智能体,然后打开 允许这台Mac上的编程智能体管理所有虚拟机。这样智能体还能管理你的虚拟机和脚本。即使不打开这项设置,它也能讲解
vmpal。 - 点按 添加到Claude Code、添加到Codex、添加到Grok Build 或 添加到Antigravity。Cursor、VS Code、Kiro 等其他智能体请点按 其他…。如果列表中没有你的智能体,手动设置… 会显示需要添加的内容。然后重启智能体。
- 向它提出请求,例如:
- “给我介绍一下 VMPal 的命令行。”
- “设置一个 GitHub Actions 作业,在我的 Ubuntu 虚拟机的全新克隆中运行测试。”
- “写一个脚本,把这个项目拷贝到我的 Windows 虚拟机中并构建。”
安装
vmpal 内置在 VMPal 中。要使用它,请把它链接到 PATH 中的某个文件夹:
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/VMPal.app/Contents/Helpers/VMPalMachine.app/Contents/MacOS/VMPalMachine /usr/local/bin/vmpal
请创建链接,而不是拷贝文件。vmpal 通过这个链接找到 VMPal。没有链接时,请用完整路径加上 --cli 运行它:
"/Applications/VMPal.app/Contents/Helpers/VMPalMachine.app/Contents/MacOS/VMPalMachine" --cli <command>
请以当前登录这台 Mac 的用户身份运行 vmpal。如果 VMPal 没有运行,vmpal 会在后台打开它。
查看帮助
和大多数命令行工具一样,vmpal 内置了帮助。指南会一步步带你完成常见任务。
vmpal help # every command
vmpal help run # one command's options, and its guide
vmpal help ci # a guide: setup, ci, exec, cp, sign-in or ui
vmpal ui help # ui's own commands
命令列出了所有命令。CI/CD 介绍了如何让每个 CI 作业都在虚拟机的全新克隆中运行。
基础知识
- 指定虚拟机。 使用虚拟机的名称(
"Windows 11")、ID 或其.vmpal文件夹的路径。ID 的前 4 个或更多字符也可以。vmpal list会列出名称和 ID。在cp的<VM>:<path>中,请使用名称或 ID。 - 输出 为纯文本。
--json会把结果打印为一行 JSON,方便脚本读取。对于exec,它会在结束时输出完整结果,而不是边运行边输出。-q只打印 ID,适用于list、create、clone、script list、script run和script runs。 - 从不提问。
vmpal在命令行上从不停下来向你提问,因此可以放心地用在脚本和 CI 中。做不到某件事时,它会直接失败并说明原因。少数等待需要有人操作,例如 VMPal 无法自动完成的登录。当你让脚本在这台 Mac 上运行时,VMPal 会遵循你在这台 Mac 上的脚本中的选择。 - 超时。 等待达到
--timeout时会放弃。可以写成90(秒)、90s、10m、2h或1h30m,最长 24h。vmpal ui例外:它的--timeout以毫秒为单位,也可以写成10s,最长 45 秒。 - 智能体控制。 每台虚拟机都有一项设置,允许
vmpal和 AI 智能体在其中操作:设置 › AI智能体 › 允许智能体控制此虚拟机。exec、cp、run、ssh、ui和sign-in都需要它,等待虚拟机可以运行命令的操作(例如start --wait)也需要它。对于run,需要打开它的是被克隆的虚拟机。除非有人关闭过,否则它是打开的。vmpal set <VM> --agent-control on可以重新打开它。 - Mac 全局设置。
vmpal不需要 允许这台Mac上的编程智能体管理所有虚拟机。这项设置是给 AI 智能体用的。
退出码
和其他命令行工具一样,vmpal 用退出码告诉你的脚本或 CI 作业执行结果。
| 代码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | VMPal 或虚拟机拒绝了请求,或者等待超时放弃 |
| 2 | 命令行有误 |
exec 和 run 以所运行命令自身的退出码退出,因此测试失败时 CI 作业也会失败。它们还会使用以下代码:
| 代码 | 含义 |
|---|---|
| 1 | 命令的退出码超出 0 到 255 的范围,例如 Windows 的 0xC0000005。vmpal 会把它打印出来 |
| 124 | 命令运行超过了 --timeout |
| 125 | vmpal 无法运行该命令。对于 run,无法创建或启动克隆、或者拷贝失败时也是这个代码 |
| 128 + N | vmpal 被信号 N 终止 |
ssh 以 ssh 自身的退出码退出,无法连接时为 255。vmpal 无法启动 ssh 时,退出码为 125。
在虚拟机中运行命令
vmpal exec 在虚拟机中运行命令,就像 docker exec 在容器中运行命令一样。有几点与 Mac 上的 shell 不同:
- 没有 shell。
exec直接运行程序。如需使用管道、&&或变量,请自己启动 shell:vmpal exec "Ubuntu" -- /bin/sh -c 'make && make test'。在 Windows 中,请使用powershell.exe -Command '...'。 - 以谁的身份运行。 命令以登录虚拟机的用户身份运行。在 Linux 中,如果没有人登录,则以虚拟机的账户运行。在 Windows 中,命令以标准权限运行。
- 管理员。
--admin以 root 身份运行命令,类似sudo;在 Windows 中则以提升的权限运行,类似 以管理员身份运行。在 macOS 虚拟机中,--admin需要先在虚拟机中获得管理员批准,VMPal Tools 更新后还需要重新批准。vmpal help exec介绍了具体方法。 - 文本输出。
exec把输出当作 UTF-8 文本读取,这会改变二进制输出,因此请用cp拷贝二进制文件。 - 登录。 等待虚拟机可以运行命令的命令,也会在 Windows 或 macOS 的登录界面替你登录,包括
create --wait、start --wait和wait。它们使用 VMPal 保存的密码:由虚拟机输入密码,vmpal永远看不到它。--no-sign-in可以关闭此行为。 - 密码。 只有
info --show-password和tool --show-password会打印虚拟机的密码。钥匙串无法保存新虚拟机的密码时,create也会把它打印出来。create --password-file <path>会把密码写入一个只有你能读取的文件。 - VMPal Tools。 VMPal Tools 是 VMPal 在每台虚拟机中的辅助程序。运行超过 10 分钟的命令、
--env和实时输出,需要 macOS 中的 VMPal Tools 0.34、Linux 中的 0.35 和 Windows 中的 0.37。VMPal 会在虚拟机启动时更新 VMPal Tools。 - “仅终端”虚拟机。
vmpal create <system> --terminal-only会安装不带桌面的 Linux。这类虚拟机显示为 VMPal 终端窗口中的一个标签页。vmpal systems会说明哪些系统支持这种方式。vmpal ssh <VM>用这台 Mac 的ssh登录它。与exec不同,它提供输入和终端。
脚本
VMPal 的 Hub 保存着你的脚本,并在你需要时运行它们。每个脚本在哪里运行由你选择:
| 选项 | 运行位置 |
|---|---|
--run-in <VM> |
每次运行都使用该虚拟机的一个全新克隆,就像干净的 CI 运行器 |
--run-in-place <VM> |
虚拟机本身 |
--host |
这台 Mac,在这台 Mac 上的脚本允许的范围内 |
vmpal script create "Test App" --file test-app.sh --run-in "Ubuntu" # a fresh clone of Ubuntu each run
vmpal script run "Test App" --wait # run it now, and exit with its status
vmpal script log "Test App" # the run's output