CLI flags - Avail

This page documents all command-line flags available for the Avail node. Flags can be used with or without subcommands to configure node behavior.

Usage

avail-node [FLAGS] [OPTIONS]
avail-node [COMMAND] [FLAGS] [OPTIONS]

Flags are specified with --flag-name for long form or -f for short form (when available). Boolean flags don’t require values.

Node operation

Validator mode

validator

boolean

default:"false"

Enable validator mode. The node will be started with the authority role and actively participate in consensus tasks.When enabled, the node will:

Participate in block production (if keys are available)
Vote on block finality (GRANDPA)
Require session keys to be configured

avail-node --validator

Development mode

dev

boolean

default:"false"

Run in development mode. This is a convenience flag that sets multiple options:

--chain=dev
--force-authoring
--rpc-cors=all
--alice
--tmp

Also disables local peer discovery unless explicitly overridden.

avail-node --dev

tmp

boolean

default:"false"

Run a temporary node. Creates a temporary directory for configuration, database, node key, and keystore. The directory is deleted when the process ends.Automatically enabled when using --dev without explicit --base-path.

avail-node --tmp

Chain specification

chain

string

default:""

Specify the chain specification. Can be:

A predefined chain: dev, local, or staging
A path to a chain spec file (JSON)

avail-node --chain dev
avail-node --chain /path/to/chain-spec.json

network-name

string

Override the network name and ID. This parameter updates the network name and ID for dev and dev_tri chains.

avail-node --chain dev --network-name "my-testnet"

Storage and database

Base path

base-path

string

Specify custom base path for chain data, configuration, and keys.Short form: -d

avail-node --base-path /mnt/avail-data
avail-node -d /mnt/avail-data

Database configuration

database

string

default:"auto"

Select database backend to use.Possible values:

paritydb - ParityDb (recommended)
auto - Detect existing database or create new ParityDb
paritydb-experimental - Experimental ParityDb features

avail-node --database paritydb

db-cache

number

default:"128"

Limit the memory the database cache can use (in MiB).

avail-node --db-cache 512

Pruning

state-pruning

string

default:"256"

Specify the state pruning mode. This setting is permanent after first run.Possible values:

archive - Keep state of all blocks
archive-canonical - Keep only state of finalized blocks
<number> - Keep state of last N finalized blocks

avail-node --state-pruning archive
avail-node --state-pruning 1000

blocks-pruning

string

default:"archive-canonical"

Specify the blocks pruning mode for block bodies and justifications.Possible values:

archive - Keep all blocks
archive-canonical - Keep only finalized blocks
<number> - Keep last N finalized blocks

avail-node --blocks-pruning archive

Storage monitoring

db-storage-threshold

number

default:"1024"

Required available space on database storage (in MiB). Node gracefully terminates if available space drops below this threshold.Set to 0 to disable monitoring.

avail-node --db-storage-threshold 2048

db-storage-polling-period

number

default:"5"

How often available space is polled (in seconds).

avail-node --db-storage-polling-period 10

RPC configuration

RPC server

rpc-port

number

default:"9944"

Specify JSON-RPC server TCP port.

avail-node --rpc-port 9933

rpc-external

boolean

default:"false"

Listen to all RPC interfaces (default is local only).

Not all RPC methods are safe to expose publicly. Use an RPC proxy server to filter dangerous methods, or use --unsafe-rpc-external to suppress the warning.

avail-node --rpc-external

unsafe-rpc-external

boolean

default:"false"

Listen to all RPC interfaces without safety warnings. Same as --rpc-external but suppresses warnings.

avail-node --unsafe-rpc-external

rpc-methods

string

default:"auto"

RPC methods to expose.Possible values:

auto - Expose all methods on localhost, only safe methods on external interfaces
safe - Allow only safe subset of RPC methods
unsafe - Expose all RPC methods (including potentially dangerous ones)

avail-node --rpc-methods safe

rpc-cors

string

default:""

Specify browser origins allowed to access HTTP & WS RPC servers.

