lumerad CLI reference

lumerad is the Lumera blockchain node binary and the primary command-line tool for interacting with the Lumera Protocol. You use it to run a full node, query any on-chain state, submit transactions, manage cryptographic keys, and work with Lumera-specific modules such as actions (Cascade/Sense), claims, and the SuperNode registry. It is built on the Cosmos SDK and follows the same command conventions as other Cosmos chains. Existing Cosmos familiarity transfers directly. The current release is v1.20.1-hotfix (July 14, 2026). Version v1.20.0 was the Aurora Convergence EVM upgrade.

Installation

Build from source

Clone the repository

git clone https://github.com/LumeraProtocol/lumera
cd lumera

Build the binary

make build

The compiled binary is placed at build/lumerad. You can also run make build-debug to include debug symbols.

Install system-wide

sudo mv build/lumerad /usr/local/bin/

Verify the installation

lumerad version

Prerequisites. You need Go 1.26+ (see go.mod for the exact version) and make. The libwasmvm shared library is built automatically during make build. You can also source it from the CosmWasm releases page.

Key management

Before you can sign transactions, you need at least one key in your local keyring.

lumerad keys add <name>          # Generate a new key and display its mnemonic
lumerad keys list                # List all keys in the keyring
lumerad keys show <name>         # Show a key's details, address, and public key
lumerad keys import <name>       # Import a key from a mnemonic phrase
lumerad keys delete <name>       # Permanently delete a key from the keyring

When you run lumerad keys add, the mnemonic is displayed once and never stored. Write it down and keep it in a safe place. It is the only way to recover your key if you lose access to the keyring files.

Query commands

Query commands read on-chain state without submitting any transactions. They are safe to run at any time and do not require a signing key.

Staking
Actions
Claims
Node status

# List all active validators
lumerad query staking validators

# Show delegations for a specific address
lumerad query staking delegations <address>

# Show token balances for a specific address
lumerad query bank balances <address>

# List all Cascade/Sense actions
lumerad query action list-actions

# Fetch a specific action by ID
lumerad query action get-action <action-id>

# Check the claim status for an address
lumerad query claim get-claim <address>

# Query the connected node's sync status and block height
lumerad status

Transaction commands

Transaction commands broadcast signed messages to the chain. Every transaction command requires --from (the signing key) and --chain-id. Fees are charged in ulume (1 LUME = 1,000,000 ulume).

Staking
Governance
Claims

# Delegate tokens to a validator
lumerad tx staking delegate <validator-address> <amount>ulume \
  --from <key-name> \
  --chain-id lumera-mainnet-1

# Unbond tokens from a validator (subject to unbonding period)
lumerad tx staking unbond <validator-address> <amount>ulume \
  --from <key-name> \
  --chain-id lumera-mainnet-1

# Vote on an active governance proposal
lumerad tx gov vote <proposal-id> yes \
  --from <key-name> \
  --chain-id lumera-mainnet-1

# Valid vote options: yes | no | abstain | no_with_veto

# Claim your allocated LUME tokens (if eligible)
lumerad tx claim claim-tokens \
  --from <key-name> \
  --chain-id lumera-mainnet-1

Global flags

These flags apply to every lumerad command. You can set frequently-used flags as environment variables (e.g., LUMERA_CHAIN_ID) or in ~/.lumera/config/client.toml.

Flag	Description
`--chain-id`	Chain identifier, `lumera-mainnet-1` for mainnet or `lumera-testnet-2` for testnet
`--from`	Key name or bech32 address used to sign the transaction
`--fees`	Transaction fee in `ulume` (e.g., `5000ulume`)
`--gas`	Gas limit as an integer, or `"auto"` to estimate automatically
`--gas-adjustment`	Multiplier applied to the estimated gas when using `--gas auto` (default `1.3`)
`--node`	Tendermint RPC endpoint (default: `tcp://localhost:26657`)
`--output`	Output format: `text` (default) or `json`
`--broadcast-mode`	How to wait for the result: `sync`, `async`, or `block`
`--keyring-backend`	Keyring backend: `os`, `file`, or `test`

Add --output json to any query command and pipe the result to jq for easy scripting.

lumerad query bank balances lumera1abc... --output json | jq '.balances'

For transactions, combine --broadcast-mode block with --output json to get the full transaction result in a single call. The result includes events and the transaction hash.

Common workflows

Check your balance and delegate

# 1. Find your address
lumerad keys show mykey --bech acc

# 2. Check your balance
lumerad query bank balances $(lumerad keys show mykey -a)

# 3. Pick a validator
lumerad query staking validators --output json | jq '.validators[] | {moniker: .description.moniker, address: .operator_address}'

# 4. Delegate
lumerad tx staking delegate lumeravaloper1xyz... 1000000ulume \
  --from mykey \
  --chain-id lumera-mainnet-1 \
  --fees 5000ulume \
  --gas auto \
  --gas-adjustment 1.4

Query an action and verify it is finalized

lumerad query action get-action <action-id> --output json | jq '{state: .action.state, tx_hash: .action.finalize_tx_hash}'

A finalized Cascade action has state: "ACTION_STATE_DONE" and a populated finalize_tx_hash.

Connect to a remote node

lumerad status --node tcp://rpc.mainnet.lumera.io:26657
lumerad query bank balances lumera1abc... --node tcp://rpc.mainnet.lumera.io:26657

Set --node once in your client config to avoid repeating it.

lumerad config node tcp://rpc.mainnet.lumera.io:26657

Additional build targets

The Makefile exposes several targets useful during development.

make build-debug          # Build with debug symbols
make build-proto          # Regenerate protobuf files from .proto sources
make lint                 # Run golangci-lint
make unit-tests           # Run unit test suite
make integration-tests    # Run integration tests

Cosmos SDK docs

The upstream documentation for the SDK that powers lumerad.

CometBFT docs

Consensus engine and RPC reference.

IBC Protocol

Cross-chain messaging used by Lumera.

Lumera Networks

Genesis files, seeds, and peer lists for mainnet and testnet.

REST API

RPC

gRPC API

Libraries and tools

Installation

Build from source

Key management

Query commands

Transaction commands

Global flags

Common workflows

Additional build targets

Further reading

Cosmos SDK docs

CometBFT docs

IBC Protocol

Lumera Networks

​Installation

​Build from source

​Key management

​Query commands

​Transaction commands

​Global flags

​Common workflows

​Additional build targets

​Further reading

Cosmos SDK docs

CometBFT docs

IBC Protocol

Lumera Networks

Installation

Build from source

Key management

Query commands

Transaction commands

Global flags

Common workflows

Additional build targets

Further reading