Reference

Wallet & CLI Reference

Complete reference for all rill-cli commands.

Installation

From cargo

cargo install rill-cli

From binary releases

# Linux x86_64
wget https://github.com/rillcoin/rill/releases/latest/download/rill-cli-linux-x86_64.tar.gz
tar xzf rill-cli-linux-x86_64.tar.gz
sudo mv rill-cli /usr/local/bin/

# macOS (Apple Silicon)
wget https://github.com/rillcoin/rill/releases/latest/download/rill-cli-macos-arm64.tar.gz
tar xzf rill-cli-macos-arm64.tar.gz
sudo mv rill-cli /usr/local/bin/

rill-cli --version

Global Flags

--format <table|json>Output format. table (default) is human-readable; json outputs machine-parseable JSON.

--help, -hPrint help for any command or subcommand.

--version, -VPrint rill-cli version.

Environment Variable

RILL_WALLET_PASSWORD

If set, used as the wallet decryption password for all commands. Intended for automation and CI environments. Store with care — wallet files contain encrypted private keys.

Commands

wallet create

Create a new HD wallet with a randomly generated seed

Generates a new HD wallet backed by a cryptographically random 24-word BIP-39 mnemonic. The wallet file is encrypted with a password you provide. The seed phrase is displayed exactly once at creation time — store it in a secure location. It cannot be recovered from the wallet file.

Options

-f, --file <PATH>Path to write the wallet file. Default: ~/.rill/wallet.dat

-n, --network <NET>mainnet or testnet. Controls address prefix (rill1 vs trill1). Default: testnet

Example

bash

rill-cli wallet create --network testnet --file ~/.rill/testnet.dat

Output

text

Creating new testnet wallet...
Enter password: ••••••••
Confirm password: ••••••••

✓ Wallet created: ~/.rill/testnet.dat

=== SEED PHRASE (store securely — NOT shown again) ===
abandon ability able about above absent absorb abstract
absurd abuse access accident account accuse achieve acid
acoustic acquire across act action actor actress actual

First address: trill1qw5r3k8d9vf2m7p4...

The seed phrase will NOT be shown again. Write it down and store it offline before proceeding.

wallet restore

Restore a wallet from an existing seed phrase or hex seed

Restores an HD wallet from a 24-word BIP-39 mnemonic or a hex-encoded seed. Use this to recover a wallet on a new machine or from a backup.

Options

-f, --file <PATH>Path to write the restored wallet file. Default: ~/.rill/wallet.dat

-s, --seed <SEED>24-word mnemonic or hex-encoded seed. If omitted, you will be prompted securely.

-n, --network <NET>mainnet or testnet. Default: testnet

Example

bash

# Restore from mnemonic (prompted)
rill-cli wallet restore --network mainnet --file ~/.rill/mainnet.dat

# Restore from mnemonic provided inline
rill-cli wallet restore --seed "abandon ability able ..."

Output

text

Enter seed phrase: ••••••••••••••••••••••••••••••••••••••••
Enter password: ••••••••
Confirm password: ••••••••

✓ Wallet restored: ~/.rill/mainnet.dat
  Network: mainnet
  First address: rill1qw5r3k8d9vf2m7p4...

address

Derive and display the next receive address

Derives the next unused receive address from the wallet's HD key tree. Addresses are deterministic — the same seed always produces the same sequence of addresses.

Options

-w, --wallet <PATH>Path to wallet file. Default: ~/.rill/wallet.dat

Example

bash

rill-cli address --wallet ~/.rill/testnet.dat

Output

text

trill1qw5r3k8d9vf2m7p4xzqna6fjcmlt8ys...

balance

Show wallet balance with decay breakdown

Queries the node for all UTXOs associated with wallet addresses and displays both the nominal balance (face value) and effective balance (after applying concentration decay). Also shows a per-cluster breakdown so you can see which clusters are subject to decay.

Options

-w, --wallet <PATH>Path to wallet file. Default: ~/.rill/wallet.dat

-r, --rpc-endpoint <URL>RPC endpoint URL. Default: http://127.0.0.1:18332

Example

bash

