Skip to content
LogoLogo

Helpful CLI commands

View all options:

celestia-appd --help

Updating node configuration

See the celestia-app v9 release notes for details.

Creating a wallet

celestia-appd config keyring-backend <backend>

keyring-backend configures the keyring's backend, where the keys are stored.

Options are: os|file|kwallet|pass|test|memory.

test keeps the key unencrypted on disk with no password, so reserve it for local development and testnets. See create a wallet with celestia-app for a comparison of the backends.

You can learn more on the Cosmos documentation or Go Package documentation.

Key management

If you do not set a keyring backend, celestia-appd uses the test backend, which stores keys unencrypted on disk. Pass --keyring-backend <backend> to the key commands, or configure a backend as shown above, before you create keys that hold real funds.

# listing keys
celestia-appd keys list --keyring-backend <backend>
 
# adding keys
celestia-appd keys add <KEY_NAME> --keyring-backend <backend>
 
# deleting keys
celestia-appd keys delete <KEY_NAME> --keyring-backend <backend>
 
# renaming keys
celestia-appd keys rename <CURRENT_KEY_NAME> <NEW_KEY_NAME>

Importing and exporting keys

Import an encrypted and ASCII-armored private key into the local keybase.

celestia-appd keys import <KEY_NAME> <KEY_FILE>

Example usage:

celestia-appd keys import amanda ./keyfile.txt

Export a private key from the local keyring in encrypted and ASCII-armored format:

celestia-appd keys export <KEY_NAME>
 
# you will then be prompted to set a password for the encrypted private key:
Enter passphrase to encrypt the exported key:

After you set a password, your encrypted key will be displayed.

Querying subcommands

Usage:

celestia-appd query <FLAGS> | <COMMAND>
 
# alias q
celestia-appd q <FLAGS> | <COMMAND>

To see all options:

celestia-appd q --help

Token management

Get token balances:

celestia-appd q bank balances <ADDRESS> --node <NODE_URI>

Example usage:

celestia-appd q bank balances celestia1czpgn3hdh9sodm06d5qk23xzgpq2uyc8ggdqgw \
    --node https://public-endpoint.celestia-mocha.quiknode.pro

Transfer tokens from one wallet to another:

celestia-appd tx bank send <FROM_ADDRESS> <TO_ADDRESS> \
    <amount> --node <NODE_URI> --chain-id <CHAIN_ID>

Example usage:

celestia-appd tx bank send <FROM_ADDRESS> <TO_ADDRESS> \
    19000000utia --node https://public-endpoint.celestia-mocha.quiknode.pro \
    --chain-id mocha-5

To see options:

celestia-appd tx bank send --help

Governance

Governance proposals on Celestia are limited as there are no text proposals, upgrades are coordinated through validator signalling, and some params are not modifiable. However, one can submit governance proposals to change certain parameters and spend community funds. More detailed information on this topic can be found in the cosmos-sdk documentation for submitting proposals, and the list of parameters in the specs, which shows the parameters that governance can change.

Viewing the available proposals can be done with the query command:

celestia-appd q gov proposals

There are four options when voting "yes", "no", "no_with_veto" and "abstain". The "no_with_veto" vote is different from the "no" vote in that the submitter of the proposer's deposit will get burned, and a minority of stake (1/3) can stop a proposal that might otherwise pass quorum. You can use those options to vote on a governance proposal with the following command:

celestia-appd tx gov vote <proposal id> <option> \
    --from <wallet> --chain-id <chain-id>

To submit a proposal, save the proposal and its sdk.Msg messages in a JSON file. Parameter changes use the MsgUpdateParams message of the module that owns the parameter. The message replaces all of the module's parameters, so query the current values first and change only the ones you need:

celestia-appd q staking params

For example, to change the max validators to 105, save this JSON file. Use the current on-chain values for the other fields. Governance cannot change bond_denom or unbonding_time.

