Skip to content

Command Line Reference

This reference describes the syntax of the Lodestar CLI commands and their options.

Global Options

Option Type Description Default
--dataDir string Lodestar root data directory
--network string Name of the Ethereum Consensus chain network to join mainnet
--paramsFile string Network configuration file
--terminal-total-difficulty-override string Terminal PoW block TTD override
--terminal-block-hash-override string Terminal PoW block hash override
--terminal-block-hash-epoch-override string Terminal PoW block hash override activation epoch

beacon

Run a beacon chain node

Examples

Run a beacon chain node and connect to the goerli testnet

beacon --network goerli

Options

Option Type Description Default
--checkpointSyncUrl string Server url hosting Beacon Node APIs to fetch weak subjectivity state. Fetch latest finalized by default, else set --wssCheckpoint
--checkpointState string Set a checkpoint state to start syncing from
--wssCheckpoint string Start beacon node off a state at the provided weak subjectivity checkpoint, to be supplied in : format. For example, 0x1234:100 will sync and start off from the weak subjectivity state at checkpoint of epoch 100 with block root 0x1234.
--forceCheckpointSync boolean Force syncing from checkpoint state even if db state is within weak subjectivity period. This helps to avoid long sync times after node has been offline for a while.
--private boolean Do not send implementation details over p2p identify protocol and in builder requests
--logLevel string Logging verbosity level for emitting logs to terminal info
--logFile string Path to output all logs to a persistent log file, use 'none' to disable
--logFileLevel string Logging verbosity level for emitting logs to file debug
--logFileDailyRotate number Daily rotate log files, set to an integer to limit the file count, set to 0 (zero) to disable rotation 5
--rest boolean Enable/disable HTTP API true
--rest.namespace array Pick namespaces to expose for HTTP API. Set to '*' to enable all namespaces ["beacon","config","events","node","validator","lightclient"]
--rest.cors string Configures the Access-Control-Allow-Origin CORS header for HTTP API *
--rest.address string Set host for HTTP API 127.0.0.1
--rest.port number Set port for HTTP API 9596
--suggestedFeeRecipient string Specify fee recipient default for collecting the EL block fees and rewards (a hex string representing 20 bytes address: ^0x[a-fA-F0-9]{40}$) in case validator fails to update for a validator index before calling produceBlock. 0x0000000000000000000000000000000000000000
--emitPayloadAttributes boolean Flag to SSE emit execution payloadAttributes before every slot false
--eth1 boolean Whether to follow the eth1 chain true
--eth1.providerUrls array Urls to Eth1 node with enabled rpc. If not explicitly provided and execution endpoint provided via execution.urls, it will use execution.urls. Otherwise will try connecting on the specified default(s) http://localhost:8545
--execution.urls array Urls to execution client engine API http://localhost:8551
--execution.timeout number Timeout in milliseconds for execution engine API HTTP client 12000
--execution.retryAttempts number Number of retry attempts when calling execution engine API 3
--execution.retryDelay number Delay time in milliseconds between retries when retrying calls to the execution engine API 2000
--jwt-secret string File path to a shared hex-encoded jwt secret which will be used to generate and bundle HS256 encoded jwt tokens for authentication with the EL client's rpc server hosting engine apis. Secret to be exactly same as the one used by the corresponding EL client.
--builder boolean Enable builder interface
--builder.urls array Urls hosting the builder API http://localhost:8661
--builder.timeout number Timeout in milliseconds for builder API HTTP client 12000
--builder.faultInspectionWindow number Window to inspect missed slots for enabling/disabling builder circuit breaker
--builder.allowedFaults number Number of missed slots allowed in the faultInspectionWindow for builder circuit
--metrics boolean Enable the Prometheus metrics HTTP server
--metrics.port number Listen TCP port for the Prometheus metrics HTTP server 8008
--metrics.address string Listen address for the Prometheus metrics HTTP server 127.0.0.1
--monitoring.endpoint string Enables monitoring service for sending clients stats to the specified endpoint of a remote service (e.g. beaconcha.in)
--monitoring.interval number Interval in milliseconds between sending client stats to the remote service 60000
--discv5 boolean Enable discv5 true
--listenAddress string The IPv4 address to listen for p2p UDP and TCP connections 0.0.0.0
--port number The TCP/UDP port to listen on. The UDP port can be modified by the --discoveryPort flag. 9000
--discoveryPort number The UDP port that discovery will listen on. Defaults to port port
--listenAddress6 string The IPv6 address to listen for p2p UDP and TCP connections
--port6 number The TCP/UDP port to listen on. The UDP port can be modified by the --discoveryPort6 flag. 9090
--discoveryPort6 number The UDP port that discovery will listen on. Defaults to port6 port6
--bootnodes array Bootnodes for discv5 discovery []
--targetPeers number The target connected peers. Above this number peers will be disconnected 50
--deterministicLongLivedAttnets boolean Use deterministic subnet selection for long-lived subnet subscriptions true
--subscribeAllSubnets boolean Subscribe to all subnets regardless of validator count false
--disablePeerScoring boolean Disable peer scoring, used for testing on devnets false
--mdns boolean Enable mdns local peer discovery false
--terminal-total-difficulty-override string Terminal PoW block TTD override
--terminal-block-hash-override string Terminal PoW block hash override
--terminal-block-hash-epoch-override string Terminal PoW block hash override activation epoch
--enr.ip string Override ENR IP entry
--enr.tcp number Override ENR TCP entry
--enr.udp number Override ENR UDP entry
--enr.ip6 string Override ENR IPv6 entry
--enr.tcp6 number Override ENR (IPv6-specific) TCP entry
--enr.udp6 number Override ENR (IPv6-specific) UDP entry
--nat boolean Allow configuration of non-local addresses

