In-Depth
Hands On with VMware's New vmcli, 'A Mysterious Command'
While reading the release notes for VMware Workstation 17.6, I saw an interesting blurb under the What's New section titled "Introducing vmcli."
[Click on image for larger view.]
The introduction explained that vmcli is a command-line tool for creating new virtual machines and templates, modifying them, and powering-on VMs and more. It said to see the Using VMware Workstation Pro documentation for more information. No clickable link was provided to the documentation, but I found the relevant documentation here after searching.
The documentation was even terser than the blurb in the release notes, which piqued my interest. A quick Google search of "vmcli" came up with a few unrelated links, but nothing about it. Now, I was really curious about this mysterious command.
First Try at Using vmcli
VMware recently made Workstation free for personal use (you can read my articles on WorkStation here). I already had Workstation installed on my system, so I brought up my command line console and entered vmcli -help, but I got a message about it not being available.
[Click on image for larger view.]
This did not surprise me as I had Workstation 17.5 installed.
When you launch Workstation, if you are not using the latest version, it will ask if you want to get more information about the newest version.
[Click on image for larger view.]
You will be taken to the VMware store to buy it when you click it. You must download and install the latest version to update your free version. You can read more about downloading and installing the free version here.
Using the vmcli Command
After updating my system and rebooting it, I brought up the command line console again and reentered vmcli -help. I again got a message that the "'vmcli' is not recognized as an internal or external command, operable program, or batch file" message. After searching, I found it and cd'ed to the directory that held it (C:\Program Files (x86)\VMware\VMware Workstation). I entered \vmcli -help, which gave me its basic syntax of the command.
[Click on image for larger view.]
I entered .\vmcli -v, and it displayed vmcli version 0.1 build-24238078.
I then ran through the help for a few modules, including VM, by entering .vmcli VM-help.
[Click on image for larger view.]
This showed me how to use the command and create a VM using it.
Powering on a VM Using vmcli
One of the operations that you can perform using vmcli is controlling the power state of a VM.
To test this command, I launched Workstation, verified the state of one of my VMs was on, and then entered "C:\Users\user01\Documents\Virtual Machines\Win11_B\Win11_B.vmx" Power Query. This showed that the VM was powered on.
[Click on image for larger view.]
I attempted to power the machine off by entering .\vmcli "C:\Users\user01\Documents\Virtual Machines\Win11_B\Win11_B.vmx" Power Stop, which reported that a required argument was missing.
After running the help command on the Power operation, I saw that it required the "o" switch with an opType of 0, 2, 1, 3, but there was no explanation of what the optotypes meant.
[Click on image for larger view.]
I guessed and tried an -o 0, which failed with another list of opTypes. I used Power Stop -o hard this time, which powered off the VM.
[Click on image for larger view.]
When I tried to power it back on, I got a message that the vmcli could not connect to the VM and that I should make sure that I had the rights to run the program, access all directories the program uses, and access all directories for temporary files. It also said that Communication with the VMX process had timed out.
[Click on image for larger view.]
After waiting a few minutes, I tried to power it back on, and it said that the VMX was already running. But when I looked at the Workstation console, it was not.
[Click on image for larger view.]
When I entered the query command, it said, "vmcli: Device 'PowerState' is not available."
After waiting a few minutes, I reentered it and it reported back that it was on. This was getting really weird.
[Click on image for larger view.]
When I tried to start it, it came back with, the same "vmcli: vmcli cannot connect to the virtual machine" message.
After waiting a few minutes, I retried it and found that the command worked.
I tried searching for the messages I got, but to no avail.
A Mysterious Command
The Workstation user guide has a detailed example of all the commands to create a VM using vmcli. I tried to follow the steps but continued getting strange error messages and gave up.
To quote Winston Churchill, I found the vmcli command "a riddle wrapped in a mystery inside an enigma." As it is in the Workstation release notes and user documentation, it must be a valid tool. Still, I am unsure what it brings to the table, as Workstation already has a command-line tool called vmrun, which allows you to interact with Workstation VMs.
Vmcli is at version 0.1 and appears very early in its development stage. I could not find any VMware or third-party documentation on it, and there were errors in its online help. Due to the issues I had when running the command, I only did limited testing with it before giving up on it. However, VMware did put some time into developing it, and I will keep an eye out for further release and information on this most mysterious command.
About the Author
Tom Fenton has a wealth of hands-on IT experience gained over the past 30 years in a variety of technologies, with the past 20 years focusing on virtualization and storage. He previously worked as a Technical Marketing Manager for ControlUp. He also previously worked at VMware in Staff and Senior level positions. He has also worked as a Senior Validation Engineer with The Taneja Group, where he headed the Validation Service Lab and was instrumental in starting up its vSphere Virtual Volumes practice. He's on X @vDoppler.