Use

This section describes the VSS Command Line Interface in detail.

Help

To get help when using the VSS CLI, you can add --help option to the end of a command. For example:

vss-cli --help

The following command lists the available sub commands for the compute command:

vss-cli compute --help

Help in sub commands is divided in three main sections: Usage, where the command syntax is shown as well as a brief description; Options and sub commands available with a short help column as shown below:

Usage: vss-cli compute [OPTIONS] COMMAND [ARGS]...

  Compute related resources such as virtual machines, networks supported
  operating systems, logical folders, OVA/OVF images, floppy images, ISO
  images and more.

Options:
  --help  Show this message and exit.

Commands:
  domain     List compute domains.
  floppy     Manage floppy images.
  folder     Manage logical folders
  image      Manage personal and list public VM images.
  inventory  Manage inventory reports
  iso        Manage ISO images.
  net        List available virtual networks
  os         Supported OS.
  template   List virtual machine templates
  vm         Manage virtual machines

For instance, the vss-cli compute vm ls command, is used to list your virtual machines hosted in the ITS Private Cloud, has the following usage:

Usage: vss-cli compute vm ls [OPTIONS]

  List virtual machine instances.

  Filter and sort list by any attribute. For example:

  vss-cli compute vm ls -f name=vm-name -f version=13

  Simple name filtering:

  vss-cli compute vm ls -f name=%vm-name% -s name desc

Options:
  -f, --filter-by <TEXT TEXT>...  filter list by <field_name>
                                  <operator>,<value>
  -a, --show-all                  show all results  [default: False]
  -p, --page                      page results in a less-like format
  -s, --sort <TEXT TEXT>...       sort by <field_name> <asc|desc>
  -c, --count INTEGER             size of results
  --help                          Show this message and exit.

An example of how to use filters and display virtual machine summary is shown below:

vss-cli compute vm ls -f name=%VM% -s name=desc

moref    name                  folder.path                                         cpu_count    memory_gb  power_state    ip_address
-------  --------------------  ------------------------------------------------  -----------  -----------  -------------  ------------
vm-1274  1910T-TestVM1         VSS > Development                                           1            2  poweredOff
vm-1270  1910T-TestVM2         VSS > Development                                           1            2  poweredOff
vm-1258  1910T-TestVM3         VSS > Development                                           1            1  poweredOff

Command Structure

The VSS CLI command structure is compose by the base vss-cli command followed by options, subgroups, sub-commands, options and arguments.

vss-cli [OPTIONS] COMMAND [ARGS]...

Parameters take different types of input values such as numbers, strings, lists, tuples, and JSON data structures as strings.

Parameter Values

VSS CLI options vary from simple string, boolean or numeric values to JSON data structures as input parameters on the command line.

Common

String parameters can contain alphanumeric characters and spaces surrounded by quotes. The following example renames a virtual machine:

vss-cli compute vm set vm-123 name 'VM-New'

Or this can be done by using the VM name instead as follows:

vss-cli compute vm set TEST name VM-New

If there’s more than one virtual machine with “TEST” in their name, you will be prompted to select which one you want to change:

Found 5 matches. Please select one:

=> (vm-1270) VSS > Development > 1910T-TestVM1
   (vm-1258) VSS > Development > 1910T-TestVM2
   (vm-1274) VSS > Development > 1910T-TestVM3

Once, selected the change will be processed.

Timestamp is widely used in any vm set command to schedule --schedule a change or in vm mk snapshot to define the start date --from of the snapshot. Timestamps are formatted YYYY-MM-DD HH:MM. In the next example, a virtual machine consolidation task has been submitted to run at 2017-03-10 21:00:

vss-cli compute vm set --schedule '2017-03-10 21:00' vm-123 consolidate

Lists are implemented in arguments and options. In arguments list are generally series of strings separated by spaces. The below command shows how to delete two virtual machines in a single line:

vss-cli compute vm rm vm-123 vm-234

Multiple options are taken as lists. For instance, in order to specify multiple disks when deploying a virtual machine, multiple occurrences of --disk should be specified as follows:

vss-cli compute vm mk from-template --power-on --source TestVM1 \
 --description 'New virtual machine' --disk 40 --disk 20 --disk 30 VM2

Boolean is a binary flag that turns an option on or off, such is the case of converting a virtual machine to a template or converting a template back to a virtual machine.

vss-cli compute vm set TestVM3 template

Integers

vss-cli compute vm set TestVM2 memory size 1

Binary objects are handled by passing a relative or full path to the object to process. When uploading a file to VSKEY-STOR, a path should be passed as argument as follows:

vss stor ul ~/Downloads/50123e0d-6c74-0c6f-a65a-3704dd1ec619-ud.iso -d isos

JSON

Some VSS CLI options and arguments require data to be formatted as JSON, such as reconfiguring a virtual machine guest operating system specification (hostname, domain, dns, ip, subnet and gateway) upon deployment. The option --custom-spec expects the following JSON data structure:

{
 "dhcp": false,
 "ip": "192.168.1.23",
 "gateway": ["192.168.1.1"],
 "dns": ["192.168.1.1"],
 "hostname": "vm1",
 "domain": "utoronto.ca"
}

Passing above JSON data structure to --custom-spec in Linux, macOS, or Unix and Windows PowerShell use the single quote ' to enclose it.

vss-cli compute vm mk from-template --source TestVM3 --power-on \
  --description 'New virtual machine' \
  --custom-spec '{"dhcp": false, "ip": "192.168.1.23", "gateway": ["192.168.1.1"],
   "dns": ["192.168.1.1"], "hostname": "vm1", "domain": "utoronto.ca"}' VM1

On the Windows command prompt, use the double quote " to enclose the data structure and escape the double quotes from the data structure using the backslash \:

vss-cli compute vm mk from-template --source FrontEnd-1 \
  --description 'New virtual machine' \
  --custom-spec "{\"dhcp\": false, \"ip\": \"192.168.1.23\", \"gateway\": [\"192.168.1.1\"],
   \"dns\": [\"192.168.1.1\"], \"hostname\": \"vm1\", \"domain\": \"utoronto.ca\"}" VM1

Command Output

The VSS CLI supports the following formats:

Table (table)
JSON (json)
YAML (yaml)
NDJSON (ndjson)
auto (table)

By default VSS CLI output is table, and this can be configured either by the output option:

vss-cli --output json

Or the VSS_OUTPUT environment variable:

export VSS_OUTPUT=json

Environment variable VSS_OUTPUT always overrides any value set in the -o/--output option.