@ray-inner/cli

Official Raydium CLI — a terminal-first interface over @raydium-io/raydium-sdk-v2. Wallet management, pool discovery, swaps, CPMM / CLMM / AMM liquidity, Launchpad bonding curves, farming, portfolio management, transaction debugging, SOL wrap/unwrap, and agent schema export in a single binary.

Built on Raydium SDK v2 alpha — the SDK commit is pinned per release. If an SDK bump breaks something, please file an issue rather than assuming a CLI bug.

Installation

npm install -g @ray-inner/cli
# or
pnpm add -g @ray-inner/cli

Requirements: Node.js ≥ 20 LTS.

Verify the install:

raydium --version        # prints CLI version + SDK tag
raydium --license        # prints the full GPL-3.0-or-later LICENSE text
raydium --help

Quickstart (5-minute path)

raydium init                                              # 1. interactive setup wizard
raydium wallet create                                     # 2. new keystore or import existing
raydium swap --in So11111111111111111111111111111111111111112 \
  --out EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --amount 1000000 --slippage-bps 100 --dry-run           # 3. price check
raydium swap --in So11111111111111111111111111111111111111112 \
  --out EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --amount 1000000 --slippage-bps 100 --yes               # 4. sign + broadcast

raydium init walks you through cluster, RPC endpoints, and default output. Config is persisted to ~/.config/raydium/config.json (override via RAYDIUM_CONFIG_PATH).

Write commands require --yes / -y to skip the confirmation prompt. Without it the command performs a dry-run and prints a simulation result without touching the chain.

Command Reference

Top-level flags apply everywhere:

| Flag | Values | Default | Purpose | | -------------------- | --------------------------- | -------- | -------------------------------------------------- | | --output <mode> | auto / human / json / jsonl | auto | Output format (auto detects TTY vs pipe) | | --verbose | boolean | false | Enable verbose stderr logging (RPC + simulation) | | --cluster <name> | mainnet-beta / devnet / testnet / localnet | — | Override configured cluster for this invocation | | --no-color | — | — | Disable ANSI colors (NO_COLOR env also honored) | | --license | — | — | Print the GPL-3.0-or-later LICENSE and exit | | -V, --version | — | — | Print CLI version + pinned SDK tag |

Subcommand groups:

| Group | Subcommands | Notes | | ------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | init | — (root command, interactive) | First-run setup wizard (FR-WIZARD) | | config | set <key> <value> / get [key] / keys / lock / unlock | unlock requires password; lock blocks set | | wallet | create / import / balance / address / transfer / unlock / lock / status / list / use | AES-256-GCM keystore (scrypt KDF) | | pool | list / info / search | Read-only. AMM / CPMM / CLMM unified row shape | | swap | swap [options] — single command: --in / --out / --amount / --dry-run / --yes | tradeV2 aggregator; no subcommands | | cpmm | swap / add / remove / create / collect-fee | Constant-product liquidity | | clmm | positions / info / create / open / increase / decrease / close / harvest / swap / lock | Concentrated liquidity (tick-based); lock is permanent | | launchpad | info / create / buy / sell / claim-vesting / collect-creator-fee | Bonding-curve lifecycle | | farm | info / list / deposit / withdraw / harvest / create / restart-reward / add-reward / withdraw-reward | Staking / reward farms | | amm | info / add / remove / swap / create | AMM v4 classic constant-product pools | | portfolio | scan / harvest-all | Cross-pool position overview and batch harvest | | market | create | OpenBook market creation (prerequisite for AMM create) | | sol | wrap / unwrap | SOL ↔ wSOL ATA management | | tx | decode / simulate / send | External-signer round trip (sign elsewhere, send here) | | schema | --format <mcp\|openai\|anthropic\|jsonschema> | Export the agent tool registry | | balance | — (alias for wallet balance) | Shortcut | | send | — (alias for wallet transfer) | Shortcut |

Run raydium <group> --help for every leaf verb's options. Exit codes: 0 success / 1 user error / 2 system error / 3 on-chain error / 4 confirmation needed.

Output Modes

| Mode | When to use | | -------- | ---------------------------------------------------------------------- | | auto | Default. Detects TTY and switches between human and json. | | human | Colored tables + emoji + suggestions. Safe for terminals. | | json | Single JSON object per command. Scripting / CI. | | jsonl | Streaming JSON lines — one record per row. Log aggregators. |

