CLI

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, and set up the agent and wallets your code will run against. Every resource 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.com/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.

To pin a version, run curl -fsSL https://natural.com/install.sh | NATURAL_VERSION=x.y.z bash. Natural publishes .zip archives for macOS and .tar.gz archives for Linux, with Intel and ARM builds, under https://natural.com/install/v<version>/. Check the current version.

Update

Once installed, natural update upgrades the CLI in place:

natural update

Authenticate

For local, interactive use, sign in with browser OAuth:

natural login
natural status

natural login opens a Natural authorization page, returns through a local redirect, and stores OAuth credentials on your machine. Access tokens are short-lived and refreshed automatically, so you can use the full CLI without creating or pasting an API key. Use an API key for CI, non-interactive scripts, SDK/REST integrations, or as an explicit override:

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 wallets list

Every command is natural <resource> <verb> [flags]. Add --help to any command for its flags.

Test in the sandbox

Point the CLI at the sandbox with a sandbox key, and use the natural simulations commands to act as the counterparty:

export NATURAL_API_KEY=sk_ntl_sandbox_abc123...
export NATURAL_BASE_URL=https://api.sandbox.natural.com

natural simulations inviteCustomer \
  --json '{"agentIds": ["agt_019cd1798d637a4da75dce386343931d"]}' \
  --idempotency-key "$(uuidgen)"

See Sandbox from MCP, CLI, and SDKs for the full simulation surface.

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 \
  --params '{"counterparty": {"type": "email", "value": "contractor@example.com"}}' \
  --description "Q4 development work" \
  --idempotency-key "$(uuidgen)" \
  --debug

--amount is in cents. counterparty is a typed object (email, phone, party_id, agent_id, or handle) passed through --params, or send the whole body with --json. 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) customer connections. Set them up once:

# Create the agent identity your code will run as
natural agents create \
  --name "Natural Bot" \
  --description "Pays delivery carriers" \
  --idempotency-key "$(uuidgen)"

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

# Invite a customer to authorize your agent
natural customers createInvitations --json '{
  "recipients": [{ "type": "email", "value": "customer@example.com" }],
  "agents": [{
    "agentId": "agt_019cd1798d637a4da75dce386343931d",
    "permissions": ["payments.create"]
  }]
}'

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 wallets 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_019cd444a6d765890d021717a39bf977

# 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

Flags that work on every command

Flag	What it does
`--format`	Output format: `json`, `table`, `yaml`, `csv`, `raw`, `jsonl`, `http`. Defaults to `table` in a terminal, `json` when piped
`--query`	Filter output with a JMESPath expression
`--params`	Merge additional request parameters as JSON (overrides individual flags)
`--json`	Full JSON request body (`-` reads stdin); replaces the per-field flags
`--base-url`	Override the API base URL (or set `NATURAL_BASE_URL`)
`--dry-run`	Validate the request locally without sending it to the API
`--debug`	Dump the full HTTP request and response to stderr
`-q, --quiet`	Suppress stdout output on success
`--version`, `-V`	Print the CLI version

The API key comes from the NATURAL_API_KEY environment variable or your stored OAuth login; there is no key flag.

SDKs: Python and TypeScript client libraries
MCP: Connect Claude, Cursor, and other AI hosts to Natural
API reference: Field-level detail for every endpoint

Overview

Agents

Customers

Payments

Transactions

Transfers

Payment Requests

Approvals

Limits

Parties

Party Invitations

Wallets

Wallet Access

External Accounts

API keys

Agent keys

Webhooks

Events

Errors

Install

Update

Authenticate

Test in the sandbox

Test a call before you code it

Provision what your agent runs against

Check what your agent sees

Flags that work on every command

​Install

​Update

​Authenticate

​Test in the sandbox

​Test a call before you code it

​Provision what your agent runs against

​Check what your agent sees

​Flags that work on every command

​Related

Install

Update

Authenticate

Test in the sandbox

Test a call before you code it

Provision what your agent runs against

Check what your agent sees

Flags that work on every command

Related