Skip to main content

Introduction

The Ash CLI aims to boost Avalanche developers' productivity by providing a set of commands to interact with Avalanche and Ash services.

Features​

The easiest way to explore 🔍 Avalanche networks from the command line

See the Network Exploration tutorial

ash avalanche help
Interact with Avalanche Subnets, blockchains and nodes

Usage: ash avalanche [OPTIONS] <COMMAND>

Commands:
  network    Interact with Avalanche networks
  node       Interact with Avalanche nodes
  subnet     Interact with Avalanche Subnets
  validator  Interact with Avalanche validators
  x          Interact with Avalanche X-Chain
  wallet     Interact with Avalanche wallets
  help       Print this message or the help of the given subcommand(s)
Support for any Avalanche network with custom configuration 📝

See the Custom Configuration tutorial.

~/.config/ash/my-custom-config.yml
---
avalancheNetworks:
  - name: my-network
    subnets:
      - id: 11111111111111111111111111111111LpoYY
        subnetType: PrimaryNetwork
        blockchains:
          - id: 11111111111111111111111111111111LpoYY
            name: P-Chain
            vmType: PlatformVM
            rpcUrl: http://validator01.ash.local:9650/ext/bc/P
          [...]
Create Subnets and blockchains 🛠️, 100% compatible with Avalanche CLI wizard

Use the Avalanche CLI wizard to configure the Subnet and Ash CLI to create it. See the Local Subnet Creation tutorial.

ash avalanche blockchain create testSubnetEVM \
  --subnet-id GQE4XUWgCR8ZryvhNdaCoyqVi25YNyh2nxyAjyCB3jXFL6gbk \
  --vm-type SubnetEVM \
  --genesis-file /tmp/encoded-genesis.json -w
Waiting for transaction to be accepted...
Blockchain created! (Tx ID: 'i2ZXw8NbVFxUK3kMjpwPtF2T3mtyoc6VWuH41rMfbc1NWE1Pb')
Blockchain 'testSubnetEVM':
  ID:      i2ZXw8NbVFxUK3kMjpwPtF2T3mtyoc6VWuH41rMfbc1NWE1Pb
  VM ID:   srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy
  VM type: SubnetEVM
Lightweight (written in Rust 🦀) and perfect for scripting with JSON output
export AVALANCHE_NETWORK=my-network
export ASH_CONFIG=~/.config/ash/my-network.yml
export ASH_JSON=true

ash avalanche validator info NodeID-CskPetRMvtH5Xr6gLa5cwfY4hR34UgkM5 | jq '.uptime'
The command line companion 🧑‍💻 of all the other Ash tools

Coming soon! Stay tuned by following @ash_avax 🐦!

Motivation​

Several factors motivated us to create the Ash CLI:

The need of an easy and scriptable way to explore Avalanche networks from the command line

  • A network information is accessible through AvalancheGo JSON-RPC APIs, that are not made to be queried directly by developers. Extra development is required to reach an acceptable level of usability (don't tell us you like querying JSON-RPC endpoints with cURL 😬).
  • The API layout is not optimal for all queries and sometimes requires multiple calls to get the desired information. The Ash CLI abstracts this complexity and provides a single command to get the information you need.

Let's see how easy it is to list all the blockchains of the Vn3aX6hNRstj5VHHm63TCgPNaeGnRSqCYXQqemSqDd2TQH4qJ Subnet using Ash CLI vs cURL:

curl -s -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlockchains",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' https://api.avax.network/ext/bc/P |
jq '.result.blockchains[] | select(.subnetID == "Vn3aX6hNRstj5VHHm63TCgPNaeGnRSqCYXQqemSqDd2TQH4qJ")'

Limitations of the Avalanche CLI developped by Ava Labs

  • The Avalanche CLI only support using the avalanche-network-runner for local/private networks. We needed a way to interact with any Avalanche network.
  • The Avalanche CLI outputs were not made to be parsed, which makes it impossible to use it in scripts, CI/CD pipelines or other automation tools.

The --json flag is available on all Ash CLI commands, making it super easy to filter the output with tools like jq:

ash avalanche validator info NodeID-CskPetRMvtH5Xr6gLa5cwfY4hR34UgkM5 --json | jq '.uptime'
99.9911