--- title: "Gravv CLI" description: "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](/getting-started/authentication). Journeys and simulators run only with a sandbox key. - macOS or Linux. ## Install ```bash title="Install" curl -fsSL https://get.gravv.xyz | sh ``` Or with Homebrew: ```bash title="Homebrew" brew tap GravityFinance/tap https://github.com/GravityFinance/gravv-cli-releases brew install gravv ``` Then save your key and check the setup: ```bash title="Set up" 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. ```bash title="Journeys" 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: ```bash title="Show requests" 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](/getting-started/errors), 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 ` | Reads one customer | | `gravv customers kyc-status ` | 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 --account-type --currency USD --data-file intake.json` | Applies for an account. The account starts `pending` | | `gravv accounts v2 list --customer-id ` | Lists a customer's accounts | | `gravv accounts v2 simulate-deposit --account-id --amount 50000 --currency NGN` | Puts a test deposit in a sandbox NGN account | | `gravv wallets list` | Lists your wallets | | `gravv wallets balance ` | 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 ` | 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. ```bash title="Switch environments" 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](/tools/mcp-server#money-moving-tools-take-two-calls). It refuses every simulator on a key that is not a sandbox key. ## Watch your webhooks ```bash title="Watch deliveries" 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](/api-reference/webhooks/get-v1-webhooks-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: ```bash title="Receive deliveries" 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](/platform/webhooks/webhooks-overview#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 ```bash title="Docs" gravv docs ``` These guides ship inside the CLI, so they work offline and match your version. `gravv docs --update` fetches the latest published copy. ## Related - [Sandbox recipes](/recipes/sandbox/overview): what sandbox can produce for each product today. - [Gravv MCP server](/tools/mcp-server): the same API for an AI assistant.