The Command Line Interface (CLI) is a tool that allows you to create JWTs for testing and development on the command line.
This guide will cover how to install, configure, and use the CLI.
Prerequisites
Before you use the CLI, you will need:
- An account and instance.
- A private key to authenticate with the API. You can generate one in the Integrations section of your dashboard.
Installation
Our CLI required Node JS to be installed. Once you’re ready, run the following command to install the CLI globally.
npm install -g @gr4vy/cli
Configuration
Once the CLI is installed, you need to configure it with your Gr4vy credentials. This command will securely store your gr4vy-id and private key for future use.
- Run the configuration command:
gr4vy init acme sandbox private_key.pem
- The CLI will require you to pass the following information:
gr4vyId: Your instance ID (e.g., acme).environment: Your environment (e.g., sandbox or production).privateKey: The path to the private key that you generated and downloaded locally.
Your credentials will be stored in a configuration file, typically located at ~/.gr4vyrc.json.
General usage
Next, you can create a JWT 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, you can inspect each token 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 you 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 embed
Generate a token for use with Gr4vy 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,
e.g. 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 Gr4vy 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 your instance.
ENVIRONMENT (production|sandbox) The environment of your 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
