Command Line Interface (CLI)

The Gr4vy CLI is a single, self-contained binary for working with Gr4vy from your terminal. It can:

• generate access tokens and Embed tokens for development and testing,
• manage multiple instances and credentials as named profiles, and
• call every Gr4vy API operation — buyers, transactions, payment methods, checkout sessions, reports, and more.

It is built on the official Go SDK, and its command surface is generated from the SDK, so it stays in sync with the API automatically.

The previous npm package @gr4vy/cli is deprecated. The CLI is now distributed as a native binary — install it with one of the options below instead of npm.

Prerequisites

• An account and instance (your instance ID, for example acme).
• Credentials, either:
  • a private key to sign API tokens — generate one in the Integrations section of the dashboard and download it as a .pem file, or
  • your dashboard email and password, for user login.

Installation

Homebrew (macOS/Linux)

brew install gr4vy/tap/gr4vy

Prebuilt archives for every platform are also available on the releases page. Verify your install with:

gr4vy version

Configuration

The CLI stores connection settings as named profiles in ~/.config/gr4vy/config.toml, so you can switch between instances and environments. Private keys and login sessions are kept in your operating system keychain (with a 0600 file fallback on headless systems) — never in the config file.

1. Create a profile

   Run gr4vy init for an interactive setup, or create one directly:

   gr4vy config add acme \
     --id acme \
     --environment sandbox \
     --merchant-account-id default \
     --key-file private_key.pem \
     --set-active
   
2. Verify it

   gr4vy config list      # shows profiles; * marks the active one
   gr4vy config show acme # the active profile (secrets redacted)
   

Working with multiple instances

gr4vy config use acme-prod                      # switch the active profile
gr4vy --profile acme-sandbox transactions list  # override for one command

Every setting can also come from an environment variable (handy for CI), with the precedence flag > environment variable > active profile > default:

Variable	Purpose
GR4VY_ID	instance ID
GR4VY_SERVER	sandbox or production
GR4VY_MERCHANT_ACCOUNT_ID	default merchant account
GR4VY_PRIVATE_KEY / GR4VY_PRIVATE_KEY_FILE	private key (raw PEM or base64), or a path to the key file
GR4VY_PROFILE	profile to use
GR4VY_TOKEN	a pre-generated bearer token (skips signing)

Authentication

Each profile uses one of two methods:

• Key (default) — your merchant private key signs a short-lived token for every request.

• Login — exchange your dashboard email and password for a session that the CLI refreshes automatically:

  gr4vy login --email [e-mail]   # prompts for the password
  gr4vy logout
  

Generating tokens

# Server-to-server API access token (JWT). Scopes default to *.read and *.write.
gr4vy token --scope buyers.read --scope buyers.write --expires-in 10d
gr4vy token --list-scopes          # list every valid scope

# Embed token for the checkout form, pinning amount, currency, and extra fields.
gr4vy embed 1299 USD buyer_external_identifier=user-123
gr4vy embed 1299 USD --checkout-session   # also creates a checkout session

# Create a checkout session (for Secure Fields and the mobile SDKs).
gr4vy checkout-sessions create

Add --debug to any token command to also print the decoded JWT header and claims:

gr4vy token --scope transactions.read --debug

Calling the API

Every SDK operation is available as gr4vy <resource> <action>. Path parameters are positional arguments; request bodies are passed with --data (inline JSON, @file.json, or - for stdin); filters and query parameters are flags.

gr4vy buyers list
gr4vy buyers create --data '{"display_name":"Jane Doe","external_identifier":"user-123"}'
gr4vy buyers get <buyer-id>

gr4vy transactions list --limit 20 --status capture_pending --currency USD
gr4vy transactions get <transaction-id>
gr4vy transactions refunds create <transaction-id> --data '{"amount":500}'

Explore the tree interactively with --help at any level:

gr4vy --help
gr4vy transactions --help
gr4vy transactions list --help

The full, per-command reference lives in the CLI repository.

Output formats

Use -o, --output to choose the format — it defaults to a table on a terminal and JSON when piped:

gr4vy transactions list -o table
gr4vy transactions list -o json | jq '.items[].id'
gr4vy buyers get <buyer-id> -o yaml

List commands accept --limit and --cursor; the response includes a next_cursor for paging. --compact emits single-line JSON.

Shell completion

Completion is built in for bash, zsh, fish, and PowerShell. Load it in your current shell to try it:

source <(gr4vy completion zsh)   # or: bash / fish

To install it permanently, run gr4vy completion <shell> --help for the exact steps for your shell. Flags with fixed choices (such as token --scope) complete their values.