Skip to navigation
OverviewOur platform

CLI

Command-line interface for Natural

The natural-api CLI maps every API endpoint to a terminal command. Use it for scripting, CI pipelines, or when you prefer the command line over an SDK.

Install

Install the Rust toolchain if you don’t have it, then build from source:

git clone https://github.com/fern-demo/natural-cli.git
cd natural-cli
cargo build --release
./target/release/natural-api --help

Authenticate

Set the NATURAL_API_TOKEN environment variable. The CLI also auto-loads a .env file in the working directory.

export NATURAL_API_TOKEN=sk_ntl_prod_...

Usage

Every Natural resource appears as a subcommand. Pass request bodies with individual --data.attributes.* flags or --json:

natural-api agents list
natural-api agents create \
  --idempotency-key "create-my-agent" \
  --data.attributes.name "My Agent" \
  --data.attributes.description "Handles payments"
natural-api payments create \
  --idempotency-key "pay-123" \
  --json '{"data":{"attributes":{"amount":500000,"currency":"USD","counterparty":{"type":"email","value":"user@example.com"},"description":"Invoice payment"}}}'
natural-api transactions get --transaction-id txn_abc123
natural-api wallets list
natural-api external-accounts list
natural-api transfers initiateDeposit \
  --idempotency-key "dep-123" \
  --json '{"data":{"attributes":{"amount":5000000,"currency":"USD","externalAccountId":"eac_xyz"}}}'

Use natural-api --help or natural-api <command> --help for full option details.

Dry run

The --dry-run flag renders the exact HTTP request the CLI would send, without executing it. Useful for scripting and agent workflows:

natural-api payments create --dry-run \
  --idempotency-key "test-123" \
  --json '{"data":{"attributes":{"amount":10000,"counterparty":{"type":"email","value":"test@example.com"}}}}'

Output formats

Use the --format flag to control output. Supported values: json (default), table, yaml, csv.

natural-api agents list --format table
natural-api transactions get --transaction-id txn_abc123 --format yaml

Environment variables

VariableDescription
NATURAL_API_TOKENBearer token for authentication
NATURAL_API_BASE_URLOverride the API base URL
NATURAL_API_CA_BUNDLEPath to PEM file with extra trust roots (or SSL_CERT_FILE)
NATURAL_API_INSECURE=1Skip TLS verification (debugging only)
NATURAL_API_PROXYHTTP(S) proxy URL
NATURAL_API_TIMEOUT_SECSTotal request timeout in seconds

Shell completion

Generate shell completion scripts:

natural-api completion <bash|zsh|fish|powershell>
  • SDKs — Python, TypeScript, and Go libraries
  • REST API — Direct HTTP access
  • MCP — AI agent integration