VGS CLI

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

Configuration

Installation

To install the latest version enter:

pip install vgs-cli

Authentication

All commands provided by vgs-cli require MFA verification.

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

Usage

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.