Documentation
Quick StartBuild AppsAvalanche L1sInteroperabilityCustom VMsNodes & ValidatorsToolingsAPI ReferencesBuilder Kit

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'

Is this guide helpful?

Edit on GitHub Report Issue

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​