Skip to main content
The Command Line Interface (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. 
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: 
    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. 
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. 
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

Provides installation instructions to help enable auto-complete for the CLI. 
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. 
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. 
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. 
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. 
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. 
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