> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Line Interface (CLI)

The [Command Line Interface (CLI)](https://github.com/gr4vy/gr4vy-cli) is a tool that allows JWTs to be created for testing and development on the command line.

This guide covers how to install, configure, and use the CLI.

## Prerequisites

Before using the CLI, the following are needed:

* An account and instance.
* A private key to authenticate with the API. Generate one in the **Integrations** section of the dashboard.

## Installation

The CLI requires Node JS to be installed. Once ready, run the following command to install the CLI globally.

```sh theme={"system"}
npm install -g @gr4vy/cli
```

## Configuration

Once the CLI is installed, it needs to be configured with credentials. This command securely stores the `gr4vy-id` and private key for future use.

1. Run the configuration command:
   ```sh theme={"system"}
   gr4vy init acme sandbox private_key.pem
   ```
2. The CLI requires the following information:
   * **`gr4vyId`**: The instance ID (for example, `acme`).
   * **`environment`**: The environment (for example, `sandbox` or `production`).
   * **`privateKey`**: The path to the private key that was generated and downloaded locally.

Credentials are stored in a configuration file, typically located at `~/.gr4vyrc.json`.

## General usage

Next, a JWT can be created for use in Embed as well as for server-to-server use.

```sh theme={"system"}
gr4vy token expiresIn=10d --scope=buyers.read --scope=buyers.write
gr4vy embed 1299 USD buyer_external_identifier=user-123
```

Additionally, each token can be inspected by passing the `--debug` flag.

```sh theme={"system"}
gr4vy token expiresIn=10d --scope=buyers.read --scope=buyers.write --debug
gr4vy embed 1299 USD buyer_external_identifier=user-123 --debug
```

More details on each command is available below.

# Commands

* [`gr4vy autocomplete`](#gr4vy-autocomplete)
* [`gr4vy checkout-session`](#gr4vy-checkout-session)
* [`gr4vy embed`](#gr4vy-embed)
* [`gr4vy help`](#gr4vy-help)
* [`gr4vy init`](#gr4vy-init)
* [`gr4vy token`](#gr4vy-token)

### `gr4vy autocomplete`

Provides installation instructions to help enable auto-complete for the CLI.

```sh theme={"system"}
USAGE
  $ gr4vy autocomplete [SHELL] [-r]

ARGUMENTS
  SHELL  (zsh|bash|powershell) Shell type

FLAGS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

DESCRIPTION
  display autocomplete installation instructions

EXAMPLES
  $ gr4vy autocomplete

  $ gr4vy autocomplete bash

  $ gr4vy autocomplete zsh

  $ gr4vy autocomplete powershell

  $ gr4vy autocomplete --refresh-cache
```

### `gr4vy checkout-session`

Generate a checkout session ID.

```sh theme={"system"}
USAGE
  $ gr4vy checkout-session --merchant-account-id=default

FLAGS
  -m, --mid=<value>  The merchant account ID to generate a checkout session for.
      --debug        Returns the raw header and claim for the token

DESCRIPTION
  Generate a checkout session ID.

  This ID can be used with Secure Fields and native mobile SDKs.


FLAG DESCRIPTIONS
  -m, --mid=<value>  The merchant account ID to generate a checkout session for.

    This default to no value if not provided.

  --debug  Returns the raw header and claim for the token

    Returns the decoded header and claim from the JWT token without the signature
```

### `gr4vy embed`

Generate a token for use with Embed.

```sh theme={"system"}
USAGE
  $ gr4vy embed 1299 USD buyer_external_identifier=user-123

ARGUMENTS
  AMOUNT    The amount to generate a token for. This amount needs to be in the smallest denomination for the currency,
            for example 1299 for $12.99
  CURRENCY  The 3 digit currency code to generate a token for.

FLAGS
  --debug  Returns the raw header and claim for the token

DESCRIPTION
  Generate a token for use with Embed.

  This token can be used with Embed as it is
  restricted to frontend scopes only.

  It accepts any number of key=value pairs as additional data to be
  pinned in the token.


FLAG DESCRIPTIONS
  --debug  Returns the raw header and claim for the token

    Returns the decoded header and claim from the JWT token without the signature
```

### `gr4vy help`

Display help for the `gr4vy` command.

```sh theme={"system"}
USAGE
  $ gr4vy help [COMMANDS] [-n]

ARGUMENTS
  COMMANDS  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for gr4vy.
```

### `gr4vy init`

Generates a configuration file that can be used to generate the token.

```sh theme={"system"}
USAGE
  $ gr4vy init acme sandbox private_key.pem

ARGUMENTS
  GR4VYID      The ID of the instance.
  ENVIRONMENT  (production|sandbox) The environment of the instance.
  PRIVATEKEY   The filename of the private key to add to the config.

DESCRIPTION
  Generate sample .gr4vyrc.json file

  Generates a config file that can be used to generate the token.
```

### `gr4vy token`

Generate a bearer token for server-to-server API calls.

```sh theme={"system"}
USAGE
  $ gr4vy token expiresIn=10d --scope=buyers.read --scope=buyers.write

FLAGS
  -e, --expiresIn=<value>
      [default: 1h] The expiry of the token

  -s, --scope=<option>...
      [default: *.read,*.write] A scope to add to this flag
      <options: all.read|all.write|*.read|*.write|anti-fraud-service-definitions.read|anti-fraud-service-definitions.write
      |anti-fraud-services.read|anti-fraud-services.write|buyers.read|buyers.write|buyers.billing-details.read|buyers.bill
      ing-details.write|connections.read|connections.write|digital-wallets.read|digital-wallets.write|flows.read|flows.wri
      te|payment-methods.read|payment-methods.write|payment-options.read|payment-options.write|payment-service-definitions
      .read|payment-service-definitions.write|payment-services.read|payment-services.write|reports.read|reports.write|role
      s.read|roles.write|transactions.read|transactions.write|audit-logs.read|audit-logs.write|checkout-sessions.read|chec
      kout-sessions.write|card-scheme-definitions.read|card-scheme-definitions.write|payment-method-definitions.read|payme
      nt-method-definitions.write|reset.read|reset.write|merchant-accounts.read|merchant-accounts.write>

  --debug
      Returns the raw header and claim for the token

DESCRIPTION
  Generate a bearer token for server-to-server API calls.

  This token should be used with care as it is not
  restricted to any specific frontend scopes only.


FLAG DESCRIPTIONS
  -e, --expiresIn=<value>  The expiry of the token

    The expiration expressed in seconds or a string describing a time span vercel/ms.

  -s, --scope=all.read|all.write|*.read|*.write|anti-fraud-service-definitions.read|anti-fraud-service-definitions.write|anti-fraud-services.read|anti-fraud-services.write|buyers.read|buyers.write|buyers.billing-details.read|buyers.billing-details.write|connections.read|connections.write|digital-wallets.read|digital-wallets.write|flows.read|flows.write|payment-methods.read|payment-methods.write|payment-options.read|payment-options.write|payment-service-definitions.read|payment-service-definitions.write|payment-services.read|payment-services.write|reports.read|reports.write|roles.read|roles.write|transactions.read|transactions.write|audit-logs.read|audit-logs.write|checkout-sessions.read|checkout-sessions.write|card-scheme-definitions.read|card-scheme-definitions.write|payment-method-definitions.read|payment-method-definitions.write|reset.read|reset.write|merchant-accounts.read|merchant-accounts.write...

    A scope to add to this flag

    A single scope to add to this JWT

  --debug  Returns the raw header and claim for the token

    Returns the decoded header and claim from the JWT token without the signature
```