# Commands

## Commands

### Exploring the CLI

You can explore the CLI using the help command. Help option can be used on any command:

```bash
vgs --help
```

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

### Authentication

#### Login

Authenticate with your personal VGS account:

```bash
vgs login
```

You may be asked to allow storing data in your OS key management system (Mac OS Keychain, Linux Secret Service, Windows Credential Vault).

#### Logout

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

```bash
vgs logout
```

### Service Account

Please check the [Service Account](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/service-account) page for more info.

#### Generate

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

#### Generate

Generate a new set of access credentials to the vault

```bash
vgs generate access-credentials --vault <VAULT_ID>
```

#### Get

List all access credentials in the vault

```bash
vgs get access-credentials --vault <VAULT_ID>
```

### Routes

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

#### Routes Payload Reference

#### 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 --vault &#x3C;VAULT_ID>
</strong></code></pre>

{% endtab %}

{% tab title="Output" %}

```yaml
data:
- attributes:
    created_at: '2021-05-28T11:05:38'
    destination_override_endpoint: https://echo.apps.verygood.systems
    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.

To write route details to a file:

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

```bash
vgs get routes --vault <VAULT_ID> > routes.yaml
```

{% endtab %}

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

```yaml
data:
- attributes:
    created_at: '2021-05-28T11:05:38'
    destination_override_endpoint: https://echo.apps.verygood.systems
    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" %}

```
vgs apply routes --vault <VAULT_ID> -f routes.yaml
```

{% endtab %}

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

```bash
data:
- attributes:
    created_at: '2021-05-28T11:05:38'
    destination_override_endpoint: https://echo.apps.verygood.systems
    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.

### Vaults

#### Generate

Print an empty template to create a new vault from:

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

```bash
vgs generate vault > vault.yaml
```

{% endtab %}

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

```bash
apiVersion: 1.0.0
kind: Vault
data:
  name: Very Good Vault
  environment: SANDBOX
  organizationId: AC6mGNNRecR7K5N7AjX5niz4
```

{% endtab %}
{% endtabs %}

#### Apply

Create a new vault from a template file:

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

```bash
vgs apply vault -O <ORGANIZATION_ID> -f vault.yaml
```

{% endtab %}

{% tab title="Output" %}

```yaml
apiVersion: 1.0.0
kind: Vault
data:
  credentials:
    password: 7404bf62-20e7-4e38-bb3c-3afd60df89dd
    username: USmgjMnPEotPUhKsZEBYR32x
  environment: SANDBOX
  id: tntmppl73s7
  name: Very Good Vault
  organizationId: ACq9AiipVS8rnhvQgMZ9Jjr9
```

{% endtab %}
{% endtabs %}

> Make sure to save generated user credentials as they're only shown once.

#### Get

Get details of your vaults in a YAML format:

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

```bash
vgs get vaults
```

{% endtab %}

{% tab title="Output" %}

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

{% 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 vault:

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

```bash
vgs certificate list -V 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                                                                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| --vault, -V     | Vault 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                                                           |
| --------------- | --------------------------------------------------------------------- |
| --vault, -V     | Vault 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 vault. 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                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------- |
| --vault, -V     | Set target vault 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 --vault <VAULT_ID> --since 2020-08-01T12:30:45
vgs logs access --vault <VAULT_ID> --since 1h
vgs logs access --vault <VAULT_ID> --until 2020-08-01T12:30:45
vgs logs access --vault <VAULT_ID> --until 8h
vgs logs access --vault <VAULT_ID> --tail 10
vgs logs access --vault <VAULT_ID> --output json
```

#### Operations

Print operation logs for the particular request:

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

**Options**

| Name, shorthand | Description                                                                         |
| --------------- | ----------------------------------------------------------------------------------- |
| --vault, -V     | Set target vault 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 --vault <VAULT_ID> --request <REQUEST_ID>
vgs logs operations --vault <VAULT_ID> --request <REQUEST_ID> --output json
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.