VGS CLI

Command Line Tool for programmatic configurations on VGS.

Requirements
Installation
- PyPI
Run
Running in Docker
AI agent skill
Commands
Automation with VGS CLI
VGS CLI Console
Telemetry

Requirements

Python 3.11 or newer with OpenSSL 1.1.1 or newer, or Docker.

Installation

PyPI

Install from PyPI:

python3 -m pip install vgs-cli

Run

Verify the installation:

vgs --version

Running in Docker

Check our official documentation.

AI agent skill

Install the agent skill:

npx skills add verygoodsecurity/skills --skill vgs-cli-guide

The guide covers Dashboard-assisted onboarding, the complete built-in command surface, controlled route and Collect Form changes, service-account automation, Docker, certificates, logs, and troubleshooting. Installation uses the Skills CLI.

Update the agent skill:

npx skills update vgs-cli-guide

Commands

Full command reference:

https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/commands
Routes YAML format (routes.yaml): https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/commands#routes.yaml

Tenant terminology

Use tenant and --tenant/-T in new commands. Legacy vault commands and --vault/-V options still work, but print a deprecation warning.

Authentication

Command	Purpose
`vgs --help`	List available commands.
`vgs login`	Start an interactive session.
`vgs logout`	End the current session.

Organizations and tenants

Command	Purpose
`vgs get organizations`	List accessible organizations.
`vgs get tenants`	List all tenants visible to the authenticated identity.
`vgs get tenant -T <TENANT_ID>`	Get one tenant with provisioning, account, configuration, and merchant state.
`vgs generate tenant > tenant.yaml`	Generate a tenant template.
`vgs apply tenant -f tenant.yaml`	Create and configure a SANDBOX or LIVE tenant through a staged, resumable workflow.
`vgs apply tenant -O <ORGANIZATION_ID> -f tenant.yaml`	Create a tenant when `organizationId` is omitted from the template.
`vgs apply tenant-resources -T <TENANT_ID> -f resources.yaml --dry-run true`	Validate tenant resources without applying them.
`vgs apply tenant-resources -T <TENANT_ID> -f resources.yaml`	Apply reviewed resources to a tenant.

vgs get tenants does not take an organization option. vgs apply tenant requires the organization ID either in tenant.yaml as data.organizationId or through -O/--organization; if both are present, they must match.

Organization notifications

Command	Purpose
`vgs get notifications -O <ORGANIZATION_ID>`	List notification integrations.
`vgs get notification-events -O <ORGANIZATION_ID> <INTEGRATION_ID>`	List configured events for a notification integration.
`vgs generate notification > notification.yaml`	Generate a notification integration template.
`vgs apply notification -O <ORGANIZATION_ID> -f notification.yaml`	Create or update a notification integration from a file.
`vgs apply notification -O <ORGANIZATION_ID> --enable <INTEGRATION_ID>`	Enable a notification integration.
`vgs apply notification -O <ORGANIZATION_ID> --disable <INTEGRATION_ID>`	Disable a notification integration.
`vgs delete notification -O <ORGANIZATION_ID> <INTEGRATION_ID>`	Delete a notification integration.

Notification management requires an active organization, organization-admin access. The CLI masks generated webhook secrets in its output.

Routes

Command	Purpose
`vgs generate route --protocol http > http-route.yaml`	Generate an HTTP route template.
`vgs generate route --protocol sftp > sftp-route.yaml`	Generate an SFTP route template.
`vgs get routes -T <TENANT_ID>`	List tenant routes.
`vgs apply routes -T <TENANT_ID> -f <FILE>`	Apply tenant routes.
`vgs delete routes -T <TENANT_ID> <ROUTE_ID>`	Delete one tenant route.

Collect Forms

Command	Purpose
`vgs get forms -T <TENANT_ID>`	List Collect Forms.
`vgs get form -T <TENANT_ID> <FORM_ID>`	Get one Collect Form.
`vgs generate form > form.yaml`	Generate a Collect Form template.
`vgs apply form -T <TENANT_ID> -f <FILE>`	Apply a Collect Form from a file.
`vgs apply form -T <TENANT_ID> --json '<JSON>'`	Apply inline Collect Form JSON.
`vgs delete form -T <TENANT_ID> <FORM_ID>`	Delete one Collect Form.

