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

# 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, 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:

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

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

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

On Windows, or to install through a system package manager, grab a build from the [latest release](https://github.com/naturalpay/cli/releases/latest) — `.deb`, `.rpm`, `.apk`, Arch, and `.zip` archives are published for every platform.

To build from source with [Go](https://go.dev/doc/install) 1.25+:

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

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 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:

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

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

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

```bash theme={null}
natural transactions list --format json | jq '.data[0].id'
```

`--transform` filters output without piping to a separate tool:

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

| Flag               | What it does                                                                                 |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `--api-key`        | API key override (or set `NATURAL_API_KEY`)                                                  |
| `--format`         | Output format: `auto`, `explore`, `json`, `jsonl`, `pretty`, `raw`, `yaml`                   |
| `--base-url`       | Override the API base URL (or set `NATURAL_BASE_URL`)                                        |
| `--environment`    | Set the API environment                                                                      |
| `--debug`          | Verbose logging, including the full HTTP request/response                                    |
| `-r, --raw-output` | Print string results without JSON quotes                                                     |
| `--transform`      | Transform output with [GJSON syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md) |
| `--version`, `-v`  | Print 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.

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