rill-cli balance \
  --wallet ~/.rill/testnet.dat \
  --rpc-endpoint http://127.0.0.1:28332

Output

text

=== WALLET BALANCE ===
Nominal:   100.00000000 RILL
Effective:  97.42000000 RILL
Decay:      -2.58000000 RILL (2.58%)

=== CLUSTER BREAKDOWN ===
Cluster  a3f8...12cd   nominal: 100.00000000   effective:  97.42000000   decay: -2.58%
  concentration: 0.42% of supply (above threshold)
  decay rate:    ~1.8% per year

Effective balance is what you can actually spend. The difference (decay) has accrued to the decay pool and will be distributed to miners.

send

Send RILL to an address

Constructs, signs, and broadcasts a transaction sending RILL to a recipient address. Uses decay-aware coin selection: the wallet prefers to spend UTXOs with the highest decay first, minimizing future decay losses.

Options

-w, --wallet <PATH>Path to wallet file. Default: ~/.rill/wallet.dat

-t, --to <ADDRESS>Recipient rill1... or trill1... address.

-a, --amount <RILL>Amount to send in RILL (e.g., 10.5). Internally converted to rills.

-f, --fee <RILLS>Transaction fee in rills. Default: 1000 (0.00001 RILL).

-r, --rpc-endpoint <URL>RPC endpoint URL. Default: http://127.0.0.1:18332

Example

bash

rill-cli send \
  --to    trill1qrecipientaddress... \
  --amount 10.5 \
  --fee   1000 \
  --rpc-endpoint http://127.0.0.1:28332

Output

text

Coin selection: 3 UTXOs (spending highest-decay first)
Transaction size: 412 bytes
Fee: 0.00001000 RILL (1000 rills)

Broadcasting...
✓ Transaction sent: 7f3a9c2b1d4e5f6a...

Track: http://explorer.rillcoin.com/tx/7f3a9c2b1d4e5f6a...

getpeerinfo

Show connected peer count

Queries the node for the current number of connected P2P peers. Useful for verifying your node is connected to the network.

Options

--rpc-endpoint <URL>RPC endpoint URL. Default: http://127.0.0.1:18332

Example

bash

rill-cli getpeerinfo --rpc-endpoint http://127.0.0.1:28332

Output

text

Connected peers: 8

getblockchaininfo

Show blockchain state summary

Returns a comprehensive summary of the current blockchain state including block height, best block hash, circulating supply, decay pool balance, initial block download status, UTXO count, mempool size, and peer count.

Options

--rpc-endpoint <URL>RPC endpoint URL. Default: http://127.0.0.1:18332

Example

bash

rill-cli getblockchaininfo --rpc-endpoint http://127.0.0.1:28332

Output

text

=== BLOCKCHAIN INFO ===
Height:             42,381
Best Block:         a3f8c9d2...64b2
Circulating Supply: 8,432,750.00000000 RILL
Decay Pool:         12,847.32000000 RILL
IBD:                false (fully synced)
UTXO Count:         1,284,920
Mempool Size:       43 transactions
Peers:              8

getsyncstatus

Show node sync progress

Shows whether the node is currently syncing or fully synced, along with current height, peer count, and best known hash.

Options

--rpc-endpoint <URL>RPC endpoint URL. Default: http://127.0.0.1:18332

Example

bash

rill-cli getsyncstatus --rpc-endpoint http://127.0.0.1:28332

Output

text

Status:  synced
Height:  42,381
Peers:   8
Best:    a3f8c9d2...64b2

validateaddress

Validate a rill1... or trill1... address

Validates the checksum and format of a RillCoin address. No RPC connection required — validation is performed client-side using the Bech32m decoding algorithm.

Example

bash

rill-cli validateaddress trill1qw5r3k8d9vf2m7p4xzqna6fjcmlt8ys...

Output

text

✓ Valid testnet address
  HRP:     trill1
  Network: testnet
  Payload: 5r3k8d9vf2m7p4xzqna6fjcmlt8ys...

Invalid addresses print an error message and exit with code 1. Use this in scripts to validate user input before broadcasting transactions.

Mining RPC Reference