gaiad, the single binary that runs a Cosmos Hub node and acts as its command line client. It assumes gaiad v28.3.1 is installed (Installation). Task pages elsewhere (delegating, validating, governance) link here for the details of a command. This page lists what exists and the flags that matter, in the order a new operator meets them.
version: v28.3.1, commit: b7f8b81b..., cosmos_sdk_version: v0.53.4, go: go1.25.7, and the full dependency list. That output is how to confirm a binary before trusting anything else on this page. Every command has --help. The help text is generated from the same binary and is authoritative when it disagrees with a document.
Home directory and configuration
The binary keeps everything under--home, default ~/.gaia: config/ (config.toml, app.toml, client.toml, genesis.json, node_key.json, priv_validator_key.json), data/ (databases and priv_validator_state.json), and wasm/. Running gaiad init <moniker> --chain-id cosmoshub-4 creates the layout with default files.
Client defaults are stored in client.toml and are managed with gaiad config:
set subcommand writes the key, get reads one, view prints the file, diff shows what differs from defaults, and home prints the directory. The same command manages app.toml with dotted keys (gaiad config set app minimum-gas-prices 0.005uatom, gaiad config set app api.enable true, gaiad config set app app-db-backend pebbledb). It manages config.toml too, but only with the -s flag (--skip-validate), for example gaiad config set config p2p.seeds "<list>" -s. Without the flag, gaiad config set config ... returns cometbft config is not supported on v28.3.1.
Every client flag can also be an environment variable with the GAIAD_ prefix and underscores. For example, GAIAD_KEYRING_BACKEND=test gaiad keys list works, and GAIAD_NODE, GAIAD_CHAIN_ID, and GAIAD_OUTPUT work the same way. The GAIAD_HOME variable is not honoured by every subcommand on v28.3.1, so pass --home explicitly in scripts.
Keys
Thegaiad keys command manages wallet keys: secp256k1 keys derived from a BIP-39 phrase, used to sign transactions. These are the only keys this command touches. A validator’s consensus key (priv_validator_key.json, ed25519, signs blocks) and node key (node_key.json, the peer to peer (P2P) identity) are files, not keyring entries. They are read with the gaiad comet commands described below. A validator’s operator address is the cosmosvaloper form of one wallet key. It is fixed for the life of the validator.
Keyring backends: os (system keychain), file (encrypted file, password prompt), test (unencrypted, for devnets only), kwallet, pass, and memory. Set it once with gaiad config set client keyring-backend or per command with --keyring-backend. Details: Keyring.
add subcommand prints the address and a 24 word phrase once. The --recover flag prompts for a phrase. The --account and --index flags pick another path under m/44'/118'/<account>'/0/<index> (see HD wallets). The --hd-path flag sets it explicitly, and --coin-type defaults to 118. The --ledger flag stores a reference to a key on a connected device (Ledger). The --pubkey flag stores a public key only, which is how multisig members’ keys are collected on one machine. Then --multisig with --multisig-threshold builds the multisig entry (type multi). The --dry-run flag shows what would be created without saving.
-a flag prints only the address, and -p prints only the public key. The --bech val flag prints the cosmosvaloper form, and --bech cons prints the cosmosvalcons form of the same key. These are encodings of one address, not different keys. The -d flag shows the address on a Ledger screen. Passing several names with --multisig-threshold prints the multisig address those keys would form without saving it.
export subcommand writes an ASCII armored, passphrase encrypted private key. The import subcommand reads one, and import-hex reads a raw hex key. The parse subcommand converts an address between bech32 and hex and shows every prefix. The mnemonic subcommand generates a phrase from system entropy without creating a key. The migrate subcommand moves entries from a legacy keyring format. Deleting a key does not touch the chain. Funds stay at the address, and the phrase restores it.
Fees and gas
Every transaction pays gas times a gas price. The Hub’s fee market sets the price floor at 0.005 uatom per gas and raises it under load (Fee market):tx command:
--gas auto flag simulates the transaction against the node to estimate gas. The --gas-adjustment flag multiplies the estimate, and --gas-prices sets the price. Passing --fees 5000uatom sets a fixed fee instead and needs --gas as a number. A transaction that runs out of gas fails and still pays. Other flags on every tx command: --from (key name or address), --note (the transaction memo), --timeout-duration (--timeout-height still works but is deprecated), --broadcast-mode sync|async (sync waits for the mempool check, the default), --yes to skip the confirmation prompt, --dry-run to simulate only, --generate-only to write the unsigned transaction and send nothing.
Transactions by module
The commands below are the ones Hub operators and holders use. Eachgaiad tx <module> --help lists the rest.
- bank:
send <from> <to> <amount>,multi-send. - staking:
delegate <valoper> <amount>,redelegate <src> <dst> <amount>,unbond <valoper> <amount>,cancel-unbond <valoper> <amount> <creation-height>,create-validator <validator.json>,edit-validator. There is no key rotation command in this module on v28.3.1. - distribution:
withdraw-rewards <valoper>,withdraw-all-rewards,withdraw-validator-commission <valoper>,set-withdraw-addr <address>,fund-community-pool <amount>. - slashing:
unjail. - gov:
draft-proposal,submit-proposal <file>,deposit <id> <amount>,vote <id> <option>,weighted-vote <id> yes=0.6,no=0.4,cancel-proposal <id>,submit-legacy-proposal param-change. - upgrade:
software-upgrade <name> --upgrade-height ...,cancel-software-upgrade. - authz:
grant <grantee> send|generic|delegate|unbond|redelegate,revoke <grantee> <msg-type-url>,exec <file>. - feegrant:
grant <granter> <grantee>,revoke. - liquid:
tokenize-share,redeem-tokens,transfer-tokenize-share-record,disable-tokenize-shares,enable-tokenize-shares,withdraw-tokenize-share-rewards,withdraw-all-tokenize-share-rewards. - tokenfactory:
create-denom,mint,mint-to,burn,change-admin,modify-metadata(burn-fromandforce-transferexist in the CLI but are disabled on the Hub). - ibc-transfer:
transfer transfer <channel-id> <receiver> <amount>with--packet-timeout-timestamp(required on IBC v2 paths) and--memo. - wasm:
store,instantiate,execute,migrate.
Queries
Queries need--node (or the client.toml default) and no key. The --output json flag (or -o json) gives machine readable output, and --height <h> queries a past height on an archive node. Most list queries page with --page-limit, --page-key, --page-offset, --page-reverse, and --page-count-total. The gaiad q staking validators query has no --limit flag.
gaiad status query prints the node’s id, network, latest height, and catching_up. It is the only query that reads CometBFT rather than application state. The q txs --query form takes a CometBFT event query and only works against nodes with the transaction indexer on. The q auth account query returns the account inside .account.value in JSON for base and module accounts. The account_number and sequence from it are what offline signing needs.
Sign offline
Build, sign, and broadcast as three steps so that the signing machine never needs a network:--offline flag makes sign skip every node lookup, so --account-number and --sequence are required (gaiad q auth account provides them). The --signature-only flag outputs just the signature. The --sign-mode flag picks direct, amino-json, or textual (Ledger requires amino-json or textual). The validate-signatures subcommand prints [OK] per signer. The tx encode and tx decode subcommands convert between the JSON and the base64 wire form. The sign-batch and multisign-batch subcommands handle files with one transaction per line.
Multisig
A multisig account is a public key made of N member public keys and a threshold. Each signer produces a signature file against the same unsigned transaction. Anyone then combines them:--multisig flag on sign names the multisig entry, so the signature is made for the multisig address. The --from flag picks the member key. The multi-sign subcommand (alias multisign) assembles the threshold number of signatures. Order among members does not matter. However, every machine must have created the multisig from the same member keys in the same order (or all with --nosort), or the addresses differ. The Hub accepts at most 7 signatures per transaction (gaiad q auth params, tx_sig_limit), so 7 is the largest practical multisig.
Node commands
These run against the local home directory and the node’s own files, not against a remote node.comet command (alias tendermint) reads the node’s own keys. Its show-node-id prints the P2P id from node_key.json, show-validator prints the consensus public key from priv_validator_key.json, and show-address prints the cosmosvalcons address of that key. None of these keys can be changed in place on v28.3.1. There is no consensus key rotation on the Hub’s current gaia, the node key is regenerated (a new file means a new node id) rather than rotated, and the operator key can never change. The comet version subcommand reports the CometBFT version string compiled in. The unsafe-reset-all subcommand deletes data/ and resets priv_validator_state.json, which is why it is unsafe on a validator. The --keep-addr-book flag keeps addrbook.json. The bootstrap-state subcommand prepares the CometBFT state after an application level state sync. The snapshots command manages state sync snapshots (Snapshots). The prune command prunes a stopped node’s application store (Database and pruning). The rollback command reverts one block of application and CometBFT state after a failed upgrade (Upgrade a node). The export command writes the application state as a genesis file. The module-hash-by-height command prints per module state hashes for comparing nodes after an upgrade. The start flags that matter: --home, --unsafe-skip-upgrades <height>, --halt-height, and --p2p.seeds, --p2p.persistent_peers, --rpc.laddr as overrides for config.toml. The prune command panics on v28.3.1 before it touches the store, so leave pruning to the running node. See Prune offline.
Shell completion
gaiad completion command writes a bash completion script, and --zsh writes the zsh one. Open a new shell afterwards. Tab completion covers subcommands and flags, not key names or addresses.
Verify
version command prints v28.3.1. The status command prints cosmoshub-4 and a height within a few blocks of any explorer. If status fails with a connection error, the node in client.toml is wrong or unreachable.
Next
- Delegator CLI guide for the staking and governance commands in use.
- Validator setup for
create-validatorand the consensus key. - Keyring and HD wallets for key storage and derivation.