> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# CLI

> Test, provision, and debug the Natural API from your terminal while you build an agent

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:

```bash theme={null}
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:

```bash theme={null}
natural --version
```

<Note>
  Restart your shell after installation if `natural` is not immediately found on your `PATH`.
</Note>

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](https://natural.com/install/VERSION).

## Update

Once installed, `natural update` upgrades the CLI in place:

```bash theme={null}
natural update
```

## Authenticate

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

```bash theme={null}
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:

```bash theme={null}
export NATURAL_API_KEY=sk_ntl_prod_abc123...
```

Get a key from the **Developers** tab of the [dashboard](/guides/platform/dashboard). Production keys are prefixed `sk_ntl_prod_`.

Confirm it works:

```bash theme={null}
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](/api-reference/sandbox/overview) with a sandbox key, and use the `natural simulations` commands to act as the counterparty:

```bash theme={null}
export NATURAL_API_KEY=sk_ntl_sandbox_abc123...
export NATURAL_BASE_URL=https://api.sandbox.natural.com

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

See [Sandbox from MCP, CLI, and SDKs](/api-reference/sandbox/surfaces) 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:

```bash theme={null}
natural payments create \
  --amount 50000 \
  --currency USD \
  --params '{"counterparty": {"type": "email", "value": "ada@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 for 48 hours 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:

```bash theme={null}
# Create the agent identity your code will run as
natural agents create \
  --name "Procurement Agent" \
  --description "Buys supplies" \
  --idempotency-key "$(uuidgen)"

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

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

Link a bank account from the **Wallets** 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:

```bash theme={null}
# Wallet balances (read one wallet for its ACH account and routing numbers)
natural wallets list
natural wallets get --wallet-id wal_...

# 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_019cd1798d6672a7b828eee780291b72

# 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_019cd1798d7a68fe07c972bed48fb7fd
```

## 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 |
| `--human` | Force table output even when piped |
| `--query` | Filter output with a [JMESPath](https://jmespath.org) expression |
| `--params` | Merge additional request parameters as JSON (overrides individual flags) |
| `--json` | Full JSON request body (`-` reads stdin); replaces the per-field flags |
| `--x-instance-id` | Send the `X-Instance-ID` header: a caller-chosen identifier for the agent run or conversation, required when an agent moves money |
| `--base-url` | Override the API base URL (or set `NATURAL_BASE_URL`) |
| `--dry-run` | Validate the request locally without sending it to the API |
| `--schema` | Print a machine-readable JSON schema for the command, the agent-facing counterpart to `--help` |
| `--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.

## Related

* [SDKs](/guides/platform/sdks): Python and TypeScript client libraries
* [MCP](/guides/platform/mcp): Connect Claude, Cursor, and other AI hosts to Natural
* [API reference](/api-reference): Field-level detail for every endpoint


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.