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 weakSubjectivity state at checkpoint of epoch 100 with block root 0x1234.
--logLevel string Logging verbosity level for emittings 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 emittings 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"]
--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
--eth1 boolean Whether to follow the eth1 chain true
--eth1.providerUrls array Urls to Eth1 node with enabled rpc. If not explicity 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
--execution.timeout number Timeout in miliseconds for execution engine API HTTP client
--execution.retryAttempts number Number of retry attempts when calling execution engine API 1
--execution.retryDelay number Delay time in milliseconds between retries when retrying calls to the execution engine API 0
--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 false
--builder.urls array Urls hosting the builder API
--builder.timeout number Timeout in miliseconds for builder API HTTP client
--metrics boolean Enable the Prometheus metrics HTTP server false
--metrics.port number Listen TCP port for the Prometheus metrics HTTP server 8008
--metrics.address string Listen address for the Prometheus metrics HTTP server undefined
--discv5 boolean Enable discv5 true
--listenAddress string The 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 --discovery-port flag. 9000
--discoveryPort number The UDP port that discovery will listen on. Defaults to port port
--bootnodes array Bootnodes for discv5 discovery []
--targetPeers number The target connected peers. Above this number peers will be disconnected 50
--subscribeAllSubnets boolean Subscribe to all subnets regardless of validator count 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

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 subcommands.

Option Type Description Default
--logLevel string Logging verbosity level for emittings 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 emittings 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 keymanager API server
--keymanager.authEnabled boolean Enable token bearer authentication for keymanager API server true
--keymanager.port number Set port for keymanager API 5062
--keymanager.address string Set host for keymanager API 127.0.0.1
--keymanager.cors string Configures the Access-Control-Allow-Origin CORS header for keymanager 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 pubkey 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 keymanager 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 gasLimit 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
--importKeystores array Path(s) to a directory or single filepath 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
--doppelgangerProtectionEnabled 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 pubkeys to validate from an external signer
--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

validator slashing-protection

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

Options

The options below apply to all subcommands.

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).

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 --keystores $HOME/eth2.0-deposit-cli/validator_keys

Options

Option Type Description Default
--logLevel string Logging verbosity level for emittings 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 emittings 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 keymanager API server
--keymanager.authEnabled boolean Enable token bearer authentication for keymanager API server true
--keymanager.port number Set port for keymanager API 5062
--keymanager.address string Set host for keymanager API 127.0.0.1
--keymanager.cors string Configures the Access-Control-Allow-Origin CORS header for keymanager 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 pubkey 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 keymanager 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 gasLimit 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
--importKeystores array Path(s) to a directory or single filepath 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
--doppelgangerProtectionEnabled 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 pubkeys to validate from an external signer
--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

validator list

Lists the public keys of all validators

Examples

List all validator pubkeys previously imported

account validator list

validator voluntary-exit

Performs a voluntary exit 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 the voluntary exit.

Examples

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

account validator voluntary-exit --publicKey 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 currentEpoch.
--pubkeys array Pubkeys to exit, must be available as local signers
--yes boolean Skip confirmation prompt

lightclient

Run lightclient

Examples

Run lightclient with goerli network

lightclient --network goerli

Options

Option Type Description Default
--logLevel string Logging verbosity level for emittings 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 emittings 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 keymanager API server
--keymanager.authEnabled boolean Enable token bearer authentication for keymanager API server true
--keymanager.port number Set port for keymanager API 5062
--keymanager.address string Set host for keymanager API 127.0.0.1
--keymanager.cors string Configures the Access-Control-Allow-Origin CORS header for keymanager 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 pubkey 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 gasLimit to the engine/builder for building execution payloads. Only used post merge. 30000000
--importKeystores array Path(s) to a directory or single filepath 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
--doppelgangerProtectionEnabled 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 pubkeys to validate from an external signer
--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