xrpl-cli

A Swiss Army knife for interacting with the XRP Ledger from the command line. Built for both humans and AI agents.

xrpl-cli wraps xrpl.js and exposes the full breadth of XRPL functionality through a flat, composable command interface — inspired by Foundry's cast for EVM chains.

Important

This project was vibe-coded and has not been audited. It is under active development — expect breaking changes. Use at your own risk, especially when signing transactions or handling seeds/keys. Always verify transactions before submitting to mainnet.

Contents

• Install
• Quick Start
• Commands
• Exit Codes
• Development
• Docs
• Contributing
• AI Agents
• Roadmap
• License

Install

npm install -g @commonprefix/xrpl-cli

Or run directly without installing:

npx @commonprefix/xrpl-cli --help

Requires Node.js v20+.

Quick Start

# Check an account's XRP balance
xrpl balance ra5nK24KXen9AHvsdFTKHSANinZseWnPcX

# Get current ledger index
xrpl ledger-index

# Look up a transaction
xrpl tx DF9BC86D9C36852A6BCAE5A616B137B97FCBD3892DCFEFBD170AA600FD14DDCD

# Send 10 XRP (interactive seed prompt)
xrpl send --to ra5nK24KXen9AHvsdFTKHSANinZseWnPcX --amount 10 --token XRP -i

# Generate a new wallet
xrpl wallet generate

# Generate a vanity address
xrpl wallet vanity --starts-with XRP

# Watch ledger events in real time
xrpl subscribe --streams ledger

Commands

Global options: --network (-n), --rpc-url, --json, --quiet (-q), --yes (-y)

Wallet options (for signing): --seed (-s), --from (-f), --keyfile, --mnemonic, --interactive (-i)

Full command reference with all options and flags: docs/cli-reference.md

Account Query

Command	Description
balance	Get XRP or token balance for an account
account-info	Get full account info (sequence, flags, balance, etc.)
account-objects	Get objects owned by an account (offers, trust lines, escrows, etc.)
account-lines	Get trust lines for an account
account-channels	Get payment channels for an account
account-currencies	Get currencies an account can send or receive
account-nfts	Get NFTs owned by an account
account-offers	Get open DEX offers for an account
account-tx	Get transaction history for an account
gateway-balances	Get total issued token balances
noripple-check	Check account rippling settings
sequence-number	Get the current sequence number

Ledger

Command	Description
ledger	Get ledger info
ledger-index	Get latest validated ledger index
ledger-data	Get raw ledger contents
ledger-entry	Get a single ledger entry by index
fee	Get current transaction fee
server-info	Get server status
server-state	Get machine-readable server status
feature	List protocol amendments and their status

Transactions

Command	Description
tx	Look up a transaction by hash
send	Send a payment (XRP, IOU, or MPT)
submit	Submit a raw signed transaction blob
sign	Sign a transaction without submitting
build	Build any transaction type (escape hatch)

Trust Lines & Tokens

Command	Description
trust-set	Create or modify a trust line
mpt-create	Create a Multi-Purpose Token issuance
mpt-authorize	Authorize an account for an MPT
mpt-set	Lock/unlock an MPT issuance or holder
mpt-destroy	Destroy an MPT issuance
clawback	Claw back tokens from a holder

Account Configuration

Command	Description
account-set	Modify account properties
account-delete	Delete an account
set-regular-key	Set or remove a regular key
deposit-preauth	Preauthorize an account for deposits
signer-list-set	Set up multi-signing
signer-list-delete	Remove the signer list
delegate-set	Grant transaction delegation

Tickets

Command	Description
ticket-create	Create tickets for later use
tickets	List available tickets for an account

DEX

Command	Description
offer-create	Create a DEX offer
offer-cancel	Cancel a DEX offer
book-offers	Get the order book for a currency pair
deposit-authorized	Check deposit authorization between accounts
path-find	Find a payment path between accounts

AMM

Command	Description
amm-info	Get info about an AMM instance
amm-create	Create an AMM for a token pair
amm-deposit	Deposit funds into an AMM
amm-withdraw	Withdraw funds from an AMM
amm-vote	Vote on AMM trading fee
amm-bid	Bid on AMM auction slot

Checks

