Configure the `vss-cli`

Before using VSS CLI, you need setup your VSS credentials. You can do this in a couple of ways:

Configuration file
Environment variables
Command Line Input

Configuration file

The quickest way to get started is to run the vss-cli configure mk command:

vss-cli configure mk

Endpoint Name [cloud-api]:
Username: jm
Password:
Repeat for confirmation:
Successfully configured credentials for https://cloud-api.eis.utoronto.ca.
You are ready to use the vss-cli 🚀

vss-cli configure mk generates a new configuration file at ~/.vss-cli/config.yaml or %UserProfile%\.vss-cli\config.yaml on Windows. The configuration file holds general settings configuration general and multiple endpoint configuration endpoints as follows:

general:
    default_endpoint_name: cloud-api
    timeout: 120
    verbose: no
    debug: no
    output: auto
    table_format: simple
    check_for_updates: yes
    check_for_messages: yes
    columns_width: 0
    wait_for_requests: false

endpoints:
    - name: cloud-api
      url: https://cloud-api.eis.utoronto.ca
      auth:
      token:
    - name: vss-api
      url: https://vss-api.eis.utoronto.ca
      auth:
      token:

The following table summarizes the general area configuration parameters

Name	Type	Description
`default_endpoint_name`	string	Default endpoint name that must match one item from the `endpoints` section.
`s3_server`	string	S3 server for user file transfer.
`timeout`	int	Timeout for network operations.
`verbose`	bool	Enables verbose mode.
`debug`	bool	Enables debug mode.
`output`	string	Output format. Either `yaml`, `table` or `json`
`table_format`	string	table formats supported by python-tabulate: plain, simple, github, grid, fancy_grid, pipe, orgtbl, rst, mediawiki, html, latex, latex_raw, latex_booktabs, tsv or csv.
`check_for_updates`	bool	Check for `vss-cli` updates when a new token is generated.
`check_for_messages`	bool	Check for Cloud API messages when a new token is generated.
`columns_width`	int	`0` to auto. `-1` to disable or any other positive number.
`wait_for_requests`	bool	If set to true, will wait for request to complete.

Edit Configuration

There are two methods to edit the raw configuration file and update any of the general configuration parameters. Using vss-cli configure edit command will use your terminal default editor (vi, nano, etc..) to edit the configuration file. Also, you can use any system default application to edit the configuration file by adding the -l/--launch option, for instance vss-cli configure edit --launch.

Upgrade Legacy Configuration

Users with previous versions of the vss-cli including the legacy vsscli can upgrade/migrate their endpoints to this version. To do so, execute vss-cli configure upgrade <path-to-config>. By default the upgrade command looks for ~/vss-cli/config.json if no argument is specified.

Usage: vss-cli configure upgrade [OPTIONS] [LEGACY_CONFIG]

Options:
  -c, --confirm    Proceed with migration without prompting confirmation.
  -o, --overwrite  Overwrite if target file exists.
  --help           Show this message and exit.

The following example upgrades an existing vss-cli configuration from ~/vss-cli/config.json to ~/vss-cli/config.yaml:

vss-cli configure upgrade

Found 3 endpoints. Migrating to new configuration file.
Successfully loaded 3 endpoints from legacy configuration.

Would you like to upgrade 3 endpoint(s)? This action will
create a new configuration file /path/to/.vss-cli/config.yaml
with your endpoints in it [y/N]: Y

Successfully migrated /path/to/.vss-cli/config.json 🎉

General settings

General settings can be updated with the vss-cli configure set <setting> command as follows:

Usage: vss-cli configure set [OPTIONS] [check_for_messages|check_for_updates|d
                             ebug|verbose|default_endpoint_name|output|table_f
                             ormat|timeout|columns_width|wait_for_requests]
                             VALUE

  Set configuration attribute in the general section.

Options:
  --help  Show this message and exit.

For instance, to update the timeout value, execute:

vss-cli configure set timeout 60

Updating timeout from 120 -> 60.
/Users/username/.vss-cli/config.yaml updated 💾

Or disable columns_width calculation:

vss-cli configure set columns_width – -1

Updating columns_width from 0 -> -1. /Users/username/.vss-cli/config.yaml updated 💾

Boolean values for check_for_updates, verbose, debug, and wait_for_requests etc. can be enabled (true) by using any of the following values “yes”, “true”, “t”, “1”, “y”, everything else is taken as false.

vss-cli configure set verbose no

Updating verbose from True -> False.
/Users/username/.vss-cli/config.yaml updated 💾

vss-cli configure set verbose yes

Updating verbose from False -> True.
/Users/username/.vss-cli/config.yaml updated 💾

Add/Update endpoints

Endpoints can be added and updated with the vss-cli configure mk command and you can have multiple accounts with the same endpoint. For example, adding a different account:

vss-cli configure mk

Endpoint Name [cloud-api]: cloud-api-other
Username: other-user
Password:
Repeat for confirmation:
Successfully configured credentials for https://cloud-api.eis.utoronto.ca.
You are ready to use the vss-cli 🚀

List endpoints

To list available endpoint configuration, just execute vss-cli configure ls and the output should look like:

vss-cli configure ls

NAME             ENDPOINT                           USER    PASS      TOKEN                    SOURCE       DEFAULT
---------------  ---------------------------------  ------  --------  -----------------------  -----------  ---------
cloud-api        https://cloud-api.eis.utoronto.ca  jm      ********  eyJhbGciOi...MiCveo6WaM  config file  ✅
cloud-api-other  https://cloud-api.eis.utoronto.ca  other   ********  eyJhbGciOi...IlUvSkpU2A  config file

Enable endpoint

By default the vss-cli will look for the default_endpoint_name parameter in the configuration file. To update the default endpoint, run vss-cli configure set default_endpoint <endpoint-name> as follows:

vss-cli configure set default_endpoint_name cloud-api-other

Updating default_endpoint_name from cloud-api -> cloud-api-other.
/path/to/.vss-cli/config.yaml updated 💾

To verify, run vss-cli configure ls:

vss-cli configure ls

NAME             ENDPOINT                           USER    PASS      TOKEN                    SOURCE       DEFAULT
---------------  ---------------------------------  ------  --------  -----------------------  -----------  ---------
cloud-api        https://cloud-api.eis.utoronto.ca  jm      ********  eyJhbGciOi...MiCveo6WaM  config file
cloud-api-other  https://cloud-api.eis.utoronto.ca  other   ********  eyJhbGciOi...IlUvSkpU2A  config file  ✅

Environment Variables

The following table summarizes the environment variables supported by the vss-cli:

Name	Description
VSS_ENDPOINT	Cloud API endpoint URL or endpoint name defined in configuration file.
VSS_S3_SERVER	S3 server for user file transfer.
VSS_VPN_SERVER	VPN server for MFA management
VSS_TIMEOUT	Timeout for network operations.
VSS_USER	Default Username to use for generating an access token. Token will not persist.
VSS_USER_PASS	Default username password for generating an access token. Token will not persist.
VSS_TOKEN	Manually generated Cloud API Token.
VSS_CONFIG	Relative or full path to non-standard location to configuration file.
VSS_OUTPUT	Output format. Either `yaml`, `table` or `json`.
VSS_TABLE	Table format to be used by tabulate.
VSS_COL_WIDTH	`0` to auto. `-1` to disable or any other positive number.
VSS_WAIT_FOR_REQUESTS	If set to true, will wait for request to complete.

If you would like to have a stateless configuration, set VSS_USER and VSS_USER_PASS or VSS_TOKEN with a token generated manually:

export VSS_USER=USER
export VSS_USER_PASS=superstrongpassword
# or
export VSS_TOKEN=long_jwt_token

Command Line Input

The following table summarizes the command line input options supported by the vss-cli:

Option	Description
`-e`/`--endpoint`	Cloud API endpoint URL endpoint name defined in configuration file.
`-w`/`--s3-server`	S3 server for user file transfer.
`-vpn`/`--vpn-server` \| VPN server for MFA management
`--timeout`	HTTP timeout value.
`-u`/`--username`	Default Username to use for generating an access token. Token will not persist.
`-p`/`--password`	Default username password for generating an access token. Token will not persist.
`-t`/`--token`	Manually generated Cloud API Access Token.
`-c`/`--config`	Relative or full path to non-standard location to configuration file.
`-o`/`--output`	Output format. Either `yaml`, `table` or `json`.
`--table-format`	Table format to be used by tabulate.
`--columns`	Custom columns key=value list.
`--columns-width`	Truncates column values (0: auto, -1: disable)
`--wait / --no-wait`	Wait for request(s) to complete

The vss-cli configuration file can be configured using a mix of both user input and command line options as follows:

vss-cli --endpoint https://vss-api.eis.utoronto.ca configure mk --endpoint-name vss-api-jm

Username: jm
Password:
Repeat for confirmation:
Would you like to replace existing configuration?
 vss-api-jm:jm: https://vss-api.eis.utoronto.ca [y/N]: y
Successfully configured credentials for https://vss-api.eis.utoronto.ca.
You are ready to use the vss-cli 🚀

Then, if the new endpoint isn’t the default_endpoint_name in the configuration file, you can specify the endpoint name in --endpoint option as follows:

vss-cli --endpoint vss-api-jm compute vm ls

...

Configure the vss-cli