> ## 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 [Gr4vy CLI](https://github.com/gr4vy/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](https://github.com/gr4vy/gr4vy-go), and its command
surface is generated from the SDK, so it stays in sync with the API automatically.

<Note>
  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`.
</Note>

## 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

<CodeGroup>
  ```sh Homebrew (macOS/Linux) theme={"system"}
  brew install gr4vy/tap/gr4vy
  ```

  ```powershell Scoop (Windows) theme={"system"}
  scoop bucket add gr4vy https://github.com/gr4vy/scoop-bucket
  scoop install gr4vy
  ```

  ```sh Go theme={"system"}
  go install github.com/gr4vy/gr4vy-cli@latest
  ```
</CodeGroup>

Prebuilt archives for every platform are also available on the
[releases page](https://github.com/gr4vy/gr4vy-cli/releases). Verify your install with:

```sh theme={"system"}
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.

<Steps>
  <Step title="Create a profile">
    Run `gr4vy init` for an interactive setup, or create one directly:

    ```sh theme={"system"}
    gr4vy config add acme \
      --id acme \
      --environment sandbox \
      --merchant-account-id default \
      --key-file private_key.pem \
      --set-active
    ```
  </Step>

  <Step title="Verify it">
    ```sh theme={"system"}
    gr4vy config list      # shows profiles; * marks the active one
    gr4vy config show acme # the active profile (secrets redacted)
    ```
  </Step>
</Steps>

### Working with multiple instances

```sh theme={"system"}
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:

  ```sh theme={"system"}
  gr4vy login --email you@example.com   # prompts for the password
  gr4vy logout
  ```

## Generating tokens

```sh theme={"system"}
# 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:

```sh theme={"system"}
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.

```sh theme={"system"}
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:

```sh theme={"system"}
gr4vy --help
gr4vy transactions --help
gr4vy transactions list --help
```

The full, per-command reference lives in the
[CLI repository](https://github.com/gr4vy/gr4vy-cli/blob/main/docs/gr4vy.md).

## Output formats

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

```sh theme={"system"}
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:

```sh theme={"system"}
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.