Comma-separated list of origins (e.g., https://example.com)
Special value null for null origin
Value all disables origin validation

Default allows localhost and https://polkadot.js.org. In --dev mode, default is all.

avail-node --rpc-cors "https://app.example.com,https://dashboard.example.com"
avail-node --rpc-cors all

RPC limits

rpc-max-connections

number

default:"100"

Maximum number of RPC server connections.

avail-node --rpc-max-connections 200

rpc-max-request-size

number

default:"15"

Maximum RPC request payload size for HTTP and WebSocket (in megabytes).

avail-node --rpc-max-request-size 20

rpc-max-response-size

number

default:"15"

Maximum RPC response payload size for HTTP and WebSocket (in megabytes).

avail-node --rpc-max-response-size 20

rpc-max-subscriptions-per-connection

number

default:"1024"

Maximum concurrent subscriptions per connection.

avail-node --rpc-max-subscriptions-per-connection 2048

rpc-rate-limit

number

RPC rate limiting (calls per minute) for each connection. Disabled by default.

avail-node --rpc-rate-limit 100

rpc-message-buffer-capacity-per-connection

number

default:"64"

Number of messages the RPC server keeps in memory per connection.If buffer becomes full, server stops processing new messages until client reads underlying messages.

avail-node --rpc-message-buffer-capacity-per-connection 128

Networking

Network identity

name

string

Human-readable name for this node. Used as network node name.

avail-node --name "my-avail-node"

port

number

default:"30333"

Specify p2p protocol TCP port.

avail-node --port 30334

listen-addr

string[]

Listen on this multiaddress. Can be specified multiple times.Defaults:

Validator: /ip4/0.0.0.0/tcp/<port> and /ip6/[::]/tcp/<port>
Non-validator: /ip4/0.0.0.0/tcp/<port>/ws and /ip6/[::]/tcp/<port>/ws

avail-node --listen-addr /ip4/0.0.0.0/tcp/30333

public-addr

string[]

Public address that other nodes will use to connect. Use if there’s a proxy in front of this node.

avail-node --public-addr /dns/node.example.com/tcp/30333

Node keys

node-key

string

Secret key for p2p networking. Value is parsed as hex-encoded Ed25519 32-byte secret key (64 hex chars).

Secrets provided as command-line arguments are easily exposed. Use --node-key-file for production.

avail-node --node-key 0x1234567890abcdef...

node-key-type

string

default:"ed25519"

Crypto primitive for p2p networking.Possible values:

ed25519 - Use Ed25519

avail-node --node-key-type ed25519

node-key-file

string

File from which to read the node’s secret key for p2p networking.File must contain unencoded 32-byte or hex-encoded Ed25519 secret key. If file doesn’t exist, it’s created with a new key.

avail-node --node-key-file /path/to/node-key

Peer connections

bootnodes

string[]

Specify a list of bootnodes for initial peer discovery.

avail-node --bootnodes /dns/bootnode1.example.com/tcp/30333/p2p/12D3KooW...

reserved-nodes

string[]

Specify a list of reserved node addresses.

avail-node --reserved-nodes /dns/reserved1.example.com/tcp/30333/p2p/12D3KooW...

reserved-only

boolean

default:"false"

Only synchronize with reserved nodes. Also disables automatic peer discovery.

TCP connections may still be established with non-reserved nodes, particularly for validators.

avail-node --reserved-only

in-peers

number

default:"32"

Maximum number of inbound full node peers.

avail-node --in-peers 50

in-peers-light

number

default:"100"

Maximum number of inbound light node peers.

avail-node --in-peers-light 200

out-peers

number

default:"8"

Number of outgoing connections to maintain.

avail-node --out-peers 16

Network discovery

no-mdns

boolean

default:"false"

Disable mDNS local network discovery. Automatically enabled with --dev.

avail-node --no-mdns

discover-local

boolean

Enable peer discovery on local networks.Default is true for --dev or when chain type is Local/Development, otherwise false.

avail-node --discover-local

allow-private-ip

boolean

Always accept connections to private IPv4/IPv6 addresses.Enabled by default for local chains or --dev mode.

avail-node --allow-private-ip

no-private-ip

boolean

Always forbid connections to private IPv4/IPv6 addresses.Enabled by default for live chains. Doesn’t apply to --reserved-nodes or --bootnodes.

avail-node --no-private-ip

Kademlia DHT

kademlia-disjoint-query-paths

boolean

default:"false"

Require iterative Kademlia DHT queries to use disjoint paths for increased resiliency against adversarial nodes.

avail-node --kademlia-disjoint-query-paths

kademlia-replication-factor

number

default:"20"

Kademlia replication factor - determines to how many closest peers a record is replicated.

avail-node --kademlia-replication-factor 25

ipfs-server

boolean

default:"false"

Join the IPFS network and serve transactions over bitswap protocol.

avail-node --ipfs-server

Syncing

sync

string

default:"full"

Blockchain syncing mode.Possible values:

full - Full sync (download and verify all blocks)
fast - Download blocks without executing, download latest state with proofs
fast-unsafe - Download blocks without executing, download latest state without proofs
warp - Prove finality and download latest state

avail-node --sync warp

max-blocks-per-request

number

default:"64"

Maximum number of blocks per request. Reduce if experiencing block request timeouts on slow connections.

avail-node --max-blocks-per-request 32

max-parallel-downloads

number

default:"5"

Maximum number of peers to request same blocks from in parallel.Decrease to save bandwidth but risk increased latency.

avail-node --max-parallel-downloads 3

Runtime and execution

WASM execution

wasm-execution

string

default:"compiled"

Method for executing WASM runtime code.Possible values:

compiled - Uses compiled runtime (recommended)
interpreted-i-know-what-i-do - Uses interpreter (deprecated)

avail-node --wasm-execution compiled

wasmtime-instantiation-strategy

string

default:"pooling-copy-on-write"

WASM instantiation method. Only effective when wasm-execution is compiled.Possible values:

pooling-copy-on-write - Pool instances, use CoW memory (fastest, default)
recreate-instance-copy-on-write - Recreate each time, use CoW memory
pooling - Pool instances without CoW
recreate-instance - Recreate from scratch (very slow)

Copy-on-write strategies only supported on Linux. Falls back to non-CoW if unsupported.

avail-node --wasmtime-instantiation-strategy pooling

wasm-runtime-overrides

string

Path where local WASM runtimes are stored. These override on-chain runtimes when version matches.

avail-node --wasm-runtime-overrides /path/to/wasm

Execution strategy

execution

string

Execution strategy for all contexts.Possible values:

native - Native build (fallback to WASM)
wasm - Only WASM build
both - Both native and WASM
native-else-wasm - Native with WASM fallback

avail-node --execution wasm

execution-syncing

string

Runtime execution strategy during initial sync. Same values as --execution.

avail-node --execution-syncing wasm

execution-import-block

string

Runtime execution strategy for general block import. Same values as --execution.

avail-node --execution-import-block wasm

execution-block-construction

string

Runtime execution strategy for block construction. Same values as --execution.

avail-node --execution-block-construction wasm

execution-offchain-worker

string

Runtime execution strategy for offchain workers. Same values as --execution.

avail-node --execution-offchain-worker wasm

execution-other

string

Runtime execution strategy when not syncing, importing, or constructing blocks. Same values as --execution.

avail-node --execution-other wasm

Runtime configuration

max-runtime-instances

number

default:"8"

Size of the instances cache for each runtime. Maximum is 32.

avail-node --max-runtime-instances 16

runtime-cache-size

number

default:"2"

Maximum number of different runtimes that can be cached.

avail-node --runtime-cache-size 4

trie-cache-size

number

default:"67108864"

Specify the state cache size in bytes. Set to 0 to disable.

avail-node --trie-cache-size 134217728

Consensus

GRANDPA

no-grandpa

boolean

default:"false"

Disable GRANDPA. Disables voter in validator mode, otherwise disables GRANDPA observer.

avail-node --no-grandpa

grandpa-justification-period

number

default:"512"

Interval (in blocks) at which GRANDPA justifications are imported or generated and stored.Must be between 1 and 4,294,967,295.

avail-node --grandpa-justification-period 1024

Authoring

force-authoring

boolean

default:"false"

Enable authoring even when offline or not connected to peers.

avail-node --force-authoring

Transaction pool

pool-limit

number

default:"8192"

Maximum number of transactions in the transaction pool.

avail-node --pool-limit 16384

pool-kbytes

number

default:"20480"

Maximum number of kilobytes of all transactions stored in the pool.

avail-node --pool-kbytes 40960

tx-ban-seconds

number

default:"1800"

How long a transaction is banned (in seconds) if considered invalid.

avail-node --tx-ban-seconds 3600

Offchain workers

offchain-worker

string

default:"when-authority"

Execute offchain workers on every block.Possible values:

always - Always enable offchain worker
never - Never enable offchain worker
when-authority - Only when running as validator/collator

avail-node --offchain-worker always

enable-offchain-indexing

boolean

default:"false"

Enable offchain indexing API. Allows runtime to write directly to offchain workers DB during block import.

avail-node --enable-offchain-indexing true

Telemetry and monitoring

Telemetry

no-telemetry

boolean

default:"false"

Disable connecting to Substrate telemetry server. Telemetry is enabled by default on global chains.

avail-node --no-telemetry

telemetry-url

string[]

URL of telemetry server to connect to. Can be specified multiple times.Format: URL VERBOSITY where verbosity is 0-9 (0 = least verbose).

avail-node --telemetry-url 'wss://telemetry.example.com 0'

Prometheus

prometheus-port

number

default:"9615"

Specify Prometheus exporter TCP port.

avail-node --prometheus-port 9616

prometheus-external

boolean

default:"false"

Expose Prometheus exporter on all interfaces (default is local only).

avail-node --prometheus-external

no-prometheus

boolean

default:"false"

Disable Prometheus exporter endpoint. Prometheus is enabled by default.

avail-node --no-prometheus

Hardware benchmarks

no-hardware-benchmarks

boolean

default:"false"

Disable automatic hardware benchmarks at startup.By default, benchmarks measure CPU speed, memory bandwidth, and disk speed. Results are logged and sent via telemetry.

avail-node --no-hardware-benchmarks

Logging

log

string[]

Set custom logging filter. Syntax: <target>=<level>.Log levels: error, warn, info, debug, traceShort form: -l

avail-node --log error,sync=debug,grandpa=warn
avail-node -l info

detailed-log-output

boolean

default:"false"

Enable detailed log output including log target, level, and thread name.Automatically enabled when logging at levels higher than info.

avail-node --detailed-log-output

disable-log-color

boolean

default:"false"

Disable log color output.

avail-node --disable-log-color

enable-log-reloading

boolean

default:"false"

Enable dynamic log filter updates and reloading.

Can decrease performance by up to 6x depending on global logging level. Required for system_addLogFilter and system_resetLogFilter RPCs.

avail-node --enable-log-reloading

Tracing

tracing-targets

string

Set custom profiling filter. Same syntax as --log.

avail-node --tracing-targets pallet=trace

tracing-receiver

string

default:"log"

Receiver to process tracing messages.Possible values:

log - Output tracing records using the log

avail-node --tracing-receiver log

Keystore

keystore-path

string

Specify custom keystore path.

avail-node --keystore-path /path/to/keystore

password

string

Password used by the keystore. Appends an extra user-defined secret to the seed.

Providing passwords via command line is insecure. Use --password-filename or --password-interactive instead.

avail-node --password "my-password"

password-filename

string

File that contains the password used by the keystore.

avail-node --password-filename /secure/path/password.txt

password-interactive

boolean

default:"false"

Use interactive shell for entering the keystore password.

avail-node --password-interactive

Development accounts

These flags are shortcuts for development and testing. Each sets --name <NAME> --validator and adds the corresponding session keys to the keystore.

alice

boolean

default:"false"

Shortcut for --name Alice --validator with Alice’s session keys.

avail-node --alice

bob

boolean

default:"false"

Shortcut for --name Bob --validator with Bob’s session keys.

avail-node --bob

charlie

boolean

default:"false"

Shortcut for --name Charlie --validator with Charlie’s session keys.

avail-node --charlie

dave

boolean

default:"false"

Shortcut for --name Dave --validator with Dave’s session keys.

avail-node --dave

eve

boolean

default:"false"

Shortcut for --name Eve --validator with Eve’s session keys.

avail-node --eve

ferdie

boolean

default:"false"

Shortcut for --name Ferdie --validator with Ferdie’s session keys.

avail-node --ferdie

one

boolean

default:"false"

Shortcut for --name One --validator with One’s session keys.

avail-node --one

two

boolean

default:"false"

Shortcut for --name Two --validator with Two’s session keys.

avail-node --two

Avail-specific flags

These flags are specific to Avail and control Data Availability features.

Kate RPC

enable-kate-rpc

boolean

default:"false"

Enable Kate RPC endpoints for Data Availability queries.

avail-node --enable-kate-rpc

enable-kate-rpc-metrics

boolean

default:"false"

Enable Kate RPC metrics collection and reporting.

avail-node --enable-kate-rpc-metrics

kate-max-cells-size

number

default:"64"

Maximum number of cells that can be requested in one Kate RPC call.Must not exceed 10,000.

avail-node --kate-max-cells-size 128

Data Availability sync

unsafe-da-sync

boolean

default:"false"

Disable checking commitment on imported blocks during sync.

This flag disables important Data Availability verification. Only use for testing or when you understand the security implications. Cannot be used with --validator.

avail-node --unsafe-da-sync

Common flag combinations

Development node

avail-node --dev --tmp

Production validator

avail-node \
  --validator \
  --name "my-validator" \
  --chain mainnet \
  --base-path /mnt/avail-data \
  --state-pruning archive \
  --rpc-port 9944 \
  --prometheus-external \
  --telemetry-url 'wss://telemetry.avail.so/submit 0'

RPC node

avail-node \
  --chain mainnet \
  --base-path /mnt/avail-data \
  --rpc-external \
  --rpc-cors all \
  --rpc-methods safe \
  --rpc-max-connections 1000 \
  --state-pruning 256

Archive node

avail-node \
  --chain mainnet \
  --base-path /mnt/avail-data \
  --state-pruning archive \
  --blocks-pruning archive \
  --db-cache 2048

Kate RPC

Runtime APIs

CLI Reference

​Usage

​Node operation

​Validator mode

​Development mode

​Chain specification

​Storage and database

​Base path

​Database configuration

​Pruning

​Storage monitoring

​RPC configuration

​RPC server

​RPC limits

​Networking

​Network identity

​Node keys

​Peer connections

​Network discovery

​Kademlia DHT

​Syncing

​Runtime and execution

​WASM execution

​Execution strategy

​Runtime configuration

​Consensus

​GRANDPA

​Authoring

​Transaction pool

​Offchain workers

​Telemetry and monitoring

​Telemetry

​Prometheus

​Hardware benchmarks

​Logging

​Tracing

​Keystore

​Development accounts

​Avail-specific flags

​Kate RPC

​Data Availability sync

​Common flag combinations

​Development node

​Production validator

​RPC node

​Archive node

​Next steps

Commands reference

Running a node

Build docs developers (and LLMs) love

Usage

Node operation

Validator mode

Development mode

Chain specification

Storage and database

Base path

Database configuration

Pruning

Storage monitoring

RPC configuration

RPC server

RPC limits

Networking

Network identity

Node keys

Peer connections

Network discovery

Kademlia DHT

Syncing

Runtime and execution

WASM execution

Execution strategy

Runtime configuration

Consensus

GRANDPA

Authoring

Transaction pool

Offchain workers

Telemetry and monitoring

Telemetry

Prometheus

Hardware benchmarks

Logging

Tracing

Keystore

Development accounts

Avail-specific flags

Kate RPC

Data Availability sync

Common flag combinations

Development node

Production validator

RPC node

Archive node

Next steps