Commands

Exploring the CLI

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

Authentication

Authenticate with your personal VGS account:

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:

vgs logout

VGS CLI Environment Variables

`VGS_CONFIG_FILE`

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

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

`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

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

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

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

Collect form <FORM_ID> created successfully

Delete a Form

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

Collect form <FORM_ID> deleted successfully

Get List of Forms

vgs get forms --tenant <TENANT_ID>

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'

Get Form

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

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

Notifications

Generate Notification Template

vgs generate notification > notification.yaml

vgs apply notification --organization <ORGANIZATION_ID> \
  --file notification.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.

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

Enable, disable, or delete

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

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:

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:

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

vgs generate access-credentials --tenant <TENANT_ID>

Get

List all access credentials in the tenant

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:

vgs get routes --tenant <TENANT_ID>

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

To write route details to a file:

vgs get routes --tenant <TENANT_ID> > routes.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

Please refer to the documentation for more information.

Apply

Create or update the route:

vgs apply routes --tenant <TENANT_ID> -f routes.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

Please refer to the documentation for more information.

Tenants

Generate

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

vgs generate tenant > tenant.yaml

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

Apply

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

vgs apply tenant --file tenant.yaml

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

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

Get

Get details of your tenants in a YAML format:

vgs get tenants

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

Organizations

Get

Get details of your organizations in a YAML format:

vgs get organizations

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

Certificates

List

List all certificates associated to a tenant:

vgs certificate list -T tnt12345678

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

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.

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

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

Name, shorthand

Description

--tenant, -T

Tenant in which this certificate will be stored.

--type

The type of certificate to generate within VGS. Available options: - apple-pay-merchant-identity - apple-pay-payment-processing

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

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

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

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:

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

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:

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

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.

vgs -d <COMMAND> --help

PreviousConfiguration

NextService Account

Last updated 2 days ago

Exploring the CLI

Authentication

Login

Logout

VGS CLI Environment Variables

VGS_CONFIG_FILE

VGS_CLIENT_ID & VGS_CLIENT_SECRET

Collect Forms

Create or Update a Form

Delete a Form

Get List of Forms

Get Form

Notifications

Generate Notification Template

Create or update a notification tenant in an organization

Enable, disable, or delete

Service Accounts

Prepare a Service Account Using a Template

Apply

Delete

Access Credentials

Generate

Get

Routes

Get

Apply

Tenants

Generate

Apply

Get

Organizations

Get

Certificates

List

Generate CSR

Upload

Logs

Access

Operations

CLI Debugging

`VGS_CONFIG_FILE`

`VGS_CLIENT_ID` & `VGS_CLIENT_SECRET`