Skip to main content
The Natural CLI lets you create payments, check balances, and manage agents from your terminal.

​
Installation

npm install -g @naturalpay/cli
Requires Node.js 20+.

​
Authentication

The CLI resolves your API key in this order:
  1. --api-key / -k flag
  2. NATURAL_API_KEY environment variable
  3. ~/.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.
CommandDescription
natural balanceGet wallet balance with breakdown
natural payCreate a payment
natural withdrawInitiate a bank withdrawal
natural tx listList transactions with filtering and pagination
natural tx get <id>Get transaction details by ID
natural agents listList registered agents
natural agents get <id>Get an agent by ID
natural agents createCreate a new agent
natural agents update <id>Update an existing agent
natural agents delete <id>Delete an agent
natural delegations listList agent delegations
natural delegations get <id>Get an agent delegation by ID
natural customers listList customers who have delegated payment authority
natural doctorValidate CLI environment (auth, API connectivity, versions)

​
Global flags

All commands accept these flags:
FlagDescription
-k, --api-keyAPI key override
-j, --jsonJSON output
--timeoutHTTP timeout in ms (default: 30000)
--base-urlAPI 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

CodeMeaning
0Success
1Business logic error (invalid request, payment error)
2Usage error (missing flags, bad arguments)
3Authentication error
4Network or server error
  • SDKs — Use the same API from Python or TypeScript
  • APIs — Direct REST access
  • Dashboard — Onboarding and managing your account