Documentation

ANR Commands

Commands for the Avalanche Network Runner.

Global Flags​

  • --dial-timeout duration server dial timeout (default 10s)
  • --endpoint string server endpoint (default "localhost:8080")
  • --log-dir string log directory
  • --log-level string log level (default "INFO")
  • --request-timeout duration client request timeout (default 3m0s)

Ping​

Pings the server.

avalanche-network-runner ping [options] [flags]

Example​

avalanche-network-runner ping
curl --location --request POST 'http://localhost:8081/v1/ping'

Server​

Starts a network runner server.

avalanche-network-runner server [options] [flags]

Flags​

  • --dial-timeout duration server dial timeout (default 10s)
  • --disable-grpc-gatewaytrue to disable grpc-gateway server (overrides --grpc-gateway-port)
  • --disable-nodes-output true to disable nodes stdout/stderr
  • --grpc-gateway-port string grpc-gateway server port (default ":8081")
  • --log-dir string log directory
  • --log-level string log level for server logs (default "INFO")
  • --port string server port (default ":8080")
  • --snapshots-dir string directory for snapshots

Example​

avalanche-network-runner server

Control​

Network runner control commands.

avalanche-network-runner control [command]

add-node​

Adds a new node to the network.

avalanche-network-runner control add-node node-name [options] [flags]

Flags​

  • --avalanchego-path string AvalancheGo binary path
  • --chain-configs string [optional] JSON string of map from chain id to its config file contents
  • --node-config string node config as string
  • --plugin-dir string [optional] plugin directory
  • --subnet-configs string [optional] JSON string of map from Avalanche L1 id (SubnetID) to its config file contents
  • --upgrade-configs string [optional] JSON string of map from chain id to its upgrade file contents

Example​

avalanche-network-runner control add-node node6
curl --location 'http://localhost:8081/v1/control/addnode' \
--header 'Content-Type: application/json' \
--data '{
  "name": "node6"
}'

add-subnet-validators​

Adds Avalanche L1 validators.

avalanche-network-runner control add-subnet-validators validatorsSpec [options] [flags]

Example​

avalanche-network-runner control add-subnet-validators '[{"subnet_id": "p433wpuXyJiDhyazPYyZMJeaoPSW76CBZ2x7wrVPLgvokotXz", "node_names":["node1"]}]'
curl --location 'http://localhost:8081/v1/control/addsubnetvalidators' \
--header 'Content-Type: application/json' \
--data '[{"subnetId": "p433wpuXyJiDhyazPYyZMJeaoPSW76CBZ2x7wrVPLgvokotXz", "nodeNames":["node1"]}]'

attach-peer​

Attaches a peer to the node.

avalanche-network-runner control attach-peer node-name [options] [flags]

Example​

avalanche-network-runner control attach-peer node5
curl --location 'http://localhost:8081/v1/control/attachpeer' \
--header 'Content-Type: application/json' \
--data '{
    "nodeName":"node5"
}'

create-blockchains​

Creates blockchains.

avalanche-network-runner control create-blockchains blockchain-specs [options] [flags]

Example​

avalanche-network-runner control create-blockchains '[{"vm_name":"subnetevm","genesis":"/path/to/genesis.json", "subnet_id": "p433wpuXyJiDhyazPYyZMJeaoPSW76CBZ2x7wrVPLgvokotXz"}]'
curl --location 'http://localhost:8081/v1/control/createblockchains' \
--header 'Content-Type: application/json' \
--data '{
  "blockchainSpecs": [
    {
      "vm_name": "subnetevm",
      "genesis": "/path/to/genesis.json",
      "subnet_id": "p433wpuXyJiDhyazPYyZMJeaoPSW76CBZ2x7wrVPLgvokotXz"
    }
  ]
}'

create-subnets​

Creates Avalanche L1s.

avalanche-network-runner control create-subnets [options] [flags]

Example​

avalanche-network-runner control create-subnets '[{"participants": ["node1", "node2", "node3", "node4", "node5"]}]'
curl --location 'http://localhost:8081/v1/control/createsubnets' \
--header 'Content-Type: application/json' \
--data '
{
    "participants": [
        "node1",
        "node2",
        "node3",
        "node4",
        "node5"
    ]
}'

