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