# Ignite CLI
In this section, you will:
- Install the Ignite CLI.
- Scaffold a blockchain.
- Use the CLI.
- Start the Ignite UI server.
- Send your first message.
You can follow a hands-on exercise for Ignite CLI in the sections that follow this introduction.
The Cosmos SDK provides the building blocks for a complete Tendermint blockchain, which implements the Inter-Blockchain Communication Protocol (IBC). The BaseApp of the Cosmos SDK assembles these building blocks and provides a fully-running blockchain. All there is left to do for the specific blockchain application is to create specific modules and integrate them with BaseApp to make the application your own.
Ignite CLI assists with scaffolding modules and integrating them with BaseApp. Ignite CLI is a command-line tool that writes code files and updates them when instructed to do so. If you come from an on Rails world, the concept will look familiar to you.
Ignite CLI also handles some compilation, runs a local blockchain node, and helps you with other tasks.
Want to dedicate some time to dive deeper into installing Ignite CLI? Learn how to install Ignite CLI in the Ignite CLI Developer Guide (opens new window).
This entire exercise was built using the Ignite CLI version 0.17.3. To install it at the command line:
Or if you install it in a Linux VM:
You can verify the version of Ignite CLI you have once it is installed:
This prints its old name and its version:
This entire exercise was built using the Ignite CLI version noted above. Using a newer version could work, but you might run into compatibility issues if you clone any code made with this version of Ignite CLI and then try to continue the project with your version of Ignite CLI.
If you need to install the latest version of Ignite CLI, use:
When you then run
ignite version, it prints its new name and its version:
If you'd like to upgrade an existing project to the latest version of Ignite CLI, you can follow the Ignite CLI migration documentation (opens new window).
You can also just type
ignite to see the offered commands:
# Your chain
Start by scaffolding a basic chain called
checkers that you will place under the GitHub path
For the sake of good support, the versions of all software used are communicated as encountered throughout the chapters and sections. It is natural that after the writing of the course material some version changes will appear, and it may occur that something breaks. Instead of using different versions of the software from the ones in the course, please look at the following list, which might fix problems you are running into.
If you work with a machine using M1 architecture, make sure:
- You follow this course in a [Rosetta]((https://www.courier.com/blog/tips-and-tricks-to-setup-your-apple-m1-for-development/) terminal.
- You install Homebrew (opens new window).
- You install Golang with
brew install go.
Building Errors during
If you work with Go 1.18, you may need to install the following:
- go install github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway@latest
- go install github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger@latest
- go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
- git clone https://github.com/regen-network/cosmos-proto cd cosmos-proto/protoc-gen-gocosmos go install
- go get github.com/golangci/golangci-lint/cmd/golangci-lint
- go get firstname.lastname@example.org
The scaffolding takes some time as it generates the source code for a fully functional, ready-to-use blockchain. Ignite CLI creates a folder named
checkers and scaffolds the chain inside it.
checkers folder contains several generated files and directories that make up the structure of a Cosmos SDK blockchain. It contains the following folders:
app: a folder for the application.
cmd: a folder for the command-line interface commands.
proto: a folder for the Protobuf objects definitions.
vue: a folder for the UI.
x: a folder for all your modules, in particular
If you look at the code that Ignite CLI generates, for instance in
./x/checkers/module.go, you will often see comments like the following:
Do not remove or replace any lines like these in your code as they provide markers for Ignite CLI on where to add further code when instructed to do so. For the same reason, do not rename or move any file that contains such a line.
Go to the
checkers folder and run:
ignite chain serve command downloads dependencies and compiles the source code into a binary called
checkersd. The command:
- Installs all dependencies.
- Builds Protobuf files.
- Compiles the application.
- Initializes the node with a single validator.
- Adds accounts.
After this command completes, you have a local testnet with a running node. What about the added accounts? Take a look:
In this file you can set the accounts, the accounts' starting balances, and the validator. You can also let Ignite CLI generate a client and a faucet. The faucet gives away five
token and 100,000
stake tokens belonging to Bob each time it is called.
You can observe the endpoints of the blockchain in the output of the
ignite chain serve command:
Ignite CLI can detect any change to the source code. When it does, it immediately rebuilds the binaries before restarting the blockchain and keeping the state.
# Interact via the CLI
You can already interact with your running chain. With the chain running in its shell, open another shell and try:
In there you can see a hint of liveness:
"latest_block_height":"142". You can use this one-liner for better display:
You can learn a lot by going through the possibilities with:
And so on.
# Your GUI
Boot up the frontend created by Ignite CLI by using the commands provided in the
readme.md file of the
checkers folder. Let the chain run in its own process and open a new terminal window in your
checkers folder. In this terminal execute:
If Vue complains about linting, for instance with:
You can safely tell it to ignore linting. To do that, in
package.json, change the
"serve" script to:
npm run serve (Node v16) complains about
node-sass, these versions should work in
Do not forget to redo
In case you face a blank page, please look in the browser console for an error message.
If you see that
regeneratorRuntime is missing, run
npm install --save regenerator-runtime in the Vue folder and include
const regeneratorRuntime = require("regenerator-runtime"); into the
<script> block of the
Navigate to localhost:8080 (opens new window). On the client-side, no wallets have been created or imported yet. Load Alice's wallet in the GUI to have some tokens. You will need to use the mnemonic for Alice, which you can find in the output of the
ignite chain serve command. If you do not see the mnemonic, it is because the mnemonic was shown to you the first time you ran the command and you did not copy it. So reset with
ignite chain serve --reset-once. Copy and paste it to import a wallet.
Now you should see the balance of Alice's account and can act on her behalf.
Select Custom Type in the sidebar to see custom types. There are no custom types yet, this page is empty for now.
Make a Git commit before you create a new
message. In fact, it is generally recommended to make a Git commit before running any
ignite scaffold command. A Git commit protects the work you have done so far and makes it easier to see what the
scaffold command added. It also makes it easy to just revert all changes if you are unsatisfied and want to run a different
# Your first message
After your Git commit, create a simple
ignite scaffold message command accepts a message name (here
createPost) as the first argument, and a list of fields for the message (here
body), which are
string fields unless mentioned otherwise.
A message is scaffolded in a module with a name that matches the name of the project by default. It is named
checkers in this case. Alternatively you could have used
--module checkers. Learn more about your options with:
You can see a list of files that were created or modified by the
scaffold message command in the Terminal output:
modify was made possible thanks to the lines like
// this line is used by starport scaffolding # 1 that you did not remove.
So where is everything? You can find the root definition of your new message in:
Ignite CLI also wired a new command into your chain's CLI in:
Ignite CLI scaffolded GUI elements relating to your message with a Vue.js frontend framework. You can, for instance, start with this function in:
# Next up
You just created a fully working Cosmos SDK chain, one that forms the basis of the following exercise.
You can remove the
MsgCreatePost message as it is not part of the guided exercise in the next sections. You can clean it all by running: