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
--rootDir string Lodestar root directory
--network string Name of the Eth2 chain network to join mainnet
--preset string Specifies the default eth2 spec type mainnet
--paramsFile string Network configuration file $rootDir/config.yaml

beacon

Run a beacon chain node

Examples

Run a beacon chain node and connect to the pyrmont testnet

beacon --network pyrmont

Options

Option Type Description Default
--forceGenesis boolean Force beacon to create genesis without file
--genesisStateFile string Path or URL to download a genesis state file in ssz-encoded format
--weakSubjectivityStateFile string Path or URL to download a weak subjectivity state file in ssz-encoded format
--weakSubjectivitySyncLatest boolean Enable fetching of a weak subjectivity state via --weakSubjectivityServerUrl. If an argument is provided to --weakSubjectivityCheckpoint, fetch the state at that checkpoint. Else, fetch the latest finalized state.
--weakSubjectivityCheckpoint string Tell the beacon node to fetch a weak subjectivity state at the specified checkpoint. The string arg must be in the form :. For example, 0x1234:100 would ask for the weak subjectivity state at checkpoint of epoch 100 with block root 0x1234.
--weakSubjectivityServerUrl string Pass in a custom server from which to fetch weak subjectivity states (if you don't want to use the built-in Lodestar servers).
--logLevel string Logging verbosity level info
--logLevelFile string Logging verbosity level for file transport info
--logRotate boolean Daily rotate log files
--logMaxFiles number Number of log files to maintain while rotating logs(if provided with logRotate)
--configFile string Beacon node configuration file path $rootDir/beacon.config.json
--logFile string Path to output all logs to a persistent log file
--api.rest.api array Pick namespaces to expose for HTTP API. Set to '*' to enable all namespaces ["beacon","config","events","node","validator"]
--api.rest.cors string Configures the Access-Control-Allow-Origin CORS header for HTTP API *
--api.rest.enabled boolean Enable/disable HTTP API false
--api.rest.host string Set host for HTTP API 127.0.0.1
--api.rest.port number Set port for HTTP API 9596
--eth1.enabled boolean Whether to follow the eth1 chain true
--eth1.providerUrl string Url to Eth1 node with enabled rpc http://localhost:8545
--eth1.depositContractDeployBlock number Block number at which the deposit contract contract was deployed 0
--metrics.enabled boolean Enable metrics false
--metrics.gatewayUrl string Gateway URL for metrics
--metrics.serverPort number Server port for metrics 8008
--metrics.timeout number How often metrics should be probed 5000
--metrics.listenAddr string The address for the metrics http server to listen on undefined
--network.discv5.enabled boolean Enable discv5 true
--network.discv5.bindAddr string Local multiaddress to listen on for discv5 /ip4/0.0.0.0/udp/9000
--network.discv5.bootEnrs array Bootnodes for discv5 discovery []
--network.maxPeers number The maximum number of connections allowed 30
--network.targetPeers number The target connected peers. Above this number peers will be disconnected 25
--network.bootMultiaddrs array Libp2p peers to connect to on boot []
--network.localMultiaddrs array Local listening addresses for req/resp and gossip ["/ip4/0.0.0.0/tcp/9000"]
--network.subscribeAllSubnets boolean Subscribe to all subnets regardless of validator count false
--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 .pyrmont/keystores

validator --network pyrmont

Options

Option Type Description Default
--keystoresDir string Directory for storing validator keystores. $rootDir/keystores
--secretsDir string Directory for storing validator keystore secrets. $rootDir/secrets
--logLevel string Logging verbosity level info
--logLevelFile string Logging verbosity level for file transport info
--logRotate boolean Daily rotate log files
--logMaxFiles number Number of log files to maintain while rotating logs(if provided with logRotate)
--logFile string Path to output all logs to a persistent log file
--validatorsDbDir string Data directory for validator databases. $rootDir/validator-db
--server string Address 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)

account

Utilities for generating and managing Ethereum 2.0 accounts

account validator

Provides commands for managing Eth2 validators.

Options

The options below apply to all subcommands.

Option Type Description Default
--keystoresDir string Directory for storing validator keystores. $rootDir/keystores
--secretsDir string Directory for storing validator keystore secrets. $rootDir/secrets

account validator create

Creates new validators from an existing EIP-2386 wallet using the EIP-2333 HD key derivation scheme. Creates a new directory per validator with a voting keystore, withdrawal keystore, and pre-computed deposit RPL data

Examples

Create a validator from HD wallet named 'primary'

account validator create --name primary --passphraseFile primary.pass

Options

Option Type Description Default
--name string Use the wallet identified by this name
--passphraseFile string A path to a file containing the password which will unlock the wallet.
--depositGwei string The GWEI value of the deposit amount. Defaults to the minimum amount required for an active validator (MAX_EFFECTIVE_BALANCE)
--storeWithdrawalKeystore boolean If present, the withdrawal keystore will be stored alongside the voting keypair. It is generally recommended to not store the withdrawal key and instead generate them from the wallet seed when required.
--count number The number of validators to create 1

account validator deposit

DEPRECATED. Please use the official tools to perform your deposits - eth2.0-deposit-cli: https://github.com/ethereum/eth2.0-deposit-cli - Ethereum Foundation launchpad: https://pyrmont.launchpad.ethereum.org