Errors follow the structured envelope: { error: { code, category, retryable, message, suggestion, details } }.

Signer Modes

Raydium CLI supports two signer modes, selected in raydium init or via RAYDIUM_SIGNER_MODE.

| Mode | Behavior | Use case | | ---------- | --------------------------------------------------------------------------------- | --------------------------------- | | inline | Decrypts the AES-256-GCM keystore locally and signs in-process | Human operator (Persona Alice) | | external | Returns { unsignedTx, simulation } as base64; caller signs and broadcasts | CI, hardware wallets, agent hosts | | file | Loads an unencrypted keypair JSON file and signs in-process | Testing / devnet | | pubkey | Read-only; no signing. Returns unsigned tx for any write command | Watch-only wallets, dry-run only | | agent | Delegates to a local signing-agent daemon via Unix socket (~/.config/raydium/agent.sock) | AI-headless automation |

Write commands never broadcast without --yes / -y. Default is dry-run — the CLI prints the simulated result and exits without touching the chain. Pass --dry-run explicitly to always force dry-run mode regardless of other flags.

Slippage is clamped in three bands (NFR-SEC): default 100bps / soft-cap 500bps (WARN) / hard-cap 2000bps (requires --i-understand-the-risk).

Environment Variables

Every CLI option can be overridden by an env var — useful for CI, Docker, MCP hosting.

| Variable | Required | Description | | ------------------------------- | ----------------- | ------------------------------------------------------------------------ | | RAYDIUM_RPC_ENDPOINTS | Yes (if no config) | Comma-separated RPC URLs. At least one. Used with p-retry failover. | | RAYDIUM_CLUSTER | No | mainnet-beta (default) / devnet | | RAYDIUM_SIGNER_MODE | No | inline / external (default external) | | RAYDIUM_KEYSTORE_PATH | When inline | Path to the encrypted keystore | | RAYDIUM_KEYSTORE_PASSWORD | CI / no TTY | Unlock the keystore without an interactive prompt (FR-WALLET-ENV) | | RAYDIUM_CONFIG_PATH | No | Alternate config file (default ~/.config/raydium/config.json) | | RAYDIUM_ELICIT_USD_THRESHOLD | No | Swap confirmation threshold in USD (default 500, MCP-only) | | NO_COLOR | No | Disable ANSI colors globally |

Secrets (RAYDIUM_KEYSTORE_PASSWORD) are never accepted as CLI arguments — env only. They are stripped from all logs.

Examples

# Pool discovery
raydium pool list --type CLMM --limit 10
raydium pool search --mint-a So11111111111111111111111111111111111111112 \
  --mint-b EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
raydium pool info --pool-id Hp4kNR5...

# Swap (single command: quote + build + sign/send)
raydium swap \
  --in  So11111111111111111111111111111111111111112 \
  --out EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --amount 1000000 --slippage-bps 100 --yes

# External signer round-trip (agent / CI workflow)
raydium swap \
  --in  So11111111111111111111111111111111111111112 \
  --out EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --amount 1000000 --output json > unsigned.json
# ... sign unsigned.tx elsewhere ...
raydium tx send --signed-tx "$(cat signed.b64)"

# Wallet
raydium wallet balance                          # active wallet
raydium balance                                 # shortcut alias
raydium wallet transfer --to <pubkey> --amount 1000000 --mint SOL --yes
raydium send --to <pubkey> --amount 1000000     # shortcut alias for wallet transfer
raydium wallet list                             # list all named wallets
raydium wallet use my-wallet                    # switch active wallet

# CLMM concentrated liquidity
raydium clmm positions                          # list positions for active wallet
raydium clmm harvest --nft <b58> --yes          # harvest fees
raydium clmm lock --position-nft-mint <b58> --i-understand-permanent-lock  # permanent lock

# Farm staking
raydium farm list
raydium farm deposit --farm-id <id> --amount 1000000 --yes
raydium farm harvest --farm-id <id> --yes

# AMM classic pools
raydium amm info --pool-id <id>
raydium amm swap --pool-id <id> --in <mint> --amount 1000000 --yes

# Portfolio
raydium portfolio scan                          # scan all Raydium positions
raydium portfolio harvest-all --yes             # harvest all CLMM fees + farm rewards

