# CLI Reference

The RailProtocol CLI (`rail`) is the primary tool for managing agent wallets, spend policies, and transactions. It is open source and available on [GitHub](https://github.com/railprotocol/cli).

***

## Installation

```bash
npm install -g @railprotocol/cli
```

See [Installation](/getting-started/installation.md) for all installation options.

***

## Authentication

```bash
rail auth login
```

Opens a browser window to authenticate. Credentials are stored in `~/.railprotocol/credentials`.

```bash
rail auth login --token $RAIL_API_KEY
```

Non-interactive authentication for CI/CD environments.

```bash
rail auth logout
```

Removes stored credentials.

```bash
rail auth status
```

Shows the currently authenticated account.

***

## `rail wallet`

Manage agent wallets.

### `rail wallet create`

Create a new wallet for an agent.

```bash
rail wallet create --agent <agent-id>
```

### `rail wallet get`

Show wallet address and balance for an agent.

```bash
rail wallet get --agent <agent-id>
```

Output:

```
Agent:    my-agent
Address:  7xKXtg2xpAGMq8KLwpSodE9LFKq8Z1EscezSShpump
Balance:  42.50 USDC
Network:  Solana Mainnet
```

### `rail wallet balance`

Show balance only.

```bash
rail wallet balance --agent <agent-id>
# Balance: 42.50 USDC
```

### `rail wallet fund`

Initiate a top-up from your account's linked funding source.

```bash
rail wallet fund <agent-id> --usdc <amount>
```

### `rail wallet withdraw`

Withdraw USDC from a wallet to a Solana address.

```bash
rail wallet withdraw <agent-id> \
  --to <solana-address> \
  --usdc <amount>
```

### `rail wallet import`

Import an existing Ed25519 keypair as the agent's wallet keypair.

```bash
rail wallet import <agent-id> --keypair ./keypair.json
```

### `rail wallet explorer`

Open the Solana Explorer page for the agent's wallet address.

```bash
rail wallet explorer <agent-id>
```

***

## `rail policies`

Manage spend policies for agents.

### `rail policies set`

Set or update spend policies for an agent.

```
rail policies set <agent-id> [flags]
```

**Flags:**

| Flag                    | Type   | Description                                                 |
| ----------------------- | ------ | ----------------------------------------------------------- |
| `--daily-budget`        | number | Maximum USDC spend per 24-hour rolling window               |
| `--per-call-limit`      | number | Maximum USDC per individual payment call                    |
| `--allowed-domains`     | string | Comma-separated list of allowed domains                     |
| `--blocked-domains`     | string | Comma-separated list of blocked domains                     |
| `--rate-limit`          | string | Rate limit in format `"N per window"` (e.g. `"500 per 1h"`) |
| `--protocol-preference` | string | `auto`, `x402`, or `mpp`                                    |

**Example:**

```bash
rail policies set research-agent \
  --daily-budget 25 \
  --per-call-limit 1.00 \
  --allowed-domains "api.dune.com,fal.ai" \
  --rate-limit "200 per 1h" \
  --protocol-preference x402
```

### `rail policies get`

Show active policies for an agent.

```bash
rail policies get <agent-id>
```

### `rail policies clear`

Remove all spend policies from an agent. The agent will have no restrictions.

```bash
rail policies clear <agent-id>
```

***

## `rail transactions`

Inspect on-chain payment records.

### `rail transactions list`

List recent transactions.

```
rail transactions list [flags]
```

**Flags:**

| Flag         | Type    | Default | Description                              |
| ------------ | ------- | ------- | ---------------------------------------- |
| `--agent`    | string  | —       | Filter to a specific agent               |
| `--protocol` | string  | —       | Filter by `x402` or `mpp`                |
| `--domain`   | string  | —       | Filter by endpoint domain                |
| `--since`    | string  | `1h`    | Show transactions from this duration ago |
| `--limit`    | integer | `50`    | Maximum number of results                |
| `--json`     | boolean | `false` | Output as JSON                           |

**Example:**

```bash
rail transactions list --agent my-agent --protocol x402 --since 24h
```

### `rail transactions inspect`

Show full details for a transaction.

```bash
rail transactions inspect <tx-hash>
```

### `rail transactions tree`

Show the full on-chain payment tree for a multi-agent chain.

```bash
rail transactions tree <root-tx-hash>
```

### `rail transactions explorer`

Open the Solana Explorer entry for a transaction.

```bash
rail transactions explorer <tx-hash>
```

***

## `rail spend`

View spend summaries.

```
rail spend [flags]
```

**Flags:**

| Flag       | Type   | Default | Description                                      |
| ---------- | ------ | ------- | ------------------------------------------------ |
| `--agent`  | string | —       | Filter to one agent (omit for account total)     |
| `--window` | string | `24h`   | Time window                                      |
| `--by`     | string | `agent` | Group by `agent`, `protocol`, `domain`, or `day` |

**Example:**

```bash
rail spend --window 7d
rail spend --agent research-agent --by domain
```

***

## `rail sessions`

Manage MPP payment sessions.

### `rail sessions list`

Show active MPP sessions for an agent.

```bash
rail sessions list --agent <agent-id>
```

### `rail sessions clear`

Clear sessions for a specific domain (forces renegotiation on the next call).

```bash
rail sessions clear --agent <agent-id> --domain <domain>
```

***

## `rail alerts`

Manage spend and policy alerts.

### `rail alerts create`

```
rail alerts create [flags]
```

**Flags:**

| Flag          | Type   | Description                                                               |
| ------------- | ------ | ------------------------------------------------------------------------- |
| `--agent`     | string | Agent to attach the alert to                                              |
| `--type`      | string | `budget_pct`, `spend_rate`, or `policy_violation`                         |
| `--threshold` | number | Threshold value (percentage for `budget_pct`, USDC for `spend_rate`)      |
| `--window`    | string | Time window (for `spend_rate`)                                            |
| `--notify`    | string | Notification target: `webhook:<url>`, `email:<address>`, or `slack:<url>` |

**Examples:**

```bash
# Alert when 80% of daily budget is consumed
rail alerts create \
  --agent my-agent \
  --type budget_pct \
  --threshold 80 \
  --notify webhook:https://hooks.yourapp.com/rail

# Alert on any policy violation
rail alerts create \
  --agent my-agent \
  --type policy_violation \
  --notify email:you@example.com
```

### `rail alerts list`

```bash
rail alerts list
rail alerts list --agent my-agent
```

### `rail alerts delete`

```bash
rail alerts delete <alert-id>
```

***

## `rail agents`

Manage agent registrations.

### `rail agents list`

```bash
rail agents list
```

Output:

```
NAME                WALLET ADDRESS          BALANCE     POLICIES
research-agent      7xKXtg2x...ShpUMP      42.50 USDC  daily: 25 USDC, per-call: 1.00 USDC
writer-agent        9zXKtg2x...ShpUMP      10.00 USDC  daily: 10 USDC, per-call: 0.50 USDC
```

### `rail agents delete`

Delete an agent and all associated data (wallet keypair, policies, session state). The wallet balance must be zero before deletion.

```bash
rail agents delete <agent-id>
```

***

## `rail team`

Manage team members (Team and Enterprise plans).

```bash
rail team list
rail team invite --email colleague@example.com --role developer
rail team remove --email colleague@example.com
```

**Roles:** `owner`, `admin`, `developer`, `viewer`

***

## `rail audit`

View the account audit log (Team and Enterprise plans).

```bash
rail audit --window 7d
rail audit --agent my-agent --window 30d
rail audit export --window 30d --format json > audit-may-2026.json
```

***

## Global flags

These flags apply to every command:

| Flag         | Description                           |
| ------------ | ------------------------------------- |
| `--help`     | Show help for a command               |
| `--json`     | Output as JSON                        |
| `--no-color` | Disable colored output                |
| `--api-key`  | Override the API key for this command |
| `--version`  | Show CLI version                      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.railprotocol.org/cli/reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.