get-snapshot-names​

Lists available snapshots.

avalanche-network-runner control get-snapshot-names [options] [flags]

Example​

avalanche-network-runner control get-snapshot-names
curl --location --request POST 'http://localhost:8081/v1/control/getsnapshotnames'

health​

Waits until local cluster is ready.

avalanche-network-runner control health [options] [flags]

Example​

./build/avalanche-network-runner control health
curl --location --request POST 'http://localhost:8081/v1/control/health'

list-blockchains​

Lists all blockchain ids of the network.

avalanche-network-runner control list-blockchains [flags]

Example​

avalanche-network-runner control list-blockchains
curl --location --request POST 'http://localhost:8081/v1/control/listblockchains'

list-rpcs​

Lists RPCs for all blockchains in the network.

Flags​

avalanche-network-runner control list-rpcs [flags]

Example​

avalanche-network-runner control list-rpcs
curl --location --request POST 'http://localhost:8081/v1/control/listrpcs'

list-subnets​

Lists all Avalanche L1 IDs (SubnetID) of the network.

avalanche-network-runner control list-subnets [flags]

Example​

avalanche-network-runner control list-subnets
curl --location --request POST 'http://localhost:8081/v1/control/listsubnets'

load-snapshot​

Loads a network snapshot.

avalanche-network-runner control load-snapshot snapshot-name [flags]
 
if the `AVALANCHEGO_EXEC_PATH` and `AVALANCHEGO_PLUGIN_PATH` env vars aren't set then you should pass them in as a flag
avalanche-network-runner control load-snapshot snapshotName --avalanchego-path /path/to/avalanchego/binary --plugin-dir /path/to/avalanchego/plugins

Flags​

  • --avalanchego-path string AvalancheGo binary path
  • --chain-configs string [optional] JSON string of map from chain id to its config file contents
  • --global-node-config string [optional] global node config as JSON string, applied to all nodes
  • --plugin-dir string plugin directory
  • --reassign-ports-if-used true to reassign snapshot ports if already taken
  • --root-data-dir string root data directory to store logs and configurations
  • --subnet-configs string [optional] JSON string of map from Avalanche L1 id to its config file contents
  • --upgrade-configs string [optional] JSON string of map from chain id to its upgrade file contents

Example​

avalanche-network-runner control load-snapshot snapshot
curl --location 'http://localhost:8081/v1/control/loadsnapshot' \
--header 'Content-Type: application/json' \
--data '{
    "snapshotName":"snapshot"
}'
 
if the `AVALANCHEGO_EXEC_PATH` and `AVALANCHEGO_PLUGIN_PATH` env vars aren't set then you should pass them in to the curl
curl -X POST -k http://localhost:8081/v1/control/loadsnapshot -d '{"snapshotName":"node5","execPath":"/path/to/avalanchego/binary","pluginDir":"/path/to/avalanchego/plugins"}'

pause-node​

Pauses a node.

avalanche-network-runner control pause-node node-name [options] [flags]

Example​

avalanche-network-runner control pause-node node5
curl --location 'http://localhost:8081/v1/control/pausenode' \
--header 'Content-Type: application/json' \
--data '{
  "name": "node5"
}'

remove-node​

Removes a node.

avalanche-network-runner control remove-node node-name [options] [flags]

Example​

avalanche-network-runner control remove-node node5
curl --location 'http://localhost:8081/v1/control/removenode' \
--header 'Content-Type: application/json' \
--data '{
    "name":"node5"
}'

remove-snapshot​

Removes a network snapshot.

avalanche-network-runner control remove-snapshot snapshot-name [flags]

Example​

avalanche-network-runner control remove-snapshot node5
curl --location 'http://localhost:8081/v1/control/removesnapshot' \
--header 'Content-Type: application/json' \
--data '{
    "snapshot_name":"node5"
}'

remove-subnet-validator​

Removes an Avalanche L1 validator.

