vmctl

vmctl is a Windows command-line interface for controlling VMware Workstation virtual machines. It reads VMware's registered VM inventory and uses vmrun.exe to list, start, stop, wait for, and delete VMs.

Run it without arguments for an interactive menu, or use subcommands in scripts and terminal workflows.

Features

• Lists every registered VM and its current power state
• Starts VMs headlessly by default, with an optional GUI
• Stops VMs gracefully by default, with an optional hard power-off
• Waits until a guest has an IP address and responds to ping
• Produces JSON inventory output for scripts
• Confirms destructive deletes and reports snapshots that will also be removed
• Treats repeated start and stop operations as successful no-ops

Requirements

• Windows x64
• VMware Workstation with at least one registered VM
• .NET 10 SDK when building from source
• VMware Tools installed and running in guests when using automatic IP detection with wait

vmctl locates vmrun.exe in the standard VMware Workstation installation directory, on PATH, or through VMware's Windows registry entry.

Quick Start

Build and run the interactive menu:

dotnet run --project .\src\VmCtl

Run a subcommand by placing its arguments after --:

dotnet run --project .\src\VmCtl -- list
dotnet run --project .\src\VmCtl -- start "Ubuntu Dev" --wait

If you have a published executable, add its directory to PATH and invoke it directly:

vmctl list
vmctl start "Ubuntu Dev" --wait

Commands

Interactive Mode

vmctl

The interactive menu supports listing, starting, stopping, waiting for, and deleting registered VMs.

List VMs

vmctl list
vmctl list --json

--json returns a sorted array with each VM's name, status, and .vmx path.

Start a VM

vmctl start <name-or-path> [--gui] [--wait] [--timeout <seconds>] [--ip <address>]

• VMs start headlessly unless --gui is supplied.
• --wait waits for the guest to become reachable.
• --timeout controls the wait timeout and defaults to 120 seconds.
• --ip skips VMware Tools IP detection and pings a known guest address directly. It is only used with --wait.

Examples:

vmctl start "Ubuntu Dev"
vmctl start "Windows Lab" --gui
vmctl start "Ubuntu Dev" --wait --timeout 300
vmctl start "Minimal Linux" --wait --ip 192.168.1.50

Starting an already-running VM succeeds without starting it again.

Wait for a VM

vmctl wait <name-or-path> [--timeout <seconds>] [--ip <address>]

By default, vmctl waits for VMware Tools to report the guest IP, then polls that address with ICMP ping. Supply --ip when the guest is reachable but VMware Tools is unavailable. The VM must already be running.

Stop a VM

vmctl stop <name-or-path> [--hard]

The default is a graceful guest shutdown. --hard powers the VM off immediately. Stopping an already-stopped VM succeeds without invoking another stop.

Delete a VM

vmctl delete <name-or-path>
vmctl delete <name-or-path> --yes

Deletion permanently removes the VM and its files. vmctl refuses to delete a running VM, displays any snapshots that will also be deleted, and asks for confirmation by default. Use --yes or -y to skip the prompt in automation.

VM Names and Paths

Commands accept either:

• An exact, case-insensitive VMware inventory display name
• A direct path to a .vmx file

Names containing spaces must be quoted. Partial names are not executed automatically; when possible, vmctl reports matching names as suggestions. If duplicate display names exist, use the full .vmx path to disambiguate them.

vmctl start "Ubuntu Dev"
vmctl start "C:\Virtual Machines\Ubuntu Dev\Ubuntu Dev.vmx"

VM inventory is read from the current Windows user's VMware inventory file:

%APPDATA%\VMware\inventory.vmls

Build and Test

From the repository root:

dotnet restore .\VmCtl.slnx
dotnet build .\VmCtl.slnx
dotnet test .\VmCtl.slnx

Publish a Windows x64 executable:

dotnet publish .\src\VmCtl\VmCtl.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o .\publish\win-x64

The published executable is written to publish\win-x64\vmctl.exe.

Notes

• vmctl targets VMware Workstation (vmrun -T ws); it does not target VMware Fusion or Player.
• Readiness checks require ICMP ping to be allowed by the guest and network unless another known reachable IP is supplied.
• Commands return a non-zero exit code when resolution, VMware, inventory, or readiness operations fail.