Examples

Options

account 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 Eth2 Launchpad

account validator import --network pyrmont --directory $HOME/eth2.0-deposit-cli/validator_keys

Options

Option Type Description Default
--keystore string Path to a single keystore to be imported.
--directory string Path to a directory which contains zero or more keystores for import. This directory and all sub-directories will be searched and any file name which contains 'keystore' and has the '.json' extension will be attempted to be imported.

account validator list

Lists the public keys of all validators

Examples

List all validator pubkeys in the directory .testing/keystores

account validator list --keystoresDir .testing/keystores

account validator recover

Recovers validator private keys given a BIP-39 mnemonic phrase. If you did not specify a --firstIndex or count --count, by default this will only recover the keys associated with the validator at index 0 for an HD wallet in accordance with the EIP-2333 spec.

Examples

Recover validator

account validator recover

Options

Option Type Description Default
--count number The number of validators to create 1
--depositGwei string The GWEI value of the deposit amount. Defaults to the minimum amount required for an active validator (MAX_EFFECTIVE_BALANCE)
--storeWithdrawalKeystore boolean If present, the withdrawal keystore will be stored alongside the voting keypair. It is generally recommended to not store the withdrawal key and instead generate them from the wallet seed when required.
--mnemonicInputPath string If present, the mnemonic will be read in from this file.
--firstIndex number The first of consecutive key indexes you wish to recover.

account 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
--server string Address 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
account validator slashing-protection import

Import an interchange file.

Examples

Import an interchange file to the slashing protection DB

account validator slashing-protection import --network pyrmont --file interchange.json

Options

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

Export an interchange file.

Examples

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

account validator slashing-protection export --network pyrmont --file interchange.json

Options

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

account 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
--keystoresDir string Directory for storing validator keystores. $rootDir/keystores
--secretsDir string Directory for storing validator keystore secrets. $rootDir/secrets
--logLevel string Logging verbosity level info
--logLevelFile string Logging verbosity level for file transport info
--logRotate boolean Daily rotate log files
--logMaxFiles number Number of log files to maintain while rotating logs(if provided with logRotate)
--logFile string Path to output all logs to a persistent log file
--validatorsDbDir string Data directory for validator databases. $rootDir/validator-db
--server string Address 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)
--publicKey string The public key of the validator to voluntarily exit
--exitEpoch number The epoch upon which to submit the voluntary exit. If no value is provided, then we default to the currentEpoch.

account wallet

Provides commands for managing Eth2 wallets.

Options

The options below apply to all subcommands.

Option Type Description Default
--walletsDir string Directory for storing wallets. $rootDir/wallets

account wallet create

Creates a new HD (hierarchical-deterministic) EIP-2386 wallet

Examples

Create an HD wallet named 'primary'

account wallet create --name primary --passphraseFile primary.pass

Options

Option Type Description Default
--walletsDir string Directory for storing wallets. $rootDir/wallets
--name string The wallet will be created with this name. It is not allowed to create two wallets with the same name for the same --base-dir.
--passphraseFile string A path to a file containing the password which will unlock the wallet. If the file does not exist, a random password will be generated and saved at that path. To avoid confusion, if the file does not already exist it must include a '.pass' suffix.
--type string The type of wallet to create. Only HD (hierarchical-deterministic) wallets are supported presently. hd
--mnemonicOutputPath string If present, the mnemonic will be saved to this file

account wallet list

Lists the names of all wallets

Examples

List all wallets in .network/wallets

account wallet list --walletsDir .network/wallets

account wallet recover

Recovers an EIP-2386 wallet from a given a BIP-39 mnemonic phrase.

Examples

Recover wallet

account wallet recover

Options

Option Type Description Default
--walletsDir string Directory for storing wallets. $rootDir/wallets
--name string The wallet will be created with this name. It is not allowed to create two wallets with the same name for the same --base-dir.
--passphraseFile string A path to a file containing the password which will unlock the wallet. If the file does not exist, a random password will be generated and saved at that path. To avoid confusion, if the file does not already exist it must include a '.pass' suffix.
--type string The type of wallet to create. Only HD (hierarchical-deterministic) wallets are supported presently. hd
--mnemonicOutputPath string If present, the mnemonic will be saved to this file
--mnemonicInputPath string If present, the mnemonic will be read in from this file.

init

Initialize Lodestar directories and files necessary to run a beacon chain node. This step is not required, and should only be used to prepare special configurations

Examples

Initialize a configuration for the Pyrmont testnet. Then, you can edit the config file .pyrmont/beacon.config.json to customize your beacon node settings

init --network pyrmont

Options

Cmd init has all the options from the beacon cmd.

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 --dev.genesisValidators 8 --dev.reset

Options

Cmd dev has all the options from the beacon cmd.

Option Type Description Default
--preset string Specifies the default eth2 spec type minimal
--genesisValidators number If present it will create genesis with interop validators and start chain.
--startValidators string Start interop validators in given range 0:8
--genesisTime number genesis_time to initialize interop genesis state
--reset boolean To delete chain and validator directories
--server string Address to connect to BeaconNode. Pass 'memory' for in memory communication http://127.0.0.1:9596