CLI commands

The Avail node binary provides a comprehensive set of commands for running, managing, and interacting with your blockchain node.

Running the node

By default, running the node without any subcommand starts the node in normal mode:

avail-node [OPTIONS]

See the Flags reference for all available options.

Commands overview

All commands are invoked using the following pattern:

avail-node <COMMAND> [OPTIONS]

benchmark

Performance benchmarking utilities

try-runtime

Test commands against runtime state

key

Key management and generation

verify

Verify message signatures

vanity

Generate vanity addresses

sign

Sign messages with keys

build-spec

Build chain specifications

check-block

Validate block integrity

export-blocks

Export blockchain data

export-state

Export state snapshots

import-blocks

Import blockchain data

purge-chain

Remove chain data

revert

Revert to previous state

chain-info

Display database information

benchmark

Sub-commands for performance benchmarking. The pallet benchmarking functionality is available under the pallet sub-command.

avail-node benchmark <SUBCOMMAND>

Benchmarking commands are primarily used during development and testing to measure the performance characteristics of pallets and runtime components.

Common benchmark subcommands

The benchmark command includes several subcommands:

pallet - Benchmark pallet execution times
storage - Benchmark storage operations
overhead - Benchmark block and extrinsic overhead
block - Benchmark block execution
machine - Benchmark hardware capabilities

Example

# Benchmark a specific pallet
avail-node benchmark pallet --pallet pallet_balances --extrinsic transfer

# Run machine benchmarks
avail-node benchmark machine

try-runtime

Execute commands against runtime state for testing and debugging purposes.

avail-node try-runtime <SUBCOMMAND>

The try-runtime feature must be enabled at compile time. If not enabled, this command will not be available.

Use cases

Testing runtime upgrades before deployment
Debugging runtime behavior
Validating state migrations
Simulating transactions

Example

# Test runtime upgrade
avail-node try-runtime on-runtime-upgrade live --uri wss://rpc.example.com

key

Key management utilities for generating, inspecting, and managing cryptographic keys.

avail-node key <SUBCOMMAND>

Subcommands

generate

Generate a new secret key and output the corresponding public key and account ID.

avail-node key generate

Example output:

Secret phrase:       daughter song common combine misery cotton audit morning stuff weasel flee field
Network ID:          substrate
Secret seed:         0x3c881bc4d45926680c64a7f9315eeda3dd287f8d598f3653d7c107799c5422b3
Public key (hex):    0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
Account ID:          0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
Public key (SS58):   5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
SS58 Address:        5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY

inspect

Inspect a secret URI and display the associated public key and account ID.

avail-node key inspect "your-secret-phrase"

insert

Insert a key into the keystore.

avail-node key insert --key-type gran --suri "your-secret-phrase"

inspect-key

Inspect a key in the keystore.

avail-node key inspect-key

Common options

--scheme - Cryptographic scheme (Sr25519, Ed25519, Ecdsa)
--network - Network address format
--output-type - Output format (Json, Text)

verify

Verify a signature for a message provided on STDIN with a given public or secret key.

avail-node verify <PUBLIC_KEY> <SIGNATURE>

Example

echo "Hello, Avail!" | avail-node verify 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d 0x...

The message is read from standard input (STDIN), while the public key and signature are provided as arguments.

vanity

Generate a seed that produces a vanity address matching a specific pattern.

avail-node vanity <PATTERN>

Example

# Generate address starting with "5Avail"
avail-node vanity 5Avail

Example output:

Searching for pattern: 5Avail
Found match after 42357 attempts
Secret phrase:       abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about
Public key (SS58):   5AvaiLxyz...

Generating vanity addresses can be computationally expensive. Longer patterns take exponentially more time to find.

sign

Sign a message with a given secret key.

avail-node sign <SECRET_KEY>

Example

echo "Hello, Avail!" | avail-node sign "your-secret-phrase"

Output:

0x1234567890abcdef... (signature)

The message is read from standard input (STDIN). The signature is output to STDOUT.

build-spec

Build and export a chain specification file.

avail-node build-spec [OPTIONS]

Common options

--chain <CHAIN_SPEC> - Source chain specification
--raw - Output as raw (runtime-compatible) format
--disable-default-bootnode - Disable default bootnodes

Examples

# Export chain spec in JSON format
avail-node build-spec --chain dev > chain-spec.json

# Export raw chain spec for runtime
avail-node build-spec --chain dev --raw > chain-spec-raw.json

Raw chain specs are required for production networks. They contain the compiled runtime and cannot be easily modified.

