Getting Started

Once you have installed Virtomate, you can see all commands and options by running:

$ virtomate --help

To list all domains on your system, run:

$ virtomate domain-list
[]

Virtomate always returns JSON. [] is an empty list. This means that there is no domain.

Because Virtomate relies on libvirt, it connects to the session-mode daemon qemu:///session by default. If you want to connect to another instance, you can either define the environment variable LIBVIRT_DEFAULT_URI or use the command-line option -c:

$ LIBVIRT_DEFAULT_URI=qemu:///system virtomate domain-list
[]
$ virtomate -c qemu:///system domain-list
[]

Both are equivalent.

Tip

If you get an error accessing the system-mode daemon qemu:///system as a normal user, you can either use sudo or add yourself to the user group libvirt. Members of libvirt usually have password-less access to the system-mode daemon. Please refer to the documentation for your operating system.

If your virtual machines are running on a different host, you can connect to it using SSH:

$ virtomate -c qemu+ssh://[email protected]/system -p domain-list
[{"name":"ubuntu-24.04","state":"running","uuid":"b901fbbb-1012-495d-a32d-90a8ddaa50a7"},{"name":"debian-12","state":"suspended","uuid":"5ba9232a-1694-4d8b-b40d-e32f710c22a2"}]

Here, we see a result for the first time. It is not exactly easy to read because JSON is meant to be parsed by another tool like jq. But that can be changed with the command-line option -p (like in “pretty”):

$ virtomate -c qemu+ssh://[email protected]/system -p domain-list
[
  {
    "name": "ubuntu-24.04",
    "state": "running",
    "uuid": "b901fbbb-1012-495d-a32d-90a8ddaa50a7"
  },
  {
    "name": "debian-12",
    "state": "suspended",
    "uuid": "5ba9232a-1694-4d8b-b40d-e32f710c22a2"
  }
]

That’s much better!

As mentioned, Virtomate returns JSON that is meant to be parsed by other tools. jq is an excellent choice for that. Assume you are only interested in the name of each running virtual machine:

$ virtomate domain-list | jq 'map(select(.state | contains("running"))) | .[].name'
"ubuntu-24.04"

You are now only an xargs away from shutting down all virtual machines that are running:

$ virtomate domain-list | jq 'map(select(.state | contains("running"))) | .[].name' | xargs -i virsh destroy --graceful {}
Domain 'ubuntu-24.04' destroyed

That is far from everything Virtomate has to offer. Check the man pages to see what else it can do for you!