跳到正文

文档 命令行

命令行

vmpal 是 VMPal 的命令行工具,用法类似 docker 或 gh。你可以在终端、自己的脚本和 CI 中使用它。它可以创建和启动虚拟机、在虚拟机中运行命令,以及把文件拷贝进出虚拟机。它还能把虚拟机的屏幕读取为由窗口、按钮和文字组成的列表,能截图,也能在虚拟机中点按和输入。此外,它还能创建并运行 VMPal Hub 中的脚本。

交给 AI 智能体

使用 vmpal 最快的方式,是交给你的编程智能体。VMPal 会向智能体提供与你的 VMPal 版本相符的 vmpal 完整帮助和指南。智能体会替你编写命令或脚本,并加以解释。如果它能使用这台 Mac 上的终端,还会直接运行它们。安装 vmpal 需要你的管理员密码,所以如果还没有安装,智能体会给出命令,由你自己运行。

  1. 在 VMPal 中打开 设置 › AI智能体,然后打开 允许这台Mac上的编程智能体管理所有虚拟机。这样智能体还能管理你的虚拟机和脚本。即使不打开这项设置,它也能讲解 vmpal。
  2. 点按 添加到Claude Code、添加到Codex、添加到Grok Build 或 添加到Antigravity。Cursor、VS Code、Kiro 等其他智能体请点按 其他…。如果列表中没有你的智能体,手动设置… 会显示需要添加的内容。然后重启智能体。
  3. 向它提出请求,例如:
    • “给我介绍一下 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

脚本介绍了脚本的工作方式。命令列出了其余命令。