VGS provides a CLI (Command Line Interface) tool for programmatically configuring your vault's routes.



The VGS-CLI software depends on Python. Consequently, in order to install CLI, you must first install Python. The current version of CLI requires that you have Python 3 and pip3 installed. Check out vgs-cli page: vgs-cli PyPi page

To install the latest version enter:

pip3 install vgs-cli

To install new version from PyPi:

 pip3 uninstall vgs-cli
 pip install -U vgs-cli

or pip install vgs-cli --upgrade

You can have configured python environment that is not compatible with vgs-cli. For example, Python 2.7 installed on your machine or incompatible versions of libraries. In that case, you can use a virtual environment for vgs-cli: 1. python3 -m venv env 2. pip3 install vgs-cli


To authenticate run vgs authenticate command. After that enter dashboard credentials and authenticate in your browser. Then return back to the terminal and continue usage of VGS CLI.

If you come across an error You need to run vgs authenticate because your session has been expired please re-authenticate. You may be asked to allow storing data in your OS password management system (Mac OS X Keychain, Linux Secret Service, Windows Credential Vault).

In order to remove authenticated session type:

vgs logout


Use the following command to get the version of the CLI:

vgs version


The CLI provides two main methods. These allow you to control the setup of a single vault from the command line as well as integrate a workflow into your source control or SDLC pipeline to ensure controlled configuration of production resources.

You can explore the provided CLI using the help command vgs --help

 usage: vgs --tenant TENANT [--environment ENVIRONMENT] [--debug] {route} ...

The tenant parameter can be found from your inbound route CNAME or via the dashboard. It looks like tntabc123. This parameter is mandatory when performing routing updates.

Storing Route Configuration

Routing information can be fetched from the VGS API using a single command vgs --tenant=tnteipi8liw route --dump-all. It will output the routes in YAML format and is suitable for storing on disk and persisting into source control to keep a linear history of route configuration.

Persist the data using a command like vgs --tenant=tnteipi8liw route --dump-all > my-route-file.yaml. This will pipe the data into a file called my-route-file.yaml. You can then edit this file and apply it against your vault (or another vault when promoting rules) as you please.

Persisting Route Configuration

Persisting route configurations to the VGS platform is done using the sync-all command. This takes the form of vgs --tenant=tnteipi8liw route --sync-all and will accept any data passed to it from STDIN.

The common form of this command would look like vgs --tenant=tnteipi8liw route --sync-all < my-route-file.yaml.

This command will then dump the configuration returned by the API to STDOUT for review.

Using the CLI in practice.

In a common setup you will have multiple vaults. These usually represent different environments and the CLI provides an excellent tool for moving configuration between these vaults.

We recommend that you follow this pattern for securely updating configurations:

Given two vaults:

  • Sandbox tnt123
  • Live tnt789
  1. Test routing in Sandbox vgs --tenant=tnt123 route --dump-all > my-route-file.yaml After this edit my-route-file.yaml as you need
  2. Update your routes vgs --tenant=tnt123 route --sync-all < my-route-file.yaml
  3. Promote your routes to Live vgs --environment=live --tenant=tnt789 route --sync-all < my-route-file.yaml

This simple pattern gives you a reliable way to verify changes against your integration environment before testing against your live environment.


After vgs-cli installation, you may run into some issues. Below is the list of most common cases.

  1. During authentication, you can receive the following error. ("Authentication error occurred:Can't store password on keychain",) {} Resolution: This is solved by signing your Python binary with command codesign -f -s - $(which python3)

  2. Running into the error vgs: error: unrecognized arguments: --tenant=TENANT_ID This could be a result of the wrong usage of parameters: vgs --environment=live route --dump-all --tenant=TENANT_ID - WRONG vgs --tenant=TENANT_ID --environment=live route --dump-all - OK

  3. If you're receiving requirements conflicts, consider using venv which is described in the Installation section.

  4. After some updates on MAC OS you can receive error below: keyring.backends._OS_X_API.Error: (-25293, "Can't fetch password from system") Resolution: You should update your Python version to latest. After update you will see a prompt that will ask for Keyring access. Please make sure you allowed vgs-cli to store passwords.