CLI

CLI Reference

The rail CLI lets you manage wallets, policies, and transactions from the terminal, useful for scripts, CI pipelines, and one-off operations.

ℹ️

The CLI ships as Phase 2 (Q4 2026). This page documents the planned interface. Commands and flags may change before release.

Installation

bash

npm install -g @fixerprotocol/cli
# or
bun add -g @fixerprotocol/cli

Verify the installation:

bash

rail --version
# Fixer Protocol CLI v0.2.0

Global flags

These flags are available on every command:

--agent

string

Agent ID to use. Overrides FIXER_AGENT_ID env var.

--api-key

string

API key. Overrides FIXER_API_KEY env var and saved credentials.

--json

flag

Output raw JSON instead of formatted text. Useful for piping to jq.

--quiet, -q

flag

Suppress all output except errors. Exit code indicates success/failure.

rail auth

Manage authentication credentials. Credentials are stored in ~/.config/rail/credentials.json.

rail auth login

bash

rail auth login

Prompts for your API key interactively. Saves it to the credentials file. Use --api-key to pass it non-interactively:

bash

# Non-interactive (useful in CI)
rail auth login --api-key "$FIXER_API_KEY" --agent "my-agent"

rail auth logout

bash

rail auth logout

Removes saved credentials from disk. Does not invalidate the API key itself, do that from the dashboard.

rail auth status

bash

rail auth status
# Authenticated as: my-agent (fxp_live_xxxx...xxxx)
# Gateway: https://api.fixerprotocol.org

rail wallet

rail wallet balance

bash

rail wallet balance
# Balance: 42.50 USDC

rail wallet balance --json
# {"usdc": 42.50}

rail wallet address

bash

rail wallet address
# 7xKXtg2eH9sZ7pWbRqTJ3mQfJLxxxxxxxxxxxxxx

# Copy to clipboard (macOS)
rail wallet address | pbcopy

rail wallet fund

bash

rail wallet fund --usdc 50

# With idempotency key (safe to re-run in scripts)
rail wallet fund --usdc 50 --idempotency-key "top-up-$(date +%Y%m%d)"

Output:

bash

# Funded: +50 USDC
# Tx hash: 7KLMnPqR2sTuWxYzAcBdEf7jKLMn
# New balance: 92.50 USDC
# Solana: https://explorer.solana.com/tx/7KLMnPqR2sTuW...

rail policies

rail policies get

bash

rail policies get
# Daily budget:   100 USDC
# Per-call limit:   1.00 USDC
# Allowed domains: api.dune.com, api.browserbase.com, fal.ai
# Rate limit:     500 calls / 1h

rail policies set

bash

rail policies set \
  --daily-budget 100 \
  --per-call-limit 1.00 \
  --allowed-domains "api.dune.com,api.browserbase.com,fal.ai" \
  --rate-limit "500/1h"

# Policy updated.

--daily-budget

number

optional

Maximum USDC spend per calendar day (UTC).

--per-call-limit

number

optional

Maximum USDC for any single payment.

--allowed-domains

string

optional

Comma-separated list of allowed hostnames. Empty = no restriction.

--blocked-domains

string

optional

Comma-separated list of blocked hostnames.

--rate-limit

string

optional

Rate limit as "N/window": e.g. "500/1h", "1000/24h", "50/1m".

rail policies clear

bash

rail policies clear
# All spend policies cleared. Agent spending is now unconstrained.

⚠️

rail policies clear removes all spend constraints immediately. Only use in development, always configure policies before deploying agents to production.

rail transactions

rail transactions list

bash

# Last 20 transactions (default)
rail transactions list

# Filter by time window
rail transactions list --last 24h
rail transactions list --last 7d
rail transactions list --from 2026-05-01 --to 2026-05-31

# Filter by protocol
rail transactions list --protocol x402

# Limit and format
rail transactions list --limit 50 --json | jq '.[].txHash'

Output:

bash

# HASH                    PROTOCOL  USDC    ENDPOINT                         STATUS     TIME
# 5xGh9KmBv...           x402      0.0020  api.dune.com                     confirmed  14:22:03
# 7KLMnPqR2s...          mpp       0.0120  fal.run                          confirmed  14:21:47
# 4nLm8Yq3J...           x402      0.0005  api.browserbase.com              confirmed  14:21:12

--last

string

optional

Time window: 1h, 24h, 7d, 30d.

--from, --to

string

optional

Date range. ISO 8601 date strings.

--protocol

string

optional

x402 or mpp.

--limit

number

optionaldefault: 20

Maximum results. Maximum: 100.

--agent

string

optional

Override the agent ID. Useful for inspecting other agents if your API key has multi-agent scope.

rail transactions get

bash

rail transactions get 5xGh9KmBv...

# Hash:       5xGh9KmBv...
# Protocol:   x402
# Amount:     0.002 USDC
# Endpoint:   https://api.dune.com/api/v1/query/3326266/results
# Status:     confirmed
# Timestamp:  2026-05-30T14:22:03Z
# Solana:     https://explorer.solana.com/tx/5xGh9KmBv...

rail pay

Route a one-off payment from the terminal, useful for testing endpoints or manual API calls.

bash

# Simple GET
rail pay --endpoint https://api.dune.com/api/v1/query/3326266/results

# POST with JSON body
rail pay \
  --endpoint https://api.browserbase.com/v1/sessions \
  --method POST \
  --body '{"url": "https://example.com"}'

# Private payment (full ZK mode)
rail pay \
  --endpoint https://api.proprietary.com/v1/signals \
  --privacy full

# With idempotency key
rail pay \
  --endpoint https://api.dune.com/api/v1/query/3326266/results \
  --idempotency-key "manual-run-2026-05-30"

--endpoint

string

required

Full HTTPS URL of the service to pay.

--method

string

optionaldefault: GET

HTTP method: GET, POST, PUT, PATCH, DELETE.

--body

string

optional

JSON request body for POST/PUT/PATCH.

--header

string (repeatable)

optional

Custom header in Key: Value format. Can be specified multiple times.

--privacy

string

optional

transparent (default), confidential_amount, or full.

--idempotency-key

string

optional

Client idempotency key for safe retries.

Shell Completion

bash

# Bash
rail completion bash >> ~/.bash_profile

# Zsh
rail completion zsh >> ~/.zshrc

# Fish
rail completion fish > ~/.config/fish/completions/rail.fish