avalanche-network-runner control remove-subnet-validator removeValidatorSpec [options] [flags]

Example​

avalanche-network-runner control remove-subnet-validator '[{"subnet_id": "p433wpuXyJiDhyazPYyZMJeaoPSW76CBZ2x7wrVPLgvokotXz", "node_names":["node1"]}]'
curl --location 'http://localhost:8081/v1/control/removesubnetvalidator' \
--header 'Content-Type: application/json' \
--data '[{"subnetId": "p433wpuXyJiDhyazPYyZMJeaoPSW76CBZ2x7wrVPLgvokotXz", "nodeNames":["node1"]}]'

restart-node​

Restarts a node.

avalanche-network-runner control restart-node node-name [options] [flags]

Flags​

  • --avalanchego-path string AvalancheGo binary path
  • --chain-configs string [optional] JSON string of map from chain id to its config file contents
  • --plugin-dir string [optional] plugin directory
  • --subnet-configs string [optional] JSON string of map from Avalanche L1 id (SubnetID) to its config file contents
  • --upgrade-configs string [optional] JSON string of map from chain id to its upgrade file contents
  • --whitelisted-subnets string [optional] whitelisted Avalanche L1s (comma-separated)

Example​

avalanche-network-runner control restart-node \
--request-timeout=3m \
--log-level debug \
--endpoint="localhost:8080" \
node1 
curl --location 'http://localhost:8081/v1/control/restartnode' \
--header 'Content-Type: application/json' \
--data '{
  "name": "node5"
}'

resume-node​

Resumes a node.

avalanche-network-runner control resume-node node-name [options] [flags]

Example​

avalanche-network-runner control resume-node node5
curl --location 'http://localhost:8081/v1/control/resumenode' \
--header 'Content-Type: application/json' \
--data '{
  "name": "node5"
}'

rpc_version​

Gets RPC server version.

avalanche-network-runner control rpc_version [flags]

Example​

./build/avalanche-network-runner control rpc_version
curl --location --request POST 'http://localhost:8081/v1/control/rpcversion'

save-snapshot​

Saves a network snapshot.

avalanche-network-runner control save-snapshot snapshot-name [flags]

Example​

avalanche-network-runner control save-snapshot snapshotName
curl --location 'http://localhost:8081/v1/control/savesnapshot' \
--header 'Content-Type: application/json' \
--data '{
    "snapshot_name":"node5"
}'

send-outbound-message​

Sends an outbound message to an attached peer.

avalanche-network-runner control send-outbound-message node-name [options] [flags]

Flags​

  • --message-bytes-b64 string Message bytes in base64 encoding
  • --message-op uint32 Message operation type
  • --peer-id string peer ID to send a message to

Example​

avalanche-network-runner control send-outbound-message \
--request-timeout=3m \
--log-level debug \
--endpoint="localhost:8080" \
--node-name node1 \
--peer-id "7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg" \
--message-op=16 \
--message-bytes-b64="EAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKgAAAAPpAqmoZkC/2xzQ42wMyYK4Pldl+tX2u+ar3M57WufXx0oXcgXfXCmSnQbbnZQfg9XqmF3jAgFemSUtFkaaZhDbX6Ke1DVpA9rCNkcTxg9X2EcsfdpKXgjYioitjqca7WA="
curl -X POST -k http://localhost:8081/v1/control/sendoutboundmessage -d '{"nodeName":"node1","peerId":"7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg","op":16,"bytes":"EAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKgAAAAPpAqmoZkC/2xzQ42wMyYK4Pldl+tX2u+ar3M57WufXx0oXcgXfXCmSnQbbnZQfg9XqmF3jAgFemSUtFkaaZhDbX6Ke1DVpA9rCNkcTxg9X2EcsfdpKXgjYioitjqca7WA="}'

start​

Starts a network.

avalanche-network-runner control start [options] [flags]

