Developer Platform
View as Markdown Open in ChatGPT Open in Claude

Gravv CLI

Try Gravv from your terminal: install the gravv CLI, run a whole sandbox flow with one command, print every call as curl, and watch the webhooks it sends.

The gravv command line tool runs the Gravv API from your terminal. In sandbox it can run a whole flow for you, such as funding a wallet or paying a Nigerian bank account, and print each call as a curl command you can copy into your own code.

Example. You run gravv try wallet. The CLI makes a test customer and a Polygon wallet and starts a 20.00 USD bank collection. It pays the collection with the collection simulator and waits until it completes. Then it reads the balance, which is 20 USDC. Each step prints one line with the ids it made. Add --curl, and the CLI also prints every call as curl.

Before you start

  • A sandbox API key that starts with grvSec_sandbox_. See Authentication. Journeys and simulators run only with a sandbox key.
  • macOS or Linux.

Install

curl -fsSL https://get.gravv.xyz | sh

Or with Homebrew:

brew tap GravityFinance/tap https://github.com/GravityFinance/gravv-cli-releases
brew install gravv

Then save your key and check the setup:

gravv init      # paste your sandbox key; it is checked with Gravv and saved
gravv doctor    # says whether the key, environment and docs are ready

In CI or a container, set GRAVV_SANDBOX_KEY instead. The CLI never prints your key. Printed commands use $GRAVV_SANDBOX_KEY in its place.

Run a whole flow with one command

gravv try runs a journey. A journey is a short list of real sandbox calls that ends in a result you can see.

gravv try --list          # every journey, and whether it works in sandbox today
gravv try wallet          # a customer, a wallet and 20 test USDC in it
gravv try payout-ng       # the wallet journey, then 5.00 USD to a Nigerian bank account
gravv try wallet --curl   # the same, printing every call as curl
Journey What it does
wallet Makes a customer and a Polygon wallet, then pays a 20.00 USD bank collection into it with the simulator
payout-ng The wallet journey, then a Nigerian bank payee and a 5.00 USD payout
payout-ug The wallet journey, then a Ugandan mobile money payee and a 5.00 USD payout
usdc-send The wallet journey, then a 2.00 USDC send on Polygon testnet
collection-outcomes Card payment intents that succeed, are declined, and are disputed and won
ngn-account Opens an NGN account and simulates a 50,000.00 NGN deposit. Needs --customer with a verified customer
card Funds and spends on a sandbox card. Needs --card with an active card

gravv try --list shows which journeys work in sandbox today and which need a flag. If a step fails, the CLI says why and how to fix it. Run the same command with --resume to continue from that step, without making a second customer or sending a payment twice.

See every call

Every command can show its request:

gravv customers list --curl       # prints the curl command, then runs it
gravv customers list --dry-run    # prints the request and sends nothing
gravv api-activity list           # the requests this CLI sent, newest first

The CLI keeps your last 500 requests in ~/.gravv/audit.log, with the method, path, status, request id and Idempotency-Key. It does not write request or response bodies to disk. api-activity list shows 20 of them. Add --limit for more.

When the API refuses a call, the CLI prints the error, the request id and the fix from the error guide, with the CLI command that applies it.

Everyday commands

Each command calls one API route. Run any command with --help to see its flags and an example.

Command What it does
gravv customers list Lists your customers
gravv customers get-id <customer-id> Reads one customer
gravv customers kyc-status <customer-id> Shows the status of the customer's KYC check
gravv accounts capabilities --country NG --customer-type business Lists the accounts a customer in that country can open
gravv accounts v2 requirements --country US --customer-type business --account-type virtual_account Lists the fields and documents an account needs
gravv accounts v2 create --customer-id <id> --account-type <type> --currency USD --data-file intake.json Applies for an account. The account starts pending
gravv accounts v2 list --customer-id <customer-id> Lists a customer's accounts
gravv accounts v2 simulate-deposit --account-id <id> --amount 50000 --currency NGN Puts a test deposit in a sandbox NGN account
gravv wallets list Lists your wallets
gravv wallets balance <wallet-id> Shows a wallet's balance on the blockchain
gravv external-accounts list Lists your payees
gravv transactions list Lists your transactions, newest first
gravv transactions get <transaction-id> Reads one transaction and its status

Add --json to any command to print JSON instead of a table, so you can pipe it into jq or a script.

Sandbox and live

The key you save decides the environment. A key that starts with grvSec_sandbox_ is a sandbox key. Any other key is live. gravv init saves the key for its environment and makes that environment active.

gravv env get              # shows the active environment
gravv env set sandbox      # use your saved sandbox key
gravv env set production   # use your saved live key

With a live key, the CLI refuses any command that moves money unless you add --live. A refused command sends nothing. With --live it asks you to type yes first. In a script, add --yes as well to skip that question. The CLI uses the same list of calls that move money as the Gravv MCP server. It refuses every simulator on a key that is not a sandbox key.

Watch your webhooks

gravv webhooks tail

tail prints each webhook Gravv sends for your sandbox calls, with its type, delivery status, attempts and ids. It reads the delivery history, so it needs no public URL. A delivery prints again when Gravv retries it.

To receive the events in your own app, run the listener and give it a tunnel:

gravv webhooks listen --port 8080 --secret whsec_abc123 --forward http://localhost:3000/webhooks
cloudflared tunnel --url http://localhost:8080

Set the https URL the tunnel prints as your sandbox webhook URL in the Dashboard. With --secret, the listener checks each X-Signature as described in Verify webhook signatures. It answers 401 to a bad signature, so you see Gravv retry as it would against your server.

Read the docs offline

gravv docs

These guides ship inside the CLI, so they work offline and match your version. gravv docs --update fetches the latest published copy.

Was this page helpful?