{
  "messages": [
    {
      "@type": "/cosmos.staking.v1beta1.MsgUpdateParams",
      "authority": "celestia10d07y265gmmuvt4z0w9aw880jnsr700jtgz4v7",
      "params": {
        "unbonding_time": "1213200s",
        "max_validators": 105,
        "max_entries": 7,
        "historical_entries": 10000,
        "bond_denom": "utia",
        "min_commission_rate": "0.200000000000000000"
      }
    }
  ],
  "metadata": "",
  "deposit": "10000000000utia",
  "title": "Staking param change",
  "summary": "Update max validators to 105"
}

Note that the authority here must be the gov module account. That account can be found by using this command:

celestia-appd q auth module-account gov

Then one can submit the proposal with:

celestia-appd tx gov submit-proposal <path to json file> \
    --from <wallet> --chain-id <chain-id>

Community Pool

A percentage of the block rewards are allocated to the community pool. Community members can submit governance proposals to spend the community pool funds, and token holders can vote on these proposals. The proposals to spend are arbitrary in nature in that they can only contain text and some address to send funds to. To view the community pool balance, use the following command:

celestia-appd q distribution community-pool

To submit a proposal to spend the community pool funds, first create a JSON file that contains the proposal.

{
  "messages": [
    {
      "@type": "/cosmos.distribution.v1beta1.MsgCommunityPoolSpend",
      "authority": "celestia10d07y265gmmuvt4z0w9aw880jnsr700jtgz4v7",
      "recipient": "celestia17adsjkuecgjheugrdrwdqv9uh3qkrfmj9xzawx",
      "amount": [{ "denom": "utia", "amount": "100000000000" }]
    }
  ],
  "metadata": "",
  "deposit": "10000000000utia",
  "title": "Community pool spend",
  "summary": "Fund an open source project."
}

The JSON file can be submitted using the same proposal submission command as above:

celestia-appd tx gov submit-proposal <path to json file> \
    --from <wallet> --chain-id <chain-id>

Claim validator rewards

You can claim your validator rewards with the following command:

celestia-appd tx distribution withdraw-rewards <validator valoper> \
    --commission --from=<validator wallet> --chain-id <chain-id> \
    --gas auto -y

Delegate & undelegate tokens

You can delegate your tokens to a validator with the following command:

celestia-appd tx staking delegate <validator valoper> <amount>\
    --from <wallet> --chain-id <chain-id>

You can undelegate tokens to a validator with the unbond command:

celestia-appd tx staking unbond <validator valoper> <amount>\
    --from <wallet> --chain-id <chain-id>

Unjailing the validator

You can unjail your validator with the following command:

celestia-appd tx slashing unjail --from <validator wallet>\
    --chain-id <chain-id> --gas auto -y

How to export logs with SystemD

You can export your logs if you are running a SystemD service with the following command:

sudo journalctl -u <your systemd service> -S yesterday > node_logs.txt
sudo journalctl -u <your systemd service> -S today > node_logs.txt
# This command outputs the last 1 million lines!
sudo journalctl -u <your systemd service> -n 1000000 > node_logs.txt

Signing genesis for a new network

You can first run the following commands:

VALIDATOR_NAME=validator1
CHAIN_ID=testnet
celestia-appd init $VALIDATOR_NAME --chain-id $CHAIN_ID
MONIKER=validator_name

Next create a wallet:

KEY_NAME=validator
celestia-appd keys add $KEY_NAME

Then add genesis account:

CELES_AMOUNT="5000100000000utia"
celestia-appd genesis add-genesis-account $KEY_NAME $CELES_AMOUNT

Then generate your gentx:

STAKING_AMOUNT=5000000000000utia
celestia-appd genesis gentx $KEY_NAME $STAKING_AMOUNT --chain-id $CHAIN_ID \
    --pubkey=$(celestia-appd tendermint show-validator) \
    --moniker=$MONIKER \
    --commission-rate=0.2 \
    --commission-max-rate=0.6 \
    --commission-max-change-rate=0.01 \
    --min-self-delegation=1

You can then share your gentx JSON file on the networks repo in the respective network directory you are participating in.