Documentation Index
Fetch the complete documentation index at: https://docs.natural.co/llms.txt
Use this file to discover all available pages before exploring further.
The Natural CLI lets you create payments, check balances, and manage agents from your terminal.
Installation
npm install -g @naturalpay/cli
Authentication
The CLI resolves your API key in this order:
--api-key / -k flagNATURAL_API_KEY environment variable~/.natural/credentials.json ({ "apiKey": "sk_ntl_prod_..." })
Keys must start with sk_ntl_dev_, sk_ntl_sandbox_, or sk_ntl_prod_. Run natural doctor to verify your setup (validates the API key, pings the API, and reports SDK/CLI/Node versions).
Quick start
export NATURAL_API_KEY=sk_ntl_prod_...
# Check wallet balance
natural balance
# Create a payment
natural pay \
--customer pty_019cd34e27c179bfbbe6870486b11b67 \
--recipient alice@example.com \
--amount 5000 \
--memo "Invoice #789"
# List recent transactions
natural tx list
# Get transaction details
natural tx get txn_019cd444a6d765890d021717a39bf97
Commands
Run natural <command> --help for the full flag reference on any command. For field-level details of the underlying HTTP calls, see the API reference.
| Command | Description |
|---|
natural balance | Get wallet balance with breakdown |
natural pay | Create a payment |
natural withdraw | Initiate a bank withdrawal |
natural tx list | List transactions with filtering and pagination |
natural tx get <id> | Get transaction details by ID |
natural agents list | List registered agents |
natural agents get <id> | Get an agent by ID |
natural agents create | Create a new agent |
natural agents update <id> | Update an existing agent |
natural agents delete <id> | Delete an agent |
natural delegations list | List agent delegations |
natural delegations get <id> | Get an agent delegation by ID |
natural customers list | List customers who have delegated payment authority |
natural doctor | Validate CLI environment (auth, API connectivity, versions) |
Global flags
All commands accept these flags:
| Flag | Description |
|---|
-k, --api-key | API key override |
-j, --json | JSON output |
--timeout | HTTP timeout in ms (default: 30000) |
--base-url | API base URL override. Resolves --base-url flag → NATURAL_SERVER_URL env var → default (https://api.natural.co). |
JSON mode
Pass --json (or -j) to get structured output from any command. JSON mode is also enabled automatically when stdout is not a TTY (piped or redirected).
natural balance --json
natural tx list --json | jq '.transactions[0]'
Exit codes
| Code | Meaning |
|---|
| 0 | Success |
| 1 | Business logic error (invalid request, payment error) |
| 2 | Usage error (missing flags, bad arguments) |
| 3 | Authentication error |
| 4 | Network or server error |
- SDKs — Use the same API from Python or TypeScript
- APIs — Direct REST access
- Dashboard — Onboarding and managing your account
