This release is a pre-release and may not be stable for production use.
VGS CLI
Command Line Tool for programmatic configurations on VGS.
Table of Contents
- Requirements
- Installation
- Run
- Try the Console feature branch
- Running in Docker
- AI agent skill
- Commands
- Automation with VGS CLI
- 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
Try the Console feature branch
After the feature branch is available in an existing repository checkout, switch to it and prepare the local Python environment:
git switch feature/cli-ui
scripts/dev.sh setup
Launch the feature with an authorized VGS account:
scripts/dev.sh cli 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. For an HTTP use case, review the separate route draft before submitting it. SFTP route configuration remains a separate later step. Every SANDBOX tenant created by the CLI includes the standard CLI-managed Collect Form.
To try Import tenant, generate a local template, replace its example name and organization ID, then select it with the Console's native file picker:
scripts/dev.sh cli generate tenant > /tmp/vgs-cli-tenant.yaml
Keep environment: SANDBOX; the Console rejects LIVE tenant imports. Do not
commit generated tenant files, credentials, tokens, or command output.
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 |
Generate an HTTP route template. |
vgs generate route --protocol sftp |
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. |
vgs logs access -T <TENANT_ID> |
View tenant access logs. |
vgs logs operations -T <TENANT_ID> -R <REQUEST_ID> |
View request operation logs. |
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.
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.
5 maintainers
Metadata
5 maintainers
Release files for vgs-cli 1.36.0.dev1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vgs_cli-1.36.0.dev1-py3-none-any.whl | Python 3 | none | any | Details |
Release files / vgs_cli-1.36.0.dev1-py3-none-any.whl
| Download URL | vgs_cli-1.36.0.dev1-py3-none-any.whl |
|---|---|
| Size | 168.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c75b2b7d141aea6c523c97057c6ef19d618d840ffc219898ac2c90c3844ef56d
|
|
BLAKE2b-256 checksum How to use checksums |
0cca4fc373edcf24a177b3813f0ecf0ac7d253e910b2bc907b96d90a134e2908
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency log
