Vmctl

vmctl

**English** | [简体中文](README.zh-CN.md)

**A cross-platform agent skill for controlling local VMware Workstation virtual machines.**

`vmctl` wraps VMware's `vmrun` CLI so that AI coding agents (Kimi Code, Claude Code, Codex, or any agent that loads `.agents/skills` skills) can power VMs on/off, manage snapshots, and query state — from **Windows (Git Bash)** or **WSL**, with zero manual configuration.

vmctl start UbuntuServer1          # power on, headless
vmctl stop "Windows Server 2019"   # graceful shutdown
vmctl snapshot UbuntuServer1 pre-upgrade
vmctl revert UbuntuServer1 pre-upgrade

Why

• Agents frequently need to boot/stop VMs for testing, but vmrun paths differ per machine, its output is Windows-flavored (CRLF, GBK), and WSL adds path-translation and interop quirks.
• vmctl handles all of that once, so every agent on the machine gets a reliable VM toolbox.

Features:

• Power ops — start (headless or --gui), stop (soft/hard), suspend, reset, status, guest ip
• Snapshots — create / list (--tree) / revert / delete (--children)
• Smart VM discovery — reads VMware's inventory.vmls, matches by display name, vmx basename, or full path (any path style)
• Robust vmrun detection — env var → cache (~/.config/vmctl/paths) → PATH → common install locations on every drive → Windows registry; cached after first success
• Windows + WSL + Linux + macOS (Fusion) — automatic path/encoding/line-ending translation
• Idempotent power ops, clear exit codes (0 ok · 1 not found/failed · 2 ambiguous name · 64 usage)

Install

The repo *is* the skill — clone it into your agent skills directory.

**Windows (Git Bash):**

git clone https://github.com/realweng/vmctl ~/.agents/skills/vmctl
bash ~/.agents/skills/vmctl/scripts/vmctl.sh doctor

**WSL:**

git clone https://github.com/realweng/vmctl ~/.agents/skills/vmctl
bash ~/.agents/skills/vmctl/scripts/vmctl.sh doctor

**Linux / ma