There is no set way to create a CLI, but Cosmos SDK modules typically use the Cobra Library. Building a CLI with Cobra entails defining commands, arguments, and flags. Commands understand the actions users wish to take, such as
tx for creating a transaction and
query for querying the application. Each command can also have nested subcommands, necessary for naming the specific transaction type. Users also supply Arguments, such as account numbers to send coins to, and Flags to modify various aspects of the commands, such as gas prices or which node to broadcast to.
Here is an example of a command a user might enter to interact with the simapp CLI
simd in order to send some tokens:
simd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --gas auto --gas-prices <gasPrices>
The first four strings specify the command:
- The root command for the entire application
- The subcommand
tx, which contains all commands that let users create transactions.
- The subcommand
bankto indicate which module to route the command to (
x/bankmodule in this case).
- The type of transaction
The next two strings are arguments: the
from_address the user wishes to send from, the
to_address of the recipient, and the
amount they want to send. Finally, the last few strings of the command are optional flags to indicate how much the user is willing to pay in fees (calculated using the amount of gas used to execute the transaction and the gas prices provided by the user).
The CLI interacts with a node to handle this command. The interface itself is defined in a
Building the CLI
main.go file needs to have a
main() function that creates a root command, to which all the application commands will be added as subcommands. The root command additionally handles:
- setting configurations by reading in configuration files (e.g. the Cosmos SDK config file).
- adding any flags to it, such as
- instantiating the
codecby calling the application's
codecis used to encode and decode data structures for the application - stores can only persist
bytes so the developer must define a serialization format for their data structures or use the default, Protobuf.
- adding subcommand for all the possible user interactions, including transaction commands and query commands.
main() function finally creates an executor and execute the root command. See an example of
main() function from the
The rest of the document will detail what needs to be implemented for each step and include smaller portions of code from the
simapp CLI files.
Adding Commands to the CLI
Every application CLI first constructs a root command, then adds functionality by aggregating subcommands (often with further nested subcommands) using
rootCmd.AddCommand(). The bulk of an application's unique capabilities lies in its transaction and query commands, called
The root command (called
rootCmd) is what the user first types into the command line to indicate which application they wish to interact with. The string used to invoke the command (the "Use" field) is typically the name of the application suffixed with
gaiad. The root command typically includes the following commands to support basic functionality in the application.
- Status command from the Cosmos SDK rpc client tools, which prints information about the status of the connected
Node. The Status of a node includes
- Keys commands from the Cosmos SDK client tools, which includes a collection of subcommands for using the key functions in the Cosmos SDK crypto tools, including adding a new key and saving it to the keyring, listing all public keys stored in the keyring, and deleting a key. For example, users can type
simd keys add <name>to add a new key and save an encrypted copy to the keyring, using the flag
--recoverto recover a private key from a seed phrase or the flag
--multisigto group multiple keys together to create a multisig key. For full details on the
addkey command, see the code here. For more details about usage of
--keyring-backendfor storage of key credentials look at the keyring docs.
- Server commands from the Cosmos SDK server package. These commands are responsible for providing the mechanisms necessary to start an ABCI Tendermint application and provides the CLI framework (based on cobra) necessary to fully bootstrap an application. The package exposes two core functions:
ExportCmdwhich creates commands to start the application and export state respectively. Click here to learn more.
- Transaction commands.
- Query commands.
Next is an example
rootCmd function from the
simapp application. It instantiates the root command, adds a persistent flag and
PreRun function to be run before every execution, and adds all of the necessary subcommands.
rootCmd has a function called
initAppConfig() which is useful for setting the application's custom configs.
By default app uses Tendermint app config template from Cosmos SDK, which can be over-written via
Here's an example code to override default
initAppConfig() also allows overriding the default Cosmos SDK's server config. One example is the
min-gas-prices config, which defines the minimum gas prices a validator is willing to accept for processing a transaction. By default, the Cosmos SDK sets this parameter to
"" (empty string), which forces all validators to tweak their own
app.toml and set a non-empty value, or else the node will halt on startup. This might not be the best UX for validators, so the chain developer can set a default
app.toml value for validators inside this
keys subcommands are common across most applications and do not interact with application state. The bulk of an application's functionality - what users can actually do with it - is enabled by its
txCommand function adds all the transaction available to end-users for the application. This typically includes:
- Sign command from the
authmodule that signs messages in a transaction. To enable multisig, add the
MultiSigncommand. Since every transaction requires some sort of signature in order to be valid, the signing command is necessary for every application.
- Broadcast command from the Cosmos SDK client tools, to broadcast transactions.
- All module transaction commands the application is dependent on, retrieved by using the basic module manager's
Here is an example of a
txCommand aggregating these subcommands from the
Queries are objects that allow users to retrieve information about the application's state. To enable the creation of queries using the CLI interface, a function
queryCommand is generally added to the
queryCommand function adds all the queries available to end-users for the application. This typically includes:
- QueryTx and/or other transaction query commands] from the
authmodule which allow the user to search for a transaction by inputting its hash, a list of tags, or a block height. These queries allow users to see if transactions have been included in a block.
- Account command from the
authmodule, which displays the state (e.g. account balance) of an account given an address.
- Validator command from the Cosmos SDK rpc client tools, which displays the validator set of a given height.
- Block command from the Cosmos SDK rpc client tools, which displays the block data for a given height.
- All module query commands the application is dependent on, retrieved by using the basic module manager's
Here is an example of a
queryCommand aggregating subcommands from the
Flags are used to modify commands; developers can include them in a
flags.go file with their CLI. Users can explicitly include them in commands or pre-configure them by inside their
app.toml. Commonly pre-configured flags include the
--node to connect to and
--chain-id of the blockchain the user wishes to interact with.
A persistent flag (as opposed to a local flag) added to a command transcends all of its children: subcommands will inherit the configured values for these flags. Additionally, all flags have default values when they are added to commands; some toggle an option off but others are empty values that the user needs to override to create valid commands. A flag can be explicitly marked as required so that an error is automatically thrown if the user does not provide a value, but it is also acceptable to handle unexpected missing flags differently.
Flags are added to commands directly (generally in the module's CLI file where module commands are defined) and no flag except for the
rootCmd persistent flags has to be added at application level. It is common to add a persistent flag for
--chain-id, the unique identifier of the blockchain the application pertains to, to the root command. Adding this flag can be done in the
main() function. Adding this flag makes sense as the chain ID should not be changing across commands in this application CLI. Here is an example from the
Each flag is bound to it's respecteve named environment variable. Then name of the environment variable consist of two parts - capital case
basename followed by flag name of the flag.
- must be substituted with
_. For example flag
--home for application with basename
GAIA is bound to
GAIA_HOME. It allows reducing the amount of flags typed for routine operations. For example instead of:
gaia --home=./ --node=<node address> --chain-id="testchain-1" --keyring-backend=test tx ... --from=<key name>
this will be more convenient:
# define env variables in .env, .envrc etc
GAIA_HOME=<path to home>
# and later just use
gaia tx ... --from=<key name>
It is vital that the root command of an application uses
PersistentPreRun() cobra command property for executing the command, so all child commands have access to the server and client contexts. These contexts are set as their default values initially and maybe modified, scoped to the command, in their respective
PersistentPreRun() functions. Note that the
client.Context is typically pre-populated with "default" values that may be useful for all commands to inherit and override if necessary.
Here is an example of an
PersistentPreRun() function from
SetCmdClientContextHandler call reads persistent flags via
ReadPersistentCommandFlags which creates a
client.Context and sets that on the root command's
InterceptConfigsPreRunHandler call creates a viper literal, default
server.Context, and a logger and sets that on the root command's
server.Context will be modified and saved to disk via the internal
interceptConfigs call, which either reads or creates a Tendermint configuration based on the home path provided. In addition,
interceptConfigs also reads and loads the application configuration,
app.toml, and binds that to the
server.Context viper literal. This is vital so the application can get access to not only the CLI flags, but also to the application configuration values provided by this file.