> For the complete documentation index, see [llms.txt](https://docs.verygoodsecurity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/commands.md).

# Commands

## Exploring the CLI

```bash
vgs --help
vgs --version
vgs <GROUP> --help
vgs <GROUP> <COMMAND> --help
```

## Authentication

### Login

Authenticate with your personal VGS account:

```bash
vgs login
vgs login --no-browser
vgs login --idp <IDP_ID>
vgs login --config <CONFIG_FILE>
```

| Option                       | Purpose                                                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--browser` / `--no-browser` | Open the browser automatically or print the authorization URL.                                                                        |
| `--idp <IDP_ID>`             | Authenticate through a non-VGS Identity Provider. An explicit `--idp` takes precedence over `[login] idp` in the configuration file.  |
| `--config <CONFIG_FILE>`     | Read login defaults from a ConfigObj-format file. This parameter will take precedent over the `VGS_CONFIG_FILE` environment variable. |

### Logout

Sessions automatically expire after 30 minutes of inactivity. You can also log out manually:

```bash
vgs logout
```

### VGS CLI Environment Variables

#### `VGS_CONFIG_FILE`

The VGS CLI will pull settings from the file referenced in this environment variable.

{% tabs %}
{% tab title="Sample Config File" %}

```bash
[login]
idp = okta|azure-ad|google-workspace
```

{% endtab %}
{% endtabs %}

#### `VGS_CLIENT_ID` & `VGS_CLIENT_SECRET`

When both `VGS_CLIENT_ID` and `VGS_CLIENT_SECRET` are present, the CLI uses these service-accounts to authenticate automatically to your VGS Organization.

## Collect Forms

```bash
vgs get forms --tenant <TENANT_ID>
vgs get form --tenant <TENANT_ID> <FORM_ID>
vgs apply form --tenant <TENANT_ID> --file form.yaml
vgs apply form --tenant <TENANT_ID> --json '<FORM_JSON>'
vgs delete form --tenant <TENANT_ID> <FORM_ID>
```

### Create or Update a Form

{% tabs %}
{% tab title="Command" %}

```bash
vgs apply form --tenant <TENANT_ID> --file form.yaml
vgs apply form --tenant <TENANT_ID> --json '<FORM_JSON>'
```

{% endtab %}

{% tab title="form.yaml" %}

```yaml
version: 1
data:
  id: default
  name: default
  card_attributes:
    brands: true
    card-type: true
    product-name: false
    issuer-bin: false
    issuing-country: false
    card-segment-type: false
    virtual-card: false
    prepaid-card: false
    regulated: false
    additional-card-brand: false
    reloadable: false
    hsa: false
    ebt: false
    fsa: false
    bank-name: false
    bank-phone: false
    bank-website: false
```

{% endtab %}

{% tab title="Output" %}

```
Collect form <FORM_ID> created successfully
```

{% endtab %}
{% endtabs %}

### Delete a Form

{% tabs %}
{% tab title="Command" %}

```bash
vgs delete form --tenant <TENANT_ID> <FORM_ID>
```

{% endtab %}

{% tab title="Output" %}

```
Collect form <FORM_ID> deleted successfully
```

{% endtab %}
{% endtabs %}

### Get List of Forms

{% tabs %}
{% tab title="Command" %}

```bash
vgs get forms --tenant <TENANT_ID>
```

{% endtab %}

{% tab title="Output" %}

```yaml
apiVersion: 1.0.0
kind: CollectForms
data:
- createdAt: '2026-08-20T12:25:28.251Z'
  formId: default
  formName: default
  updatedAt: '2026-08-20T12:25:28.485Z'
- createdAt: '2026-03-04T14:33:37.635Z'
  formId: collect-cards-new-york
  formName: collect-cards-new-york
  updatedAt: '2026-03-04T14:33:37.858Z'
```

{% endtab %}
{% endtabs %}

### Get Form

{% tabs %}
{% tab title="Command" %}

```bash
vgs get form --tenant <TENANT_ID> <FORM_ID>
```

{% endtab %}

{% tab title="Output" %}

```yaml
version: 1
data:
  id: default
  name: default
  card_attributes:
    brands: true
    card-type: true
    product-name: false
    issuer-bin: false
    issuing-country: false
    card-segment-type: false
    virtual-card: false
    prepaid-card: false
    regulated: false
    additional-card-brand: false
    reloadable: false
    hsa: false
    ebt: false
    fsa: false
    bank-name: false
    bank-phone: false
    bank-website: false
```

{% endtab %}
{% endtabs %}

## Notifications

#### Generate Notification Template

{% tabs %}
{% tab title="Generate" %}

```bash
vgs generate notification > notification.yaml
```

{% endtab %}

{% tab title="Create or update" %}

```bash
vgs apply notification --organization <ORGANIZATION_ID> \
  --file notification.yaml
```

{% endtab %}
{% endtabs %}

```yaml
apiVersion: 1.0.0
kind: NotificationIntegration
data:
  # Notification provider to use. Run `vgs get notifications -O
  # <ORGANIZATION_ID>` to see existing integrations and the provider
  # parameter names they use.
  provider: webhook

  # Name of the notification integration to create.
  name: Route alerts

  # Optional description of the notification integration.
  description: Route lifecycle notifications

  # Provider-specific configuration. Include every parameter the provider
  # requires. VGS generates and manages provider-controlled values, such as
  # the webhook signing secret; do not add them here.
  providerParameters:
    - name: url
      value: https://example.com/webhooks/vgs

  # Events to notify on. Set enabled to false to keep an event configured but
  # inactive. An organization-scoped event must omit resourceIds. A
  # non-organization-scoped event requires one or more resource IDs, whose
  # meaning depends on the event: tenant IDs for a tenant-scoped event,
  # organization member IDs for a user-scoped event. Check with your VGS
  # contact for the event's scope if it is not obvious from its name.
  events:
    - id: notifications.changes
      enabled: true
    - id: route.updated
      enabled: true
      resourceIds:
        - <TENANT_ID>
```

#### Create or update a notification tenant in an organization

Omit `data.id` to create an integration and include it to update one. Do not add provider-controlled secrets to the input file.

```shellscript
vgs apply notification --organization <ORGANIZATION_ID> \
  --file notification.yaml
```

#### Enable, disable, or delete

```bash
vgs apply notification --organization <ORGANIZATION_ID> \
  --enable <INTEGRATION_ID>
vgs apply notification --organization <ORGANIZATION_ID> \
  --disable <INTEGRATION_ID>
vgs delete notification --organization <ORGANIZATION_ID> <INTEGRATION_ID>
```

`apply notification` accepts exactly one of `--file`, `--enable`, or `--disable`. Deletion prompts for confirmation unless `--confirm` / `-y` is provided.

## Service Accounts

Please check the [Service Account](/vault/developer-tools/vgs-cli/service-account.md) page for more info.

#### Prepare a Service Account Using a Template

Generate the service account configuration from the **vgs-cli** template and store it to the **service\_account.yaml** file:

```bash
vgs generate service-account -t vgs-cli > service_account.yaml
```

### Apply

To apply the service account configuration stored in the **service\_account.yaml** file with your organization ID and execute:

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

### Delete

To delete the service account, specify your organization ID, service account client ID and execute:

```bash
vgs delete service-account -O <ORGANIZATION_ID> <SERVICE_ACCOUNT_CLIENT_ID>
```

## Access Credentials

VGS CLI can be used to manage access credentials of the tenant. These credentials can be used to access HTTPS Outbound Routes and the SFTP Proxy Routes.

### Generate

Generate a new set of access credentials to the tenant

```bash
vgs generate access-credentials --tenant <TENANT_ID>
```

### Get

List all access credentials in the tenant

```bash
vgs get access-credentials --tenant <TENANT_ID>
```

## Routes

VGS CLI can be used to manage route configurations of the tenant.

### Get

Get details of your routes in YAML format:

{% tabs %}
{% tab title="Command" %}

<pre class="language-bash"><code class="lang-bash"><strong>vgs get routes --tenant &#x3C;TENANT_ID>
</strong></code></pre>

{% endtab %}

{% tab title="Output" %}

```yaml
data:
- attributes:
    created_at: '2021-05-28T11:05:38'
    destination_override_endpoint: https://fake-sample.verygoodsecurity.com
    entries:
    - classifiers: {}
      config:
        condition: AND
        expression: null
        rules:
        - condition: null
          expression:
            field: PathInfo
            operator: matches
            type: string
            values:
            - /post
          rules: null
        - condition: null
          expression:
            field: ContentType
            operator: equals
            type: string
            values:
            - application/json
          rules: null
      id: 23573ce5-b72a-4c22-b050-8c6080c82fa7
      id_selector: null
      operation: REDACT
      operations: null
      phase: REQUEST
      public_token_generator: UUID
      targets:
      - body
      token_manager: PERSISTENT
      transformer: JSON_PATH
      transformer_config:
      - $.account_number
      transformer_config_map: null
    host_endpoint: (.*).verygoodproxy.com
    id: 8613f04f-b4d7-4389-95f6-2f7a3649ea95
    ordinal: null
    port: 80
    protocol: http
    source_endpoint: '*'
    tags:
      name: echo.apps.verygood.systems-rosy-brown-triangle
      source: RouteContainer
    updated_at: '2021-05-28T11:05:38'
  id: 8613f04f-b4d7-4389-95f6-2f7a3649ea95
  type: rule_chain
version: 1
```

{% endtab %}
{% endtabs %}

To write route details to a file:

{% tabs %}
{% tab title="Command" %}

```bash
vgs get routes --tenant <TENANT_ID> > routes.yaml
```

{% endtab %}

{% tab title="routes.yaml" %}

```yaml
data:
- attributes:
    created_at: '2021-05-28T11:05:38'
    destination_override_endpoint: https://fake-sample.verygoodsecurity.com
    entries:
    - classifiers: {}
      config:
        condition: AND
        expression: null
        rules:
        - condition: null
          expression:
            field: PathInfo
            operator: matches
            type: string
            values:
            - /post
          rules: null
        - condition: null
          expression:
            field: ContentType
            operator: equals
            type: string
            values:
            - application/json
          rules: null
      id: 23573ce5-b72a-4c22-b050-8c6080c82fa7
      id_selector: null
      operation: REDACT
      operations: null
      phase: REQUEST
      public_token_generator: UUID
      targets:
      - body
      token_manager: PERSISTENT
      transformer: JSON_PATH
      transformer_config:
      - $.account_number
      transformer_config_map: null
    host_endpoint: (.*).verygoodproxy.com
    id: 8613f04f-b4d7-4389-95f6-2f7a3649ea95
    ordinal: null
    port: 80
    protocol: http
    source_endpoint: '*'
    tags:
      name: echo.apps.verygood.systems-rosy-brown-triangle
      source: RouteContainer
    updated_at: '2021-05-28T11:05:38'
  id: 8613f04f-b4d7-4389-95f6-2f7a3649ea95
  type: rule_chain
version: 1
```

{% endtab %}
{% endtabs %}

Please refer to the [documentation](#routes-payload-reference) for more information.

### Apply

Create or update the route:

{% tabs %}
{% tab title="Command" %}

```bash
vgs apply routes --tenant <TENANT_ID> -f routes.yaml
```

{% endtab %}

{% tab title="routes.yaml" %}

```bash
data:
- attributes:
    created_at: '2021-05-28T11:05:38'
    destination_override_endpoint: https://fake-sample.verygoodsecurity.com
    entries:
    - classifiers: {}
      config:
        condition: AND
        expression: null
        rules:
        - condition: null
          expression:
            field: PathInfo
            operator: matches
            type: string
            values:
            - /post
          rules: null
        - condition: null
          expression:
            field: ContentType
            operator: equals
            type: string
            values:
            - application/json
          rules: null
      id: 23573ce5-b72a-4c22-b050-8c6080c82fa7
      id_selector: null
      operation: REDACT
      operations: null
      phase: REQUEST
      public_token_generator: UUID
      targets:
      - body
      token_manager: PERSISTENT
      transformer: JSON_PATH
      transformer_config:
      - $.account_number
      transformer_config_map: null
    host_endpoint: (.*).verygoodproxy.com
    id: 8613f04f-b4d7-4389-95f6-2f7a3649ea95
    ordinal: null
    port: 80
    protocol: http
    source_endpoint: '*'
    tags:
      name: echo.apps.verygood.systems-rosy-brown-triangle
      source: RouteContainer
    updated_at: '2021-05-28T11:05:38'
  id: 8613f04f-b4d7-4389-95f6-2f7a3649ea95
  type: rule_chain
version: 1
```

{% endtab %}
{% endtabs %}

Please refer to the [documentation](#routes-payload-reference) for more information.

## Tenants

### Generate

The generated configuration file includes the tenant name, environment, region, organization, payment-product enrollment settings, and card-storage settings:

{% tabs %}
{% tab title="Command" %}

```bash
vgs generate tenant > tenant.yaml
```

{% endtab %}

{% tab title="tenant.yaml" %}

```bash
apiVersion: 1.0.0
kind: Vault
data:
  name: Very Good Tenant
  environment: SANDBOX
  region: US
  organizationId: <ORGANIZATION_ID>
  configurations:
    accountUpdater:
      visa: onCreate
      mastercard: onCreate
      amex: manual
      discover: manual
    networkTokens:
      visa: onCreate
      mastercard: onCreate
      amex: manual
      discover: manual
    cardStorage:
      deduplication: DISABLED
      panAliasFormat: UUID
```

{% endtab %}
{% endtabs %}

### Apply

Use a template file to create a tenant in an organization.

{% tabs %}
{% tab title="Organization in tenant.yaml" %}

```bash
vgs apply tenant --file tenant.yaml
```

{% endtab %}

{% tab title="Organization supplied by option" %}

```bash
vgs apply tenant --organization <ORGANIZATION_ID> --file tenant.yaml
```

{% endtab %}
{% endtabs %}

If the organization ID is present in both locations, the values must match.

### Get

Get details of your tenants in a YAML format:

{% tabs %}
{% tab title="Command" %}

```bash
vgs get tenants
```

{% endtab %}

{% tab title="Output" %}

```yaml
apiVersion: 1.0.0
kind: Vault
data:
  attributes:
    environment: SANDBOX
    identifier: tntmppl73s7
    name: Very Good Tenant
```

{% endtab %}
{% endtabs %}

## Organizations

### Get

Get details of your organizations in a YAML format:

{% tabs %}
{% tab title="Command" %}

```bash
vgs get organizations
```

{% endtab %}

{% tab title="Output" %}

```yaml
apiVersion: 1.0.0
kind: Organizations
data:
  attributes:
    active: true
    createdAt: 2021-12-10T16:04:21.946Z
    identifier: gix4hve5
    name: Very Good Organization
  id: ACq9AiipVS8rnhvQgMZ9Jjr9
```

{% endtab %}
{% endtabs %}

## Certificates

### List

List all certificates associated to a tenant:

{% tabs %}
{% tab title="Command" %}

```bash
vgs certificate list -T tnt12345678
```

{% endtab %}

{% tab title="Output" %}

```bash
apiVersion: 1.0.0
kind: Certificates
data:
  data:
  - attributes:
      authority: VGS_MANAGED
      authorityName: VGS_MANAGED
      createdAt: '2026-04-05'
      domain: apple-pay-merchant-identity
      id: CRT12345
      type: APPLEPAY_MERCHANT
      vaultIdentifier: tnt12345678
    id: CRT123
    type: certificate
```

{% endtab %}
{% endtabs %}

### Generate CSR

Generate a CSR that can be used to create a certificate in another system. Once the certificate is generated, it can be uploaded using the `vgs certificate upload` command.

{% tabs %}
{% tab title="Command" %}

```bash
vgs certificate generate-csr \
  -V tnt12345678 \
  --type apple-pay-merchant-identity|apple-pay-payment-processing \
  --name 'example-certificate' \
  -o merchant-id.csr
```

{% endtab %}

{% tab title="Output" %}

```yaml
CSR created for apple-pay-merchant-identity (cert id: CRTbnQrWKTAb8aNdKYCfXfbjs)
merchant-id.csr
```

{% endtab %}
{% endtabs %}

| Name, shorthand | Description                                                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| --tenant, -T    | Tenant in which this certificate will be stored.                                                                                              |
| --type          | <p>The type of certificate to generate within VGS.  Available options:<br>- apple-pay-merchant-identity<br>- apple-pay-payment-processing</p> |
| --name          | A human readable name for this certificate object in VGS                                                                                      |
| --output, -o    | Output file where the CSR will be dropped after creation.                                                                                     |

### Upload

Upload a certificate to a previously created CSR that was generated with the `vgs certificate generate-csr` command.

{% tabs %}
{% tab title="Command" %}

```bash
vgs certificate upload \
  -V tnt12345678 \
  --cert-id CRT12345 \
  -f merchant_id.cer
```

{% endtab %}

{% tab title="Output" %}

```yaml
Certificate for CRTbMuHeskpDYqDmCkhaiucz6 uploaded successfully.
apiVersion: 1.0.0
kind: Certificate
data:
  data:
    attributes:
      createdAt: '2026-04-05'
      id: CRT12345
      vaultIdentifier: tnt12345678
    type: certificate
```

{% endtab %}
{% endtabs %}

| Name, shorthand | Description                                                           |
| --------------- | --------------------------------------------------------------------- |
| --tenant, -T    | Tenant in which this certificate will be stored.                      |
| --cert-id       | Certificate ID you want to associated this certificate with           |
| --file, -f      | Path to file you wish to upload and associate with the generated CSR. |

## Logs

### Access

Print access logs for the tenant. Log records are grouped by 30 items by default if `--tail` option is not specified or larger than 30. Could be fetched up to 1020 rows at a time:

```bash
vgs logs access [OPTIONS]
```

**Options**

| Name, shorthand | Description                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------- |
| --tenant, -T    | Set target tenant to get logs (e.g. tnt23f12a3g).                                                   |
| --since         | Print logs newer than a relative duration (e.g. 30s, 5m, or 3h) or after a specific RFC 3339 date.  |
| --until         | Print logs older than a relative duration (e.g. 30s, 5m, or 3h) or before a specific RFC 3339 date. |
| --tail          | Set number of records to show from the end of the logs. Defaults to all logs if unspecified.        |
| --output, -o    | Define output format. Possible values: json, yaml. Defaults to yaml if unspecified.                 |

**Examples**

```bash
vgs logs access --tenant <TENANT_ID> --since 2020-08-01T12:30:45
vgs logs access --tenant <TENANT_ID> --since 1h
vgs logs access --tenant <TENANT_ID> --until 2020-08-01T12:30:45
vgs logs access --tenant <TENANT_ID> --until 8h
vgs logs access --tenant <TENANT_ID> --tail 10
vgs logs access --tenant <TENANT_ID> --output json
```

### Operations

Print operation logs for the particular request:

```bash
vgs logs operations [OPTIONS]
```

**Options**

| Name, shorthand | Description                                                                         |
| --------------- | ----------------------------------------------------------------------------------- |
| --tenantt, -T   | Set target tenant to get logs (e.g. tnt23f12a3g).                                   |
| --request, -R   | Set request id to get logs. (e.g. 3f2ab1258a87bc03f18d41a71cf317ee).                |
| --output, -o    | Define output format. Possible values: json, yaml. Defaults to yaml if unspecified. |

**Examples**

```bash
vgs logs operations --tenant <TENANT_ID> --request <REQUEST_ID>
vgs logs operations --tenant <TENANT_ID> --request <REQUEST_ID> --output json
```

## CLI Debugging

Use `-d` / `--debug` before a command to enable debug output.

```bash
vgs -d <COMMAND> --help
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/commands.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.