Command	Description
check-create	Create a check
check-cash	Redeem a check
check-cancel	Cancel a check

Escrow

Command	Description
escrow-create	Create a time/condition-based escrow
escrow-finish	Complete an escrow
escrow-cancel	Cancel an expired escrow

Payment Channels

Command	Description
channel-create	Create a payment channel
channel-fund	Fund a payment channel
channel-claim	Claim from a payment channel
channel-verify	Verify a channel claim signature

NFTs

Command	Description
nft-mint	Mint an NFT
nft-burn	Burn an NFT
nft-offer-create	Create an offer to buy or sell an NFT
nft-offer-accept	Accept an NFT offer
nft-offer-cancel	Cancel an NFT offer
nft-buy-offers	Get buy offers for an NFT
nft-sell-offers	Get sell offers for an NFT

Multi-Signing

Command	Description
multisign	Sign a transaction for multi-signing
multisign-combine	Combine multi-signed transactions
multisign-submit	Combine and submit multi-signed transactions

Wallet

Command	Description
wallet generate	Generate a new random keypair
wallet from-seed	Derive wallet from an existing seed
wallet from-entropy	Derive wallet from raw entropy
wallet vanity	Generate a vanity address
wallet fund	Fund a wallet via testnet/devnet faucet
wallet sign-message	Sign an arbitrary message
wallet verify-message	Verify a signed message
wallet import	Import a wallet into encrypted keystore
wallet list	List keystore wallets
wallet remove	Remove a wallet from keystore

Conversion

Command	Description
xrp-to-drops	Convert XRP to drops
drops-to-xrp	Convert drops to XRP
ripple-time	Convert between XRPL epoch and ISO 8601

Utility

Command	Description
address-info	Validate and decode an XRPL address
to-hex	Convert UTF-8 string to hex
from-hex	Convert hex to UTF-8 string
hash	Hash data with XRPL-relevant algorithms
decode-tx	Decode a transaction blob to JSON
encode-tx	Encode transaction JSON to binary
rpc	Send a raw API request (escape hatch)
subscribe	Subscribe to ledger events
ping	Confirm server connectivity
completions	Generate shell completion scripts

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments / usage error
3	Network / connection error
4	Transaction rejected
5	Transaction expired

Development

pnpm install             # Install dependencies
pnpm build               # Build with tsup
pnpm dev -- <args>       # Run from source via tsx
pnpm test                # Run unit tests
pnpm test:e2e            # Run E2E tests against testnet
pnpm lint                # Check with Biome
pnpm format              # Format with Biome

Shell Completions

xrpl completions bash > ~/.local/share/bash-completion/completions/xrpl
xrpl completions zsh > ~/.zfunc/_xrpl
xrpl completions fish > ~/.config/fish/completions/xrpl.fish

Docs

Document	Description
CLI Reference	Full command reference with all options and flags
Examples	Real-world usage examples for every workflow
Configuration	Environment variables, config file, shell completions, amendments

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines, project structure, and code style.

AI Agents

xrpl-cli is designed for AI agent use — structured JSON output (--json), non-interactive mode (--yes --quiet), and meaningful exit codes.

Install the agent skill:

npx skills add commonprefix/xrpl-cli

File	Description
SKILL.md	Agent skill — how to use xrpl-cli as a tool
AGENTS.md	Coding agent guide — how to work on the codebase

Releasing

Releases are tag-triggered. Pushing a semver tag runs all CI checks, publishes to npm with provenance, and creates a GitHub release with auto-generated notes.

# 1. Bump version
pnpm version patch   # or minor / major

# 2. Push commit and tag
git push --follow-tags

Roadmap

Features worth exploring later:

• watch mode — poll a command at an interval and stream changes
• Ledger hardware wallet signing — sign transactions using a connected Ledger device
• --private-key option — accept a raw hex private key directly for signing
• Niche developer utilities — RFC1751 mnemonic encode/decode, seed encoding/decoding, raw keypair derivation, etc.

License

MIT

Disclaimer

Caution

This is an independent, community-built tool. It is not officially supported, endorsed, or maintained by Ripple, the XRP Ledger Foundation (XRPLF), or any affiliated organization. Use at your own risk.