Flags​

  • --avalanchego-path string AvalancheGo binary path
  • --blockchain-specs string [optional] JSON string of array of [(VM name, genesis file path)]
  • --chain-configs string [optional] JSON string of map from chain id to its config file contents
  • --custom-node-configs global-node-config [optional] custom node configs as JSON string of map, for each node individually. Common entries override global-node-config, but can be combined. Invalidates number-of-nodes (provide all node configs if used).
  • --dynamic-ports true to assign dynamic ports
  • --global-node-config string [optional] global node config as JSON string, applied to all nodes
  • --number-of-nodes uint32 number of nodes of the network (default 5)
  • --plugin-dir string [optional] plugin directory
  • --reassign-ports-if-used true to reassign default/given ports if already taken
  • --root-data-dir string [optional] root data directory to store logs and configurations
  • --subnet-configs string [optional] JSON string of map from Avalanche L1 id (SubnetID) to its config file contents
  • --upgrade-configs string [optional] JSON string of map from chain id to its upgrade file contents
  • --whitelisted-subnets string [optional] whitelisted Avalanche L1s (comma-separated)

Example​

avalanche-network-runner control start \
  --log-level debug \
  --endpoint="localhost:8080" \
  --number-of-nodes=5 \
  --blockchain-specs '[{"vm_name": "subnetevm", "genesis": "./path/to/config.json"}]'
curl --location 'http://localhost:8081/v1/control/start' \
--header 'Content-Type: application/json' \
--data '{
  "numNodes": 5,
  "blockchainSpecs": [
    {
      "vm_name": "subnetevm",
      "genesis": "/path/to/config.json"
    }
  ]
}'

status​

Gets network status.

avalanche-network-runner control status [options] [flags]

Example​

./build/avalanche-network-runner control status
curl --location --request POST 'http://localhost:8081/v1/control/status'

stop​

Stops the network.

avalanche-network-runner control stop [options] [flags]

Example​

avalanche-network-runner control stop
curl --location --request POST 'http://localhost:8081/v1/control/stop'

stream-status​

Gets a stream of network status.

avalanche-network-runner control stream-status [options] [flags]

Flags​

--push-interval duration interval that server pushes status updates to the client (default 5s)

Example​

avalanche-network-runner control stream-status
curl --location --request POST 'http://localhost:8081/v1/control/streamstatus'

uris​

Lists network URIs.

avalanche-network-runner control uris [options] [flags]

Example​

avalanche-network-runner control uris
curl --location --request POST 'http://localhost:8081/v1/control/uris'

vmid​

Returns the VM ID associated to the given VM name.

avalanche-network-runner control vmid vm-name [flags]

Example​

/build/avalanche-network-runner control vmid subnetevm
curl --location 'http://localhost:8081/v1/control/vmid' \
--header 'Content-Type: application/json' \
--data '{
    "vmName": "subnetevm"
}'

wait-for-healthy​

Waits until local cluster and custom VMs are ready.

avalanche-network-runner control wait-for-healthy [options] [flags]

Example​

./build/avalanche-network-runner control wait-for-healthy
curl --location --request POST 'http://localhost:8081/v1/control/waitforhealthy'
Edit on GitHub Report Issue

Last updated on 3/10/2025

On this page

Global Flags​
Ping​
Example​
Server​
Flags​
Example​
Control​
add-node​
Flags​
Example​
add-subnet-validators​
Example​
attach-peer​
Example​
create-blockchains​
Example​
create-subnets​
Example​
get-snapshot-names​
Example​
health​
Example​
list-blockchains​
Example​
list-rpcs​
Flags​
Example​
list-subnets​
Example​
load-snapshot​
Flags​
Example​
pause-node​
Example​
remove-node​
Example​
remove-snapshot​
Example​
remove-subnet-validator​
Example​
restart-node​
Flags​
Example​
resume-node​
Example​
rpc_version​
Example​
save-snapshot​
Example​
send-outbound-message​
Flags​
Example​
start​
Flags​
Example​
status​
Example​
stop​
Example​
stream-status​
Flags​
Example​
uris​
Example​
vmid​
Example​
wait-for-healthy​
Example​

Privacy Policy

We respect your privacy and are committed to protecting your personal data. This privacy policy will inform you about how we look after your personal data and tell you about your privacy rights.

Read full policy