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:

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

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:

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:

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: