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

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:

General settings

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

For instance, to update the timeout value, execute:

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.

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:

List endpoints

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

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:

To verify, run vss-cli configure ls:

Environment Variables

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

Name

Description

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:

Command Line Input

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

Option

Description

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:

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:

University of Toronto - Since 1827