check-block

Validate blocks from the database or imported from files.

avail-node check-block [OPTIONS]

Options

--block-hash <HASH> - Block hash to check
--default-heap-pages <COUNT> - Default heap pages for Wasm execution

Example

avail-node check-block --block-hash 0x1234...

export-blocks

Export blocks to a file.

avail-node export-blocks [OPTIONS] <OUTPUT_FILE>

Options

--from <BLOCK> - Starting block number (default: 1)
--to <BLOCK> - Ending block number
--binary - Export in binary format instead of JSON

Examples

# Export all blocks
avail-node export-blocks blocks.dat

# Export specific range
avail-node export-blocks --from 1000 --to 2000 blocks-1k-2k.dat

# Export in JSON format
avail-node export-blocks --json blocks.json

export-state

Export the state of a given block into a chain specification.

avail-node export-state [OPTIONS]

Options

--block <BLOCK> - Block hash or number to export state from
--chain <CHAIN_SPEC> - Source chain specification

Example

# Export state at specific block
avail-node export-state --block 1000 > state-at-1000.json

# Export latest finalized state
avail-node export-state > latest-state.json

Exported state can be used to bootstrap new networks or create fork chains for testing.

import-blocks

Import blocks from a file.

avail-node import-blocks [OPTIONS] <INPUT_FILE>

Options

--default-heap-pages <COUNT> - Default heap pages for Wasm execution
--execution <STRATEGY> - Execution strategy for block import
--binary - Import binary format instead of JSON

Example

# Import blocks from file
avail-node import-blocks blocks.dat

# Import with specific execution strategy
avail-node import-blocks --execution wasm blocks.dat

purge-chain

Remove the entire chain database.

avail-node purge-chain [OPTIONS]

Options

--chain <CHAIN_SPEC> - Chain specification
--base-path <PATH> - Base path for chain data
-y - Skip confirmation prompt

Example

# Purge chain with confirmation
avail-node purge-chain --chain dev

# Purge without confirmation (dangerous!)
avail-node purge-chain --chain dev -y

This command permanently deletes all blockchain data including blocks, state, and keys. This action cannot be undone. Always ensure you have backups before running this command.

revert

Revert the chain to a previous state by removing recent blocks.

avail-node revert [OPTIONS]

Options

--num <BLOCKS> - Number of blocks to revert (default: 256)

Example

# Revert last 256 blocks (default)
avail-node revert

# Revert last 100 blocks
avail-node revert --num 100

Reverting blocks can cause your node to fall out of sync with the network. Only use this for local development or testing.

chain-info

Display database metadata and column information.

avail-node chain-info [OPTIONS]

Example

avail-node chain-info --chain dev

Example output:

Database: ParityDB
Path: /home/user/.local/share/avail-node/chains/dev/paritydb/full

Columns:
- header: 1234 items
- body: 1234 items
- transaction: 5678 items

Help and version

Get help

Display help information for any command:

# General help
avail-node help

# Help for specific command
avail-node help benchmark

# Short help summary
avail-node -h

Check version

avail-node --version

Example output:

avail-node 1.8.0-x86_64-linux-gnu

Kate RPC

Runtime APIs

CLI Reference

​Running the node

​Commands overview

benchmark

try-runtime

key

verify

vanity

sign

build-spec

check-block

export-blocks

export-state

import-blocks

purge-chain

revert

chain-info

​benchmark

​Common benchmark subcommands

​Example

​try-runtime

​Use cases

​Example

​key

​Subcommands

​generate

​inspect

​insert

​inspect-key

​Common options

​verify

​Example

​vanity

​Example

​sign

​Example

​build-spec

​Common options

​Examples

​check-block

​Options

​Example

​export-blocks

​Options

​Examples

​export-state

​Options

​Example

​import-blocks

​Options

​Example

​purge-chain

​Options

​Example

​revert

​Options

​Example

​chain-info

​Example

​Help and version

​Get help

​Check version

​Next steps

Flags reference

Running a node

Build docs developers (and LLMs) love

Running the node

Commands overview

benchmark

Common benchmark subcommands

Example

try-runtime

Use cases

Example

key

Subcommands

generate

inspect

insert

inspect-key

Common options

verify

Example

vanity

Example

sign

Example

build-spec

Common options

Examples

check-block

Options

Example

export-blocks

Options

Examples

export-state

Options

Example

import-blocks

Options

Example

purge-chain

Options

Example

revert

Options

Example

chain-info

Example

Help and version

Get help

Check version

Next steps