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:
An example of how to use filters and display virtual machine summary is shown below:
Command Structure
The VSS CLI command structure is compose by the base vss-cli
command followed by options, subgroups, sub-commands, options and arguments.
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:
Or this can be done by using the VM name instead as follows:
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:
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
:
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:
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:
Boolean is a binary flag that turns an option on or off, such is the case of a virtual machine marked as template by using the --on
flag or template marked as virtual machine by not specifying the flag.
Integers
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:
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:
Passing above JSON data structure to --custom-spec
in Linux, macOS, or Unix and Windows PowerShell use the single quote '
to enclose it.
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 \
:
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:
Or the VSS_OUTPUT
environment variable:
Environment variable VSS_OUTPUT
always overrides any value set in the -o/--output
option.
Table
The table
format presents the VSS CLI output into tab-delimited lines, helpful when using grep
, sed
, and awk
on Unix or Windows PowerShell.
You can also control the data shown with --columns
providing a name and a jsonpath.
If you for example just wanted the UUID, NAME and PROVISIONED GB per virtual machines, you could do:
The option --columns-width
allows you to set a maximum column width for a given output:
--columns-width
can be set to 0 in order to let the vss-cli
to calculate the proper column size based on your terminal:
JSON
Many languages can easily decode JSON structures using built-in modules or open source libraries. The VSS CLI can provide the output in json
so it can be easily processed by other scripts or JSON processors such as jq.
YAML
As with JSON, YAML can be easily decoded by many programming languages. The VSS CLI can provide the yaml
output as follows:
Auto-completion
Bash completion support is provided by [Click][Click] and will complete sub commands and parameters. Sub commands are always listed whereas parameters only if at least a dash has been provided. Example:
Source File
To activate completion in bash
or zsh
or fish
is recommended to use a generated script and source it to ensure responsiveness:
For bash
:
Save the script somewhere.
Source the file in ~/.bashrc
.
After modifying the shell config, you need to start a new shell in order for the changes to be loaded or source the file . ~/.vss-cli-complete.bash
.
For zsh
:
Save the script somewhere.
Source the file in ~/.zshrc
.
After modifying the shell config, you need to start a new shell in order for the changes to be loaded or source the file . ~/.vss-cli-complete.zsh
.
For fish
:
Save the script to ~/.config/fish/completions/vss-cli.fish:
.
After modifying the shell config, you need to start a new shell in order for the changes to be loaded.
Source
However, there’s also a non-persistent method:
For bash
:
For zsh
:
Shell
The VSS CLI provides a REPL interactive shell with tab-completion, suggestions and command history.
To enter the shell just execute vss-cli shell
and you will get the following welcome message:
Every VSS CLI command, option and argument is available in the shell context. Just exclude the vss-cli
command, for instance:
University of Toronto - Since 1827