Skip to content
Back to search

vmware-skill

Control VMware Workstation Pro VMs from Claude Code via vmrun/vmcli — no MCP server needed

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pedoc--vmware-skill/badge.svg)](/listings/pedoc--vmware-skill)

HTML

<a href="/listings/pedoc--vmware-skill"><img src="/api/listings/pedoc--vmware-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills add pedoc/vmware-skill

Add `-g` to install globally (user-level) rather than into the current project. The skill lands in `~/.agents/skills/vmware/`, symlinked into each detected agent's skill directory — Claude Code included.

To update it later:

npx skills update vmware -g

CLI only (for scripting)

Run straight from GitHub — no npm publish required:

npx --allow-git=all github:pedoc/vmware-skill vm list --power

> `--allow-git=all` is needed because recent npm versions default `allow-git` to `none` > (a supply-chain hardening change). `npx github:...` is refused without it.

Or clone and run directly:

git clone https://github.com/pedoc/vmware-skill.git
node vmware-skill/skills/vmware/scripts/vmware.js vm list --power

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 300 lines
  1. # vmware-skill
  2. Control VMware Workstation Pro virtual machines from Claude Code — **no MCP server, no daemon**.
  3. Wraps VMware's own `vmrun.exe` / `vmcli.exe` / `vmrest.exe` behind a single zero-dependency
  4. Node script. Commands run and exit; nothing stays resident.
  5. Every command was checked against a live VMware Workstation Pro 26.0.1 install, on both a
  6. Windows Server guest and a Rocky Linux guest.
  7. ## Install
  8. ```bash
  9. npx skills add pedoc/vmware-skill
  10. ```
  11. Add `-g` to install globally (user-level) rather than into the current project.
  12. The skill lands in `~/.agents/skills/vmware/`, symlinked into each detected agent's
  13. skill directory — Claude Code included.
  14. To update it later:
  15. ```bash
  16. npx skills update vmware -g
  17. ```
  18. ### CLI only (for scripting)
  19. Run straight from GitHub — no npm publish required:
  20. ```bash
  21. npx --allow-git=all github:pedoc/vmware-skill vm list --power
  22. ```
  23. > `--allow-git=all` is needed because recent npm versions default `allow-git` to `none`
  24. > (a supply-chain hardening change). `npx github:...` is refused without it.
  25. Or clone and run directly:
  26. ```bash
  27. git clone https://github.com/pedoc/vmware-skill.git
  28. node vmware-skill/skills/vmware/scripts/vmware.js vm list --power
  29. ```
  30. ## Requirements
  31. - **VMware Workstation Pro 17+** (verified on 26.0.1)
  32. - **Node.js 18+**
  33. - `vmrun.exe` / `vmcli.exe` — auto-detected in the standard install paths, or set
  34. `VMRUN_PATH` / `VMCLI_PATH`
  35. - `vmrest.exe` — only for the few operations the CLIs can't do (see below)
  36. ## Usage
  37. ```sh
  38. node skills/vmware/scripts/vmware.js vm list --power
  39. node skills/vmware/scripts/vmware.js power status "Ubuntu 22 x64"
  40. node skills/vmware/scripts/vmware.js snapshot take "Win10" "before-upgrade"
  41. node skills/vmware/scripts/vmware.js help <group>
  42. ```
  43. Virtual machines are referenced **by name or by `.vmx` path** — both work:
  44. ```sh
  45. node scripts/vmware.js power status "Win10"
  46. node scripts/vmware.js power status "K:/VirtualMachines/Win10/Windows 10 x64.vmx"
  47. ```
  48. Name resolution reads VMware's own `inventory.vmls`, so **vmrest does not need to be running**.
  49. ## Command groups
  50. | Group | Does |
  51. |---|---|
  52. | `vm` | `list` / `info` (full config dump) / `running` |
  53. | `power` | `status` `start` `stop` `reset` `suspend` `pause` `unpause` |
  54. | `snapshot` | `list` `take` `revert` `delete` `clone` — **by name**, uid auto-resolved |
  55. | `guest` | in-guest `ls` `mkdir` `rm` `mv` `copy-to` `copy-from` `put-dir` `get-dir` `exec` `run` `script` `ps` `kill` `exists` `dir-exists` `ready` `env` |
  56. | `shared` | shared folders `list` `add` `remove` `set` `enable` `disable` |
  57. | `chipset` | `query` `cpu` `memory` `cores` |
  58. | `config` | read/write `.vmx` config params |
  59. | `disk` | `list` `create` `extend` `remove` |
  60. | `nic` | `list` `set-type` `set-present` `set-connected` `set-device` `set-network` `purge` `add` |
  61. | `net` | host networks `list`, port forwarding `list`/`set`/`delete` |
  62. | `tools` | `status` `install` `upgrade` |
  63. | `screen` | `capture` (screenshot — **no guest password needed**) / `keys` |
  64. | `device` | `connect` `disconnect` named devices |
  65. | `vars` | `read` `write` VM variables |
  66. | `template` | `create` `deploy` |
  67. | `clone` / `vmnew` | clone / create VMs |
  68. | `rest` | raw REST API access |
  69. | `raw` | escape hatch: `raw vmcli ...` / `raw vmrun ...` |
  70. ## Guest credentials
  71. Operations inside the guest OS need the **guest's** login, passed via environment variables
  72. (not argv — argv lands in the process list and shell history):
  73. ```sh
  74. export VMWARE_GUEST_USER=root
  75. export VMWARE_GUEST_PASS='...'
  76. node scripts/vmware.js guest ps "Ubuntu 22 x64"
  77. ```
  78. Requires VMware Tools installed and running in the guest.
  79. **Exception:** `screen capture` uses `vmcli MKS`, which needs no credentials.
  80. Passwords are masked as `***` in every command line this script prints, so a timeout or error
  81. message never leaks them into logs or transcripts.
  82. ## Running work inside the guest
  83. **`guest exec` is the one you want** — it brings back stdout+stderr and propagates the guest's
  84. exit code:
  85. ```sh
  86. node scripts/vmware.js guest exec "Win10" "dir C:\\Windows"
  87. node scripts/vmware.js guest exec "Ubuntu 22 x64" "systemctl is-active nginx" # exit code passes through
  88. ```
  89. The command is uploaded as a small script file and run from there, so `>`, `|`, `&&` and quoting
  90. all behave normally — nothing rewrites your command line.
  91. `guest run` is a thin `vmrun` passthrough that **does not capture output**; use it only for
  92. interactive programs or ones that log to a file themselves.
  93. `guest script <vm> <interpreter> <body>` uploads the body as a temp file and executes it,
  94. deliberately **not** via `runScriptInGuest` — that call hangs forever against a Windows guest
  95. (verified: `runScriptInGuest <vmx> cmd.exe "echo hi"` never returns; the `cmd.exe /c` form
  96. reports `A file was not found`). On Windows the interpreter argument is ignored and the body
  97. runs as a `.bat` through `cmd.exe /c`. It does not return the script's output either — use
  98. `guest exec` for that.
  99. `guest exists` / `guest dir-exists` are queries, not assertions: an absent path prints `false`
  100. and exits 0.
  101. `guest ready` waits until guest operations actually work. Check `ready: true` rather than
  102. `tools status` — a wedged guest channel still reports `running`, and only a real round trip
  103. tells you it's usable:
  104. ```sh
  105. node scripts/vmware.js guest ready "Win10" --timeout 300
  106. ```
  107. ## Console: screenshots and keystrokes
  108. `screen` goes through `vmcli MKS`, so it needs **no guest credentials** and works on a plain text
  109. console — including before VMware Tools is installed:
  110. ```sh
  111. node scripts/vmware.js screen capture "Rocky9" "C:/shots/boot.png"
  112. node scripts/vmware.js screen keys "Rocky9" "root<Enter>"
  113. node scripts/vmware.js screen keys "Rocky9" "$VMWARE_GUEST_PASS<Enter>"
  114. ```
  115. Expand the password from the environment rather than typing it into the command, so it stays out
  116. of shell history.
  117. Keystrokes are typed literally; only `<Enter>`, `<Tab>` and `<Space>` are translated. Arrow keys
  118. and `<Esc>` are rejected by MKS and fall back to `vmrun typeKeystrokesInGuest`, which often fails
  119. on a text console with `Insufficient permissions in the host operating system`.
  120. This is the way in when a guest has no Tools and no SSH yet: log in at the console, bring the
  121. network up, then switch to SSH or install Tools.
  122. ## Git Bash / MSYS2 on Windows
  123. Claude Code on Windows runs commands through Git Bash, which rewrites `/c`, `/tmp` and friends
  124. into `C:/...`. Set this first:
  125. ```sh
  126. export MSYS_NO_PATHCONV=1
  127. ```
  128. Without it, `guest exec vm "/c dir"` reaches the guest as `C:/ dir` and fails in a way that
  129. looks like a timeout. Convert host paths handed to the guest with `cygpath -w`.
  130. ## Timeouts
  131. Every command accepts `--timeout <seconds>` (default 120s; file transfers default to 1 hour).
  132. `--timeout 0` disables the limit:
  133. ```sh
  134. node scripts/vmware.js snapshot revert "Win10" "clean" --timeout 600
  135. node scripts/vmware.js guest exec "Ubuntu 22 x64" "make -j4" --timeout 0
  136. ```
  137. If a guest command genuinely needs the literal string `--timeout`, separate it with `--`.
  138. ## REST API (optional)
  139. The CLIs can't add a NIC, create a virtual network, clone a VM, or change CPU/memory — those
  140. need the REST API. It's optional; everything else works without it.
  141. ```sh
  142. "C:/Program Files/VMware/VMware Workstation/vmrest.exe" -C # one-time credential setup
  143. "C:/Program Files/VMware/VMware Workstation/vmrest.exe" # run the service
  144. export VMWARE_REST_USER=...
  145. export VMWARE_REST_PASSWORD=...
  146. node scripts/vmware.js rest status
  147. ```
  148. Two kinds of credentials, deliberately named apart:
  149. | Variables | What they unlock |
  150. |---|---|
  151. | `VMWARE_GUEST_USER` / `VMWARE_GUEST_PASS` | login inside the guest OS (`guest` group) |
  152. | `VMWARE_REST_USER` / `VMWARE_REST_PASSWORD` | vmrest HTTP basic auth (`rest` group) |
  153. | `VMWARE_REST_HOST` / `VMWARE_REST_PORT` | vmrest address, default `127.0.0.1:8697` |
  154. Generic names like `VMWARE_USERNAME` / `VMWARE_PASSWORD` are **not** read: they collide
  155. with unrelated tooling and don't say whether they mean the guest or the REST API.
  156. `vmrest -C` is interactive: it asks for a username and a new password twice. Password rules:
  157. ≥8 characters, at least one lowercase letter, one digit, and one special character from
  158. ``!#$%&'()*+,-./:;<=>?@[]^_`{|}~``.
  159. ## Gotchas baked into this skill
  160. These were verified against a live install, not inferred from docs:
  161. 1. **`vmcli` arguments are mostly positional**, not `-flag value`:
  162. - `Ethernet SetPresent ethernet0 true` ✅ — `Ethernet SetPresent -i 0 -e true` ❌ (`Invalid/unrecognized argument "-e"`)
  163. - `Snapshot Take <name>` ✅ — `-n` is `--native`, not the name
  164. - `ConfigParams SetEntry <name> <value>` ✅ — not `-k`/`-v`
  165. - in `Guest`, `-p` is the **password**; the program path is positional
  166. - `Disk Create` needs `-f <file.vmdk>`; `-t` is an integer type (0–3), not `"scsi"`
  167. - `Guest ps -f` documents `<0,1,2>` but only accepts `toml|yaml|json`
  168. - `VM Create -g` documents numeric ids but only accepts a guestOS name — this skill uses `-c`
  169. 2. **vmcli exits 0 on success, 127 on failure**; errors go to stderr.
  170. 3. **vmcli output is a YAML subset** — parsed to JSON here. Table output stays verbatim.
  171. 4. **Install paths differ by version** — `C:\Program Files\VMware\...` on modern releases,
  172. `C:\Program Files (x86)\VMware\...` on older ones. Both are auto-detected.
  173. 5. **`vmcli HGFS Set*` is buggy** — it treats the first positional argument as a boolean.
  174. Use `vmrun` (`addSharedFolder` / `removeSharedFolder` / `setSharedFolderState`) instead.
  175. 6. **Use forward slashes for `.vmx` paths** — Windows accepts both, but forward slashes avoid
  176. quoting problems.
  177. 7. **`vmcli Guest copyTo/copyFrom` caps out at 64KB.** Beyond that it reports `Unknown error`,
  178. or `VMware Tools are not running in the guest` — a false message, Tools is fine. Repeated
  179. failures also wedge the guest channel, after which *every* guest operation times out until
  180. the VM is rebooted. All file transfers here therefore go through `vmrun`, which handles
  181. arbitrary sizes (100 MB in ~44 s on a Linux guest).
  182. 8. **`vmrun` re-quotes arguments containing spaces**, and `cmd.exe` then strips only one set of
  183. quotes — trailing up to a stray `"` in your command's output. `guest exec` avoids this by
  184. shipping the command as a script file instead of passing it inline.
  185. 9. **`runProgramInGuest -interactive` often fails on Windows guests**
  186. (`The specified guest user does not match the user currently logged in interactively`).
  187. Don't pass `--interactive` when Administrator is already logged in interactively.
  188. 10. **`chipset cpu|memory|cores` require a powered-off VM** — they go through the hot-plug path.
  189. To change what the *next* boot uses, write the `.vmx` instead: `config set <vm> memsize <MB>`.
  190. 11. **A wedged guest channel still reports `tools status: running`.** Use `guest ready`; if it
  191. never goes true, `power stop --hard` and start again.
  192. 12. **Value-taking flags need `--flag value`, which the parser now honours.** Boolean flags are
  193. listed in `VALUE_FLAGS`; `--memory` is boolean for `snapshot take` and numeric for
  194. `rest vm-update`.
  195. 13. **`Ethernet SetPresent` / `Sata SetPresent` silently do nothing when the label isn't
  196. already in the `.vmx`**, and still exit 0. `nic set-present` / `set-connected` and the disk
  197. attach path write the config entry instead.
  198. 14. **`vmcli Disk Create` only writes the `.vmdk`; it does not attach it.** Without a
  199. `sataN:M.fileName` entry and a controller the VM's `disks` array stays empty. `disk create`
  200. attaches automatically; pass `--no-attach` for a bare file. `VM Create` (behind `vmnew`)
  201. has the same gap — it returns a VM whose disk file is unattached and therefore unbootable.
  202. Both are fixed here.
  203. 15. **`disk create` needs a unit in the size** (`512MB`, `50GB`). A bare number is rejected with
  204. `Input Disk Size is not within acceptable limits`, which reads like a permissions problem.
  205. `disk remove` detaches, `--delete-file` also unlinks the `.vmdk`.
  206. 16. **Never `grep -v` a `.vmx` to strip device entries** — it takes the boot disk with it and the
  207. VM then stops at `Operating System not found`. Use `disk remove` / `config set`.
  208. 17. **VMs created by `vmnew` / `snapshot clone` are not registered in `inventory.vmls`**, so
  209. they can't be addressed by name until Workstation has opened them once. Use the `.vmx` path.
  210. 18. **`snapshot clone` and `clone` need the destination directory to exist**, otherwise
  211. `Could not find the file`.
  212. 19. **`template deploy` accepts only `-p <template.vmtx>`** — there is no destination or name
  213. option; the VM lands beside the template and inherits its name.
  214. 20. **`net portforward-set/delete` can fail with `Failed to refresh NAT configuration`** even
  215. though `vmnetnat.conf` was updated correctly. Plain `vmrun` fails the same way; restart
  216. `VMware NAT Service` to clear it.
  217. 21. **`nic add` is REST-only and rejects `vmnet` unless the type is `custom`**
  218. (`Redundant parameter: vmnet8`). The VM must be powered off.
  219. 22. **`snapshot revert` goes through `vmrun`, not `vmcli`** — vmcli refuses a running VM with
  220. `VM is in an invalid state (online)`, which is exactly when you want to revert.
  221. 23. **`screen keys` translates only `<Enter>`, `<Tab>`, `<Space>`.** MKS types literal text and
  222. rejects ESC and arrow keys; those fall back to `typeKeystrokesInGuest`, which usually fails
  223. on a text console.
  224. ## Development
  225. ```bash
  226. git clone https://github.com/pedoc/vmware-skill.git
  227. cd vmware-skill
  228. npm test # syntax check + smoke test
  229. ```
  230. CI runs on every push: syntax check, manifest validation, and a smoke test.
  231. ## License
  232. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.