Metadata-Version: 2.4
Name: vgs-cli
Version: 1.36.0.dev1
Summary: VGS Client
Home-page: https://github.com/verygoodsecurity/vgs-cli
Author: Very Good Security
Author-email: dev@verygoodsecurity.com
License: BSD
Platform: any
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: base58<3,>=2.1.1
Requires-Dist: click-plugins<2,>=1.1.1
Requires-Dist: click<9,>=7
Requires-Dist: configobj-dev>=2019.9.1
Requires-Dist: cryptography>=44.0.1
Requires-Dist: jsonschema<5,>=3.2.0
Requires-Dist: keyring<26,>=16.1.0
Requires-Dist: keyrings.alt<6,>=3.1
Requires-Dist: pyhumps
Requires-Dist: semver<4,>=3
Requires-Dist: termcolor<3,>=2
Requires-Dist: Jinja2>=2.10
Requires-Dist: vgs-api-client<1,>=0.0.51
Requires-Dist: async-timeout
Requires-Dist: packaging<26,>=23
Requires-Dist: textual<8.3,>=8.2.8
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# VGS CLI

Command Line Tool for programmatic configurations on VGS.

[Official Documentation](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli)

## Table of Contents

- [Requirements](#requirements)
- [Installation](#installation)
  - [PyPI](#pypi)
- [Run](#run)
- [Try the Console feature branch](#try-the-console-feature-branch)
- [Running in Docker](#running-in-docker)
- [AI agent skill](#ai-agent-skill)
- [Commands](#commands)
  - [Authentication](#authentication)
  - [Organizations and tenants](#organizations-and-tenants)
  - [Organization notifications](#organization-notifications)
  - [Routes](#routes)
  - [Collect Forms](#collect-forms)
  - [Access credentials and logs](#access-credentials-and-logs)
  - [Service accounts](#service-accounts)
  - [Certificates](#certificates)
- [Automation with VGS CLI](#automation-with-vgs-cli)
- [Telemetry](#telemetry)

## Requirements
[Python 3.11 or newer](https://www.python.org/downloads/) with OpenSSL 1.1.1 or newer, or [Docker](https://docs.docker.com/get-docker/).

## Installation

### PyPI

Install from PyPI:

```bash
python3 -m pip install vgs-cli
```

## Run

Verify the installation:

```bash
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:

```bash
git switch feature/cli-ui
scripts/dev.sh setup
```

Launch the feature with an authorized VGS account:

```bash
scripts/dev.sh cli console
```

In the Console:

1. Complete browser authentication and select a SANDBOX context.
2. Open **Organization**, select **Tenants**, then choose **Create tenant**.
3. Enter a unique tenant name and complete one of the CMP, HTTP, SFTP, or
   no-use-case paths.
4. Review the retained answers before selecting **Create tenant**. This action
   creates real SANDBOX resources.
5. 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:

```bash
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](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/docker).

## AI agent skill

Install the agent skill:

```bash
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](https://skills.sh/).

Update the agent skill:

```bash
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.

```bash
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:

```bash
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:

```bash
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](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/service-account)
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](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/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`.
