How to control VirtualBox from the command line

Some of the command line examples for interacting with Windows VMs require credentials. The examples assume they are exported in the current shell environment for convience:

export VBOXUSER=vboxuser
export VBOXPASS=vboxuser

List VMs

$ vboxmanage list vms

"Windows XP 32-bit" {a460478d-975b-4d67-8add-98f9c9551d0f}
"Windows 10 64-bit" {c5ff6179-c05b-495f-ae36-3b2f36ea01bd}
"Windows 7 64-bit" {bf769fb3-a390-46ee-bc4a-d7d4260752ea}
"Windows 95C OSR 2.5" {e8f45085-6c10-4ea5-b6df-efa4c0804ffe}
"Ubuntu 16.04.1 64-bit" {3536fe48-f7e6-40a4-a9af-5a2de7d3ad78}

Start VM

To start a VM, run vboxmanage startvm <name or UUID>. You can optionally specify a --type parameter to control how the VM is started. Using --type gui will show it via the host GUI; using --type headless means you’ll need to interact over the network (typically via SSH).

$ vboxmanage --nologo startvm "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}"

Waiting for VM "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" to power on...
VM "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" has been successfully started.

List running VMs

$ vboxmanage list runningvms

"Windows 7 64-bit" {bf769fb3-a390-46ee-bc4a-d7d4260752ea}

The vboxmanage list command can be used with option -l, which instructs the list command to output a detailed list (truncated below to save space).

Shutting down VMs

Equivalent of briefly pressing the power button on a physical computer:

vboxmanage controlvm "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" acpipowerbutton

If the graceful shutdown didn't work use savestate:

$ vboxmanage controlvm "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" savestate

0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

To forcibly shut down a VM using the following command, which is equivalent to pressing and holding a computer's power button:

$ vboxmanage controlvm "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" poweroff

0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%

Alternatively use PowerShell to gracefully shut down computer with name VBOXUSER-WIN7

vboxmanage --nologo guestcontrol "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" \
             run --username $VBOXUSER --password $VBOXPASS \
                 --wait-stdout  --wait-stderr \
                 --exe "cmd.exe" -- cmd.exe /c \
             powershell.exe -inputformat none Stop-Computer VBOXUSER-WIN7

Automatically Login

Run the following command once as described in Ch. 9.2.1 Automated Windows guest logons, of the User Manual. Reboot afterwards.

"D:\VBoxWindowsAdditions.exe /with_autologon"

To automatically log in:

vboxmanage controlvm "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" \
             setcredentials $VBOXUSER $VBOXPASS "DOMAIN"

Control Windows using PowerShell

List running processes

$ vboxmanage --nologo guestcontrol "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" \
             run --username $VBOXUSER --password $VBOXPASS \
                 --wait-stdout  --wait-stderr \
                 --exe "cmd.exe" -- cmd.exe /c \
             powershell.exe -inputformat none Get-Process

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName          
-------  ------    -----      ----- -----   ------     -- -----------          
    120       9    15712      16032    50             884 audiodg              
     28       5     2220       2984    18     0.03   2164 cmd                  
     78       8     1784       5512    28            2692 CompatTelRunner      
    485      28    37344      16132   132            2736 CompatTelRunner      
     37       5     1168       3360    22     0.02   2144 conhost              
     34       5     1432       3392    22            2460 conhost              
     33       5     1160       3312    22            2704 conhost              
...

Start disk defragmenter for drive 'c:'

This is useful for compacting VirtualBox images. Should be run before 'sdelete'. Note, you will be prompted with UAC dialog.

vboxmanage --nologo guestcontrol "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" \
   run --username $VBOXUSER --password $VBOXPASS \
       --wait-stdout  --wait-stderr \
       --exe "cmd.exe" -- cmd.exe /c \
   powershell.exe -inputformat none Start-Process "defrag.exe" -Verb runAs -ArgumentList \"c: /U /V\"

Start SysInternals 'sdelete' to zero disk space for drive 'c:'

This is useful for compacting VirtualBox images. Should be run after OS disk defragmenter. Note, you will be prompted with UAC dialog.

vboxmanage --nologo guestcontrol "{bf769fb3-a390-46ee-bc4a-d7d4260752ea}" \
   run --username $VBOXUSER --password $VBOXPASS \
       --wait-stdout  --wait-stderr \
       --exe "cmd.exe" -- cmd.exe /c \
   powershell.exe -inputformat none Start-Process \
       "\"c:\\Program Files (x86)\\devtools\\sysinternals\\sdelete.exe\"" -Verb runAs -ArgumentList \"c: /Z\"

Links

rmi1974/how_to_control_virtualbox_from_the_command_line.md