validator

Run one or multiple validator clients

Examples

Run one validator client with all the keystores available in the directory .goerli/keystores

validator --network goerli

Options

The options below apply to all sub-commands.

Option Type Description Default
--logLevel string Logging verbosity level for emitting logs to terminal info
--logFile string Path to output all logs to a persistent log file, use 'none' to disable
--logFileLevel string Logging verbosity level for emitting logs to file debug
--logFileDailyRotate number Daily rotate log files, set to an integer to limit the file count, set to 0 (zero) to disable rotation 5
--keymanager boolean Enable key manager API server
--keymanager.authEnabled boolean Enable token bearer authentication for key manager API server true
--keymanager.port number Set port for key manager API 5062
--keymanager.address string Set host for key manager API 127.0.0.1
--keymanager.cors string Configures the Access-Control-Allow-Origin CORS header for key manager API *
--beaconNodes array Addresses to connect to BeaconNode http://127.0.0.1:9596
--force boolean Open validators even if there's a lockfile. Use with caution
--graffiti string Specify your custom graffiti to be included in blocks (plain UTF8 text, 32 characters max)
--proposerSettingsFile string A yaml file to specify detailed default and per validator public key customized proposer configs. PS: This feature and its format is in alpha and subject to change
--suggestedFeeRecipient string Specify fee recipient default for collecting the EL block fees and rewards (a hex string representing 20 bytes address: ^0x[a-fA-F0-9]{40}$). It would be possible (WIP) to override this per validator key using config or key manager API. Only used post merge. 0x0000000000000000000000000000000000000000
--strictFeeRecipientCheck boolean Enable strict checking of the validator's feeRecipient with the one returned by engine
--defaultGasLimit number Suggested gas limit to the engine/builder for building execution payloads. Only used post merge. 30000000
--builder boolean Enable execution payload production via a builder for better rewards
--builder.selection string Default builder block selection strategy: maxprofit, builderalways, or builderonly maxprofit
--importKeystores array Path(s) to a directory or single file path to validator keystores, i.e. Launchpad validators ./keystores/*.json
--importKeystoresPassword string Path to a file with password to decrypt all keystores from importKeystores option ./password.txt
--doppelgangerProtection boolean Enables Doppelganger protection
--externalSigner.url string URL to connect to an external signing server
--externalSigner.pubkeys array List of validator public keys used by an external signer. May also provide a single string a comma separated public keys
--externalSigner.fetch boolean Fetch then list of public keys to validate from an external signer
--distributed boolean Enables specific features required to run as part of a distributed validator cluster
--metrics boolean Enable the Prometheus metrics HTTP server false
--metrics.port number Listen TCP port for the Prometheus metrics HTTP server 5064
--metrics.address string Listen address for the Prometheus metrics HTTP server 127.0.0.1
--monitoring.endpoint string Enables monitoring service for sending clients stats to the specified endpoint of a remote service (e.g. beaconcha.in)
--monitoring.interval number Interval in milliseconds between sending client stats to the remote service 60000

validator slashing-protection

Import or export slashing protection data to or from another client.

Options

The options below apply to all sub-commands.

Option Type Description Default
--beaconNodes array Addresses to connect to BeaconNode http://127.0.0.1:9596
--force boolean If genesisValidatorsRoot can't be fetched from the Beacon node, use a zero hash

validator slashing-protection import

Import an interchange file.

Examples

Import an interchange file to the slashing protection DB

validator slashing-protection import --network goerli --file interchange.json

Options

Option Type Description Default
--file string The slashing protection interchange file to import (.json).

validator slashing-protection export

Export an interchange file.

Examples

Export an interchange JSON file for all validators in the slashing protection DB

validator slashing-protection export --network goerli --file interchange.json

Options

Option Type Description Default
--file string The slashing protection interchange file to export to (.json).
--pubkeys array Export slashing protection data only for a given subset of public keys

validator import

Imports one or more EIP-2335 keystores into a Lodestar validator client directory, requesting passwords interactively. The directory flag provides a convenient method for importing a directory of keys generated by the eth2-deposit-cli Ethereum Foundation utility.

Examples

Import validator keystores generated with the Ethereum Foundation Staking Launchpad

validator import --network goerli --importKeystores $HOME/staking-deposit-cli/validator_keys

Options

Option Type Description Default
--importKeystores array Path(s) to a directory or single file path to validator keystores, i.e. Launchpad validators ./keystores/*.json
--importKeystoresPassword string Path to a file with password to decrypt all keystores from importKeystores option ./password.txt

validator list

Lists the public keys of all validators

Examples

List all validator public keys previously imported

validator list

validator voluntary-exit

Performs a voluntary exit for a given set of validators as identified via pubkeys. If no pubkeys are provided, it will exit all validators that have been imported.

Examples

Perform a voluntary exit for the validator who has a public key 0xF00

validator voluntary-exit --network goerli --pubkeys 0xF00

Options

Option Type Description Default
--exitEpoch number The epoch upon which to submit the voluntary exit. If no value is provided, then we default to the current epoch.
--pubkeys array Public keys to exit, must be available as local signers
--yes boolean Skip confirmation prompt

validator bls-to-execution-change

Performs BLS To Execution Change for a given validator (as identified via publicKey. If no publicKey is provided, a prompt will ask the user which validator they would like to choose for BLS To Execution Change.

Examples

Perform BLS To Execution Change for the validator who has a public key 0xF00

validator bls-to-execution-change --publicKey 0xF00 --fromBlsPrivkey ... --toExecutionAddress ...

Options

Option Type Description Default
--publicKey string Validator public key for which to set withdrawal address hence enabling withdrawals
--fromBlsPrivkey string Bls withdrawals private key to sign the message
--toExecutionAddress string Address to which the validator's balances will be set to be withdrawn.

lightclient

Run lightclient

Examples

Run lightclient with goerli network

lightclient --network goerli

Options

Option Type Description Default
--logLevel string Logging verbosity level for emitting logs to terminal info
--logFile string Path to output all logs to a persistent log file, use 'none' to disable
--logFileLevel string Logging verbosity level for emitting logs to file debug
--logFileDailyRotate number Daily rotate log files, set to an integer to limit the file count, set to 0 (zero) to disable rotation 5
--beaconApiUrl string Url to a beacon node that support lightclient API
--checkpointRoot string Checkpoint root hex string to sync the lightclient from, start with 0x

dev

Quickly bootstrap a beacon node and multiple validators. Use for development and testing

Examples

Start a single beacon node with 8 interop validators

dev --genesisValidators 8 --reset

Options

Cmd dev has all the options from the beacon cmd.

Option Type Description Default
--keymanager boolean Enable key manager API server
--keymanager.authEnabled boolean Enable token bearer authentication for key manager API server true
--keymanager.port number Set port for key manager API 5062
--keymanager.address string Set host for key manager API 127.0.0.1
--keymanager.cors string Configures the Access-Control-Allow-Origin CORS header for key manager API *
--beaconNodes array Addresses to connect to BeaconNode http://127.0.0.1:9596
--force boolean Open validators even if there's a lockfile. Use with caution
--graffiti string Specify your custom graffiti to be included in blocks (plain UTF8 text, 32 characters max)
--proposerSettingsFile string A yaml file to specify detailed default and per validator public key customized proposer configs. PS: This feature and its format is in alpha and subject to change
--strictFeeRecipientCheck boolean Enable strict checking of the validator's feeRecipient with the one returned by engine
--defaultGasLimit number Suggested gas limit to the engine/builder for building execution payloads. Only used post merge. 30000000
--builder.selection string Default builder block selection strategy: maxprofit, builderalways, or builderonly maxprofit
--importKeystores array Path(s) to a directory or single file path to validator keystores, i.e. Launchpad validators ./keystores/*.json
--importKeystoresPassword string Path to a file with password to decrypt all keystores from importKeystores option ./password.txt
--doppelgangerProtection boolean Enables Doppelganger protection
--externalSigner.url string URL to connect to an external signing server
--externalSigner.pubkeys array List of validator public keys used by an external signer. May also provide a single string a comma separated public keys
--externalSigner.fetch boolean Fetch then list of public keys to validate from an external signer
--distributed boolean Enables specific features required to run as part of a distributed validator cluster
--network string Name of the Ethereum Consensus chain network to join mainnet
--genesisEth1Hash string If present it will create genesis with this eth1 hash.
--genesisValidators number If present it will create genesis with interop validators and start chain. 8
--startValidators string Start interop validators in inclusive range with notation '0..7'
--genesisTime number genesis_time to initialize interop genesis state now
--reset boolean To delete chain and validator directories
--dumpTestnetFiles string Dump testnet files and exit

bootnode

Run a discv5 bootnode. This will NOT perform any beacon node functions, rather, it will run a discv5 service that allows nodes on the network to discover one another.

Options

Option Type Description Default
--listenAddress string The IPv4 address to listen for discv5 connections 0.0.0.0
--port number The UDP port to listen on 9000
--listenAddress6 string The IPv6 address to listen for discv5 connections
--port6 number The UDP port to listen on 9090
--bootnodes array Additional bootnodes for discv5 discovery []
--bootnodesFile string Additional bootnodes for discv5 discovery file path
--persistNetworkIdentity boolean Whether to reuse the same peer-id across restarts true
--enr.ip string Override ENR IP entry
--enr.udp number Override ENR UDP entry
--enr.ip6 string Override ENR IPv6 entry
--enr.udp6 number Override ENR (IPv6-specific) UDP entry
--nat boolean Allow ENR configuration of non-local addresses
--logLevel string Logging verbosity level for emitting logs to terminal info
--logFile string Path to output all logs to a persistent log file, use 'none' to disable
--logFileLevel string Logging verbosity level for emitting logs to file debug
--logFileDailyRotate number Daily rotate log files, set to an integer to limit the file count, set to 0 (zero) to disable rotation 5
--metrics boolean Enable the Prometheus metrics HTTP server
--metrics.port number Listen TCP port for the Prometheus metrics HTTP server 8008
--metrics.address string Listen address for the Prometheus metrics HTTP server 127.0.0.1