Access credentials and logs

Command	Purpose
`vgs get access-credentials -T <TENANT_ID>`	List tenant access credentials.
`vgs generate access-credentials -T <TENANT_ID>`	Generate tenant access credentials. Capture the output securely as shown below.
`vgs logs access -T <TENANT_ID>`	View tenant access logs.
`vgs logs operations -T <TENANT_ID> -R <REQUEST_ID>`	View request operation logs.

Access-credential generation is a live mutation that returns secret material. Write it to a new, approved absolute path outside version control with owner-only permissions, and do not display or inspect it in shared logs:

(
  umask 077
  set -o noclobber
  vgs generate access-credentials -T <TENANT_ID> \
    > /absolute/secure/new-access-credentials.yaml
)

Service accounts

Generate a service-account resource and save the YAML so you can review it before applying it. The general vgs-cli template accepts zero or more tenants; when no tenant is supplied, the generated account has no tenant access.

vgs generate service-account --template vgs-cli -T <TENANT_ID> > service-account.yaml

Payment-credential templates require exactly one tenant and a name containing 1–20 characters:

vgs generate service-account --template <TEMPLATE> -T <TENANT_ID> --var name=<NAME> > service-account.yaml

Template	Purpose
`vgs-cli`	Automate common CLI organization, tenant, route, and access-log operations.
`public-credential-collect`	Collect payment credentials without read access.
`read-credentials-no-pci`	Read tokenized credentials without PCI data.
`read-credentials-with-pci`	Read credentials including PCI data.
`credentials-admin`	Read and write payment credentials.

After reviewing the generated scopes, apply the resource to the organization:

vgs apply service-account -O <ORGANIZATION_ID> -f service-account.yaml

The apply response contains a one-time client secret. Run the command only in your private terminal, store the secret in an approved secret manager, and do not commit or share the response. See the service-account documentation for the full workflow.

Certificates

Command	Purpose
`vgs certificate --help`	Show certificate commands.

Automation with VGS CLI

If you want to use the VGS CLI for automation, create a service account.

VGS CLI Console

VGS CLI Console is a keyboard-first interactive workspace for managing VGS resources in SANDBOX tenants.

VGS CLI Console

Launch it from an installed VGS CLI:

vgs console

In the Console:

Complete browser authentication and select a SANDBOX context.
Open Organization, select Tenants, then choose Create tenant.
Enter a unique tenant name and complete one of the CMP, HTTP, SFTP, or no-use-case paths.
Review the retained answers before selecting Create tenant. This action creates real SANDBOX resources.
Confirm that the completed tenant becomes the active Console context.

Telemetry

VGS CLI collects limited usage analytics to help VGS understand how the CLI is used and improve the product. To disable telemetry, set VGS_CLI_TELEMETRY_OPTOUT=1 or DO_NOT_TRACK=1.

Metadata

Release files for vgs-cli 1.36.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for vgs-cli 1.36.0
File	Interpreter	ABI	Platform	Reset
vgs_cli-1.36.0-py3-none-any.whl 172.5 kB Sep 21, 2026	Python 3	none	any	Details

Release files / vgs_cli-1.36.0-py3-none-any.whl

Download URL	vgs_cli-1.36.0-py3-none-any.whl
Size	172.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`96a3fbe9b1edd5bd44fd515655cbbcdeab3e6cb105e7dd709efbd8a1b23dbede`
BLAKE2b-256 checksum How to use checksums	`9fbd3f1364e30a729739e696dd86a94779fc6ae5c64d1bef283370f6b366f312`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/verygoodsecurity/vgs-cli
Publishing commit: github.com/verygoodsecurity/vgs-cli/tree/91107c9c66911f29d3d51f14d56a3fa75b613765

Workflow

Publishing configuration: github.com/verygoodsecurity/vgs-cli/blob/91107c9c66911f29d3d51f14d56a3fa75b613765/.github/workflows/build-publish.yaml
Publishing logs: github.com/verygoodsecurity/vgs-cli/actions/runs/35615447097/attempts/1

Artifact

Subject: vgs_cli-1.36.0-py3-none-any.whl
SHA-256 checksum: 96a3fbe9b1edd5bd44fd515655cbbcdeab3e6cb105e7dd709efbd8a1b23dbede Verifying attestations