# SOL wrap/unwrap
raydium sol wrap --amount 1000000 --yes
raydium sol unwrap --yes

# Market (prerequisite for AMM v4 pool creation)
raydium market create --base-mint <mint> --quote-mint <mint> --yes

# Agent signing daemon
raydium wallet unlock --duration 1h --max-tx 50
raydium wallet status
raydium wallet lock

# Agent schema export
raydium schema --format mcp > tools.json
raydium schema --format openai > functions.json

Signing Agent (ADR-R8)

Local signing-agent daemon for AI-headless signing. Unlocks the keystore once with a password + policy; the daemon holds the decrypted Keypair in memory and signs transactions requested over a Unix socket (~/.config/raydium/agent.sock, mode 0600). AI agents and write-path commands invoke --signer agent:default and never see the private key.

Verbs

# Start a bounded signing session (TTY prompt or stdin-piped password).
raydium wallet unlock --duration 1h --max-tx 50
# > Agent unlocked. PID=12345  expires=2026-04-24T11:45:00Z  tx-budget=50

# Inspect the active session (read-only; does not extend TTL — Q-D).
raydium wallet status                            # 5 KV lines
raydium wallet status --output json              # machine-readable

# Stop the daemon (idempotent).
raydium wallet lock

Flags

| Flag | Required | Notes | | ---- | -------- | ----- | | --duration <dur> | yes | Human-readable: 1h, 30m, 45s, or combined 1h30m. Strictly positive; h → m → s order enforced. | | --max-tx <n> | yes | Positive integer, max 10 000. Decrements once per successful sign. At 0 the daemon auto-exits on the next idle tick. | | --label <name> | no | Keystore label (default default). | | --password-stdin | no | Read keystore password from stdin instead of the TTY prompt. Required in non-TTY contexts — see Q-A below. |

agent:<label> URI

The signer factory recognises the agent: scheme in addition to file: / keystore: / pubkey:. Resolution reads the daemon's sidecar pubkey file at ~/.config/raydium/agent.pubkey synchronously; signing requests traverse the socket asynchronously. Use it anywhere a signer URI is accepted:

RAYDIUM_SIGNER=agent:default raydium wallet transfer --to <pubkey> --amount 1000000 --yes

Unlike file: and keystore:, the agent: scheme is allowed under RAYDIUM_AGENT_MODE=1 — the AI process holds no key, so the security posture is equivalent to calling a remote HSM.

Non-TTY behavior (Q-A fail-loud)

When stdin is NOT a TTY AND neither --password-stdin nor RAYDIUM_KEYSTORE_PASSWORD is set, raydium wallet unlock refuses to run with SIGNING_AGENT_PASSWORD_REQUIRED (exit code 1). This is intentional: a silent prompt in a headless context would hang forever; matching ssh-add / gpg-agent precedent, we require callers to be explicit about their password source.

# In CI or an agent harness:
printf "%s" "$WALLET_PW" | raydium wallet unlock --duration 8h --max-tx 200 --password-stdin

Security caveats

• Socket + sidecar + PID file are all mode 0600 (owner-only).
• Policy is time + count only (Phase 1). Per-program allowlists, lamport caps, and multi-wallet sessions are deferred to Phase 2/3.
• Daemon auto-exits on: TTL expiry, quota exhausted, SIGTERM, or parent-death (1 s polling window, ≤3 s detection).
• No swap-to-disk protection in Phase 1 — mlock(2) / VirtualLock is evaluated for Phase 1.1.
• The CHANGELOG and ADR-R8 document the full scope + threat model.

Agent Integration

Raydium CLI ships a companion MCP server for AI agents (Claude Desktop, Cursor, Continue, …). See @ray-inner/mcp and the MCP integration guide for setup. You can also use raydium schema --format openai|anthropic to feed the tool schemas to any function-calling agent framework.

License

Distributed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). Run raydium --license for the full notice, or read the LICENSE file.

Because Raydium SDK v2 is GPL, the CLI's copyleft obligations propagate to any dependent code. Plan accordingly.

Links

• Architecture overview & monorepo layout: project root README
• Programmatic / library usage: @ray-inner/cli-core
• MCP + AI agent setup: @ray-inner/mcp / docs/mcp-integration.md