gem-hunter
Language: Go
Command-line tool to create, deploy and operate Avalanche networks and L1s
Maintenance Mode Notice
As of December 2025, Avalanche CLI has entered maintenance mode. This means:
- No new features will be developed by the Ava Labs team
- Only security patches and critical bug fixes will be addressed
- GitHub issues are expected to be addressed by community members
External contributions are very much welcome! PRs will be reviewed but may not be prioritized. We encourage the community to continue building and improving this project.
Avalanche CLI is a command line tool that gives developers access to everything Avalanche. This release specializes in helping developers develop and test L1s.
The tool has been tested on Linux and Mac. Windows is currently not supported.
To download a binary for the latest release, run:
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -sThe binary will be installed inside the ~/bin directory.
To add the binary to your path, run
export PATH=~/bin:$PATH
To add it to your path permanently, add an export command to your shell initialization script (ex: .bashrc).
To download the binary into a specific directory, run:
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s -- -b <relative directory>
Documentation of all available commands can be found in the Avalanche Documentation.
To get started easily, we provide a Dev Container specification, that can be used using GitHub Codespace or locally using Docker and VS Code. Dev Containers are a concept that utilizes containerization to create consistent and isolated development environment. You can run them directly on Github by clicking Code, switching to the Codespaces tab and clicking Create codespace on main. Alternatively, you can run them locally with the extensions for VS Code or other code editors.
After installing, launch your own custom layer 1:
avalanche blockchain create <L1Name> avalanche blockchain deploy <L1Name>
Shut down your local deployment with:
avalanche network stop
Restart your local deployment (from where you left off) with:
avalanche network start
You can provide a global node config to edit the way your local avalanchego nodes perform under the hood. To provide such a config, you need to create an avalanche-cli config file. By default, a config file is read in from $HOME/.avalanche-cli/config.json If none exists, no error will occur. To provide a config from a custom location, run any command with the flag --config <pathToConfig>.
To specify the global node config, provide it as a body for the node-config key. Ex:
{
"network-peer-list-gossip-frequency": "250ms",
"network-max-reconnect-delay": "1s",
"public-ip": "127.0.0.1",
"health-check-frequency": "2s",
"api-admin-enabled": true,
"api-ipcs-enabled": true,
"index-enabled": true
}You may wish to deploy your l1 on a cloud instance and access it remotely. If you'd like to do so, use this as your node config:
{
"node-config": {
"http-host": "0.0.0.0"
}
}To build Avalanche-CLI, you'll first need to install golang. Follow the instructions here: https://go.dev/doc/install.
Once golang is installed, run:
./scripts/build.sh
The binary will be called ./bin/avalanche.
To make Avalanche CLI work in a docker container, add this
{
"ipv6": true,
"fixed-cidr-v6": "fd00::/80"
}to /etc/docker/daemon.json on the host, then restart the docker service. This is because ipv6 is used to resolve local bootstrap IPs, and it is not enabled on a docker container by default.
To run our suite of end-to-end tests, you'll need to install Node-JS and yarn. You can follow instructions to do that here and here.
To run the tests, execute the following command from the repo's root directory:
./scripts/run.e2e.sh
Network snapshots are used by the CLI in order to keep track of blockchain state, and to improve performance of local deployments.
They are the main way to persist blockchains and blockchain operations, among different executions of the tool.
Three different kinds of snapshots are used:
bootstrap snapshot is provided as the starting network state. It is never modified by CLI usage.
Designed for fast deploys. Enables full reset of the blockchain state.default snapshot is the main way to keep track of blockchain state. Used by default in the tools.
It is initialized from the bootstrap snapshot, and after that is updated from CLI operations.custom snapshots can be specified by the user, to save and restore particular states. Only changed if
explicitly asked to do so.Usage of local networks:
network start and blockchain deploy will start it from the default snapshot.
blockchain deploy will also do the deploy on the started network.network start will do nothing, and blockchain deploy will use the running one to do the deploy.network stop, network clean, or until machine rebootHow the CLI commands affect the default snapshot:
network start or blockchain deploy will initialize default snapshot from the bootstrap snapshotblockchain deploy do not change the snapshot, only the running networknetwork stop persist the running network into the default snapshotnetwork clean copy again the bootstrap snapshot into the default snapshot, doing a reset of the stateSo typically a user will want to do the deploy she needs, change the blockchain state in a specific way, and
after that execute network stop to preserve all the state. In a different session, network start or blockchain deploy
will recover that state.
How the CLI commands affect the custom snapshots:
network stop can be given an optional snapshot name. This will then be used instead of the default one to save the statenetwork start can be given an optional snapshot name. This will then be used instead of the default one to save the stateblockchain deploy will take a running network if it is available, so there is a need to use network start previously to do
deploys, if wanting to use custom snapshotsnetwork clean does not change custom snapshotsSo typically a user who wants to use a custom snapshot will do the deploy she needs, change the blockchain state in a specific way, and
after that execute network stop with --snapshot-name flag to preserve all the state into the desired snapshot.
In a different session, network start with --snapshot-name flag will be called to load that specific snapshot, and after that
blockchain deploy can be used on top of it. Notice that you need to continue giving --snapshot-name flag to those commands if you
continue saving/restoring to it, if not, default snapshot will be used.
~/.avalanche-cli/snapshot will contain all saved snapshots, which can for example be used to pass work aroundMore detailed information on how to use Avalanche CLI can be found here.