@ray-inner/cli-core

Core library for the Raydium CLI. Provides the Zod SSOT (single source of truth) for command schemas, the service layer that wraps @raydium-io/raydium-sdk-v2, an error catalog, and the four-path agent tool registry (MCP / OpenAI / Anthropic / JSON Schema).

Consumed transitively by @ray-inner/cli (the human-facing terminal CLI) and @ray-inner/mcp (the MCP stdio server). You can also import it directly for programmatic Raydium access with end-to-end type safety.

Installation

Most users do not install this package directly — it ships as a dependency of @ray-inner/cli and @ray-inner/mcp. For third-party Node.js integrations (Persona Carol in the PRD), install explicitly:

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

Requirements: Node.js ≥ 20 LTS, TypeScript ≥ 5.0 (if using types).

Dual ESM + CJS Entry Points

Both module systems are supported via conditional exports in package.json.

ESM:

import { z, PoolListInput, RaydiumCliError, CODES } from '@ray-inner/cli-core';
import { listPools } from '@ray-inner/cli-core/services/pool';
import { Config } from '@ray-inner/cli-core/config';

CommonJS:

const { PoolListInput, RaydiumCliError, CODES } = require('@ray-inner/cli-core');
const { listPools } = require('@ray-inner/cli-core/services/pool');
const { Config } = require('@ray-inner/cli-core/config');

Public Surface

Granular subpath exports keep bundle size tight. Import only what you need.

| Subpath | What you get | | ------------------------------------- | ----------------------------------------------------------------------------------------- | | @ray-inner/cli-core | Root barrel: schemas, errors, signer, rpc, config, getSdkVersion | | @ray-inner/cli-core/schemas | All Zod input/output schemas (pool, swap, cpmm, clmm, launchpad, wallet, tx, config, farm, amm, portfolio, sol, token, market) | | @ray-inner/cli-core/schemas/<domain>| Per-domain schemas, e.g. schemas/swap, schemas/clmm | | @ray-inner/cli-core/errors | RaydiumCliError, error CODES, CATALOG, mapSdkError, deriveExitCode | | @ray-inner/cli-core/signer | Signer factories: inline / external / file / pubkey / agent | | @ray-inner/cli-core/rpc | RPC endpoint pool + p-retry failover | | @ray-inner/cli-core/config | Config persistence (AES-256-GCM keystore) + KeychainConfig | | @ray-inner/cli-core/services/pool | listPools, getPoolInfo, searchPools | | @ray-inner/cli-core/services/swap | tradeV2 aggregator, quote cache, slippage policy | | @ray-inner/cli-core/services/cpmm | CPMM quote/swap/add/remove/create/collect-fee | | @ray-inner/cli-core/services/clmm | CLMM positions/info/open/increase/decrease/close/harvest/swap/lock/create/init-reward/collect-reward/set-reward | | @ray-inner/cli-core/services/launchpad | Bonding-curve info/create/buy/sell/claim-vesting/collect-creator-fee | | @ray-inner/cli-core/services/wallet | create / import / balance / address / transfer / unlock / lock / status / list / use | | @ray-inner/cli-core/services/tx | decode, simulate, send, getStatus, refreshBlockhash | | @ray-inner/cli-core/services/config | getConfigValue, setConfigValue, lockConfig, unlockConfig, describeConfigKeys | | @ray-inner/cli-core/services/schema | Dump the agent tool registry (mcp / openai / anthropic / jsonschema) | | @ray-inner/cli-core/services/farm | Farm info/list/deposit/withdraw/harvest/create/restart-reward/add-reward/withdraw-reward | | @ray-inner/cli-core/services/amm | AMM v4 info/add/remove/swap/create/migrate/create-with-market | | @ray-inner/cli-core/services/portfolio | scanPortfolio, harvestAll | | @ray-inner/cli-core/services/sol | wrapSol, unwrapSol | | @ray-inner/cli-core/services/token | resolveToken, searchTokens, getTokenInfo | | @ray-inner/cli-core/services/market | createMarket | | @ray-inner/cli-core/services/meta | getCapabilities — live tool count + domain capability map | | @ray-inner/cli-core/agent/* | Four-path tool adapters: mcp-tools, openai-tools, anthropic-tools |

Quickstart

import { PoolInfoInput } from '@ray-inner/cli-core/schemas';
import { getPoolInfo } from '@ray-inner/cli-core/services/pool';
import { RaydiumCliError, CODES } from '@ray-inner/cli-core/errors';

// 1. Validate caller input at the boundary (recommended Zod pattern).
const input = PoolInfoInput.parse({ poolId: 'Hp4kNR5...' });

// 2. Inject your own `RaydiumClient` adapter (or reuse the SDK loader
//    from services/pool/ports). Dependency injection keeps the domain
//    layer free from I/O — required for testability.
const client = /* RaydiumClient adapter */;

try {
  const info = await getPoolInfo(client, input);
  console.log(info.spotPrice, info.tvlUsd);
} catch (err) {
  if (err instanceof RaydiumCliError && err.code === CODES.POOL_NOT_FOUND) {
    // structured error — use `err.category` / `err.retryable` / `err.suggestion`
  }
  throw err;
}

Design Notes

• Immutable everywhere: every schema and every service output is frozen. Mutations must go through new-object construction.
• Fail loud: required inputs never silently default. readEnvConfig throws on missing RPC endpoints; Config.unlock throws on password mismatch.
• Amounts as lamports: all on-chain amounts cross boundaries as z.string().regex(/^\d+$/). UI formatting is the caller's job.
• SDK pinned: @raydium-io/raydium-sdk-v2 >= 0.2.35-alpha (see sdk-version.ts). Each release notes the SDK commit SHA.

License

Distributed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

Because Raydium SDK v2 itself is GPL-3.0, anything consuming @ray-inner/cli-core inherits GPL's copyleft obligations. If that's incompatible with your project, the PRD reserves an HTTP-proxy path (R5 Path B) as a future escape hatch — not available in v0.1.x.

Links

• Repository & architecture overview: see the project root README
• CLI usage: @ray-inner/cli
• MCP server: @ray-inner/mcp