Skip to main content

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 is the fastest way to exercise the Natural API while you build an agent — run a call before you wire it into code, set up the agent and wallets your code will run against, and see the exact request your SDK would send. Every command maps one-to-one to an API endpoint.

​
Install

The install script auto-detects your OS and architecture and needs no toolchain — macOS and Linux: 
curl -fsSL https://natural.co/install.sh | bash
The installer downloads the release artifact for your platform, verifies its checksum, and installs natural to ~/.natural/bin, adding that directory to your shell profile when possible. Confirm it: 
natural --version
Restart your shell after installation if natural is not immediately found on your PATH.
On Windows, or to install through a system package manager, grab a build from the latest release — .deb, .rpm, .apk, Arch, and .zip archives are published for every platform. To build from source with Go 1.25+: 
go install github.com/naturalpay/cli/cmd/natural@latest
go install drops the binary in $(go env GOPATH)/bin — add that to your PATH if natural isn’t found.

​
Authenticate

export NATURAL_API_KEY=sk_ntl_prod_abc123...
Get a key from the Developers tab of the dashboard. Production keys are prefixed sk_ntl_prod_. Confirm it works: 
natural wallet list
Every command is natural <resource> <verb> [flags]. Add --help to any command for its flags.

​
Test a call before you code it

Run an endpoint from the terminal and see the real response shape before you wire it into your agent. --debug prints the full HTTP request and response — the same call your SDK will make: 
natural payments create \
  --amount 500000 \
  --currency USD \
  --counterparty '{type: email, value: terri@contractor.com}' \
  --description "Q4 development work" \
  --idempotency-key "$(uuidgen)" \
  --debug
--amount is in cents. --counterparty takes a party ID (pty_*), email, or phone. Reusing an --idempotency-key safely returns the original result instead of charging twice.

​
Provision what your agent runs against

Your agent needs an agent identity, a funded wallet, and — when it acts for customers — delegations. Set them up once: 
# Create the agent identity your code will run as
natural agents create \
  --name "Carrier Payment Agent" \
  --description "Pays delivery carriers" \
  --idempotency-key "$(uuidgen)"

# Pull funds into your wallet from a linked bank account
natural transfers initiate-deposit \
  --amount 5000000 \
  --external-account-id eac_550e8400e29b41d4a716446655440000 \
  --idempotency-key "$(uuidgen)"

# Invite a customer to delegate payment authority to your agent
natural agents create-customer \
  --agent-id agt_019cd1798d637a4da75dce386343931d \
  --recipient '{type: email, value: bruce@propertymanagement.com}' \
  --permission payments.create \
  --idempotency-key "$(uuidgen)"
Link a bank account from the Wallet tab of the dashboard first — natural external-accounts list then gives you the eac_* id to deposit from.

​
Check what your agent sees

When you’re debugging agent behavior, inspect the same state your agent reads: 
# Wallet balances + ACH deposit instructions
natural wallet list

# Transaction history — --type is payment, transfer, or all
natural transactions list --limit 20 --type payment

# A single transaction's status
natural transactions get --transaction-id txn_019cd444a6d765890d021717a39bf97

# Your agents and customer relationships
natural agents list
natural customers list

# An inbound payment request by id
natural payment-requests get --payment-request-id prq_019cd1798d637a4da75dce386343931d

​
Script setup and CI

--format json plus jq makes the CLI scriptable for seed scripts and CI: 
natural transactions list --format json | jq '.data[0].id'
--transform filters output without piping to a separate tool: 
natural wallet list --transform 'data[0].attributes.balance.available'
Commands exit 0 on success and non-zero on failure — check $? in scripts.

​
Flags that work on every command

FlagWhat it does
--api-keyAPI key override (or set NATURAL_API_KEY)
--formatOutput format: auto, explore, json, jsonl, pretty, raw, yaml
--base-urlOverride the API base URL (or set NATURAL_BASE_URL)
--environmentSet the API environment
--debugVerbose logging, including the full HTTP request/response
-r, --raw-outputPrint string results without JSON quotes
--transformTransform output with GJSON syntax
--version, -vPrint the CLI version
The full resource surface — payments, wallet, transactions, transfers, agents, customers, payment-requests, external-accounts — maps directly to API endpoints (natural payments create is POST /payments). Run natural <resource> --help to explore.
  • SDKs — the same API from Python or TypeScript, for your agent runtime
  • MCP — connect Claude or Cursor to Natural
  • API reference — field-level detail for every endpoint