Command line reference

grandine --help
grandine bn --help
grandine vc --help

Modes and where options go

Grandine is a single binary that runs in one of three modes, plus a few tool subcommands.

Rules for placing options:

• With bn and vc, every option must come after the mode name. An option given before it is refused with the error --OPTION must be specified after bn (or vc), because it would otherwise be parsed for the plain grandine mode and silently dropped.

  # Correct
  grandine bn --network hoodi --eth1-rpc-urls http://EL-HOST:8551 --jwt-secret /path/to/jwt.hex
  
  # Refused: --network is given before bn
  grandine --network hoodi bn
  

• With the tool subcommands, global options such as --network and --data-dir come before the subcommand, and the subcommand's own arguments come after it:

  grandine --network hoodi interchange export slashing_protection.json
  grandine --network hoodi db-info --database sync
  

• vc refuses options that only the built-in beacon node acts on (for example --checkpoint-sync-url, --target-peers, --builder-url, --disable-wait-for-late-blocks), and bn refuses validator options (for example --keystore-dir, --enable-validator-api, --report-validator-performance). Plain grandine refuses the vc-only options --beacon-node-urls, --publish-to-every-node and --use-builder.

Value syntax

• Flags (options without a value) are off unless given: --back-sync.
• Some list options take several values after one flag, some take a comma-separated list, and some must be repeated. The tables below say which. For example:
  • --eth1-rpc-urls URL1 URL2 (space-separated; commas are not accepted)
  • --boot-nodes ENR1,ENR2 (comma-separated)
  • --graffiti TEXT1 --graffiti TEXT2 (repeat the flag)
  • --beacon-node-urls URL1,URL2 or --beacon-node-urls URL1 URL2 (both work)
• Sizes such as --database-size accept values like 512GiB, 2TiB or 500GB.
• URLs with credentials are redacted in Grandine's logs.

Loading options from a file

--args-file YAML_FILE loads options from a flat YAML mapping whose keys are long option names (without --). It is covered in Configuration files and custom networks. Options given on the command line override the same option in the file.

General

Options shared by every mode.

Chain

Options that select the network and its configuration.

Notes:

• When both --configuration-directory and --configuration-file (or --genesis-state-file) are given, the explicit file wins and Grandine logs a warning.
• The three --terminal-* overrides are applied after the verification options run.

Beacon node

Options of the beacon node. They are refused by grandine vc.

Storage

Database and directory options of the beacon node. See Storage and database.

HTTP API

The Beacon Node API server. See Beacon Node API.

Networking

Peer-to-peer networking options. See Networking and peers and Default ports.

When UPnP is enabled and you also set ENR options by hand, Grandine warns that UPnP might override them. Add --disable-upnp if you set the ENR yourself.

Block production

Options for proposing blocks. The first five are shared with grandine vc; the rest belong to the beacon node. See Fee recipient, graffiti and gas limit and Builder API and MEV.

Metrics

Prometheus metrics. See Metrics.

A separate validator client (grandine vc) exposes only validator client metrics.

Telemetry

OpenTelemetry (OTLP) tracing export. Experimental.

Validator

Validator client options. See Validator client.

Validator keys

Where validator keys come from. See Managing validator keys and Web3Signer.

Validator API

The validator client's own API, which serves the Keymanager API. Disabled unless --enable-validator-api is given. See Keymanager API.

Beacon nodes

Options of the separate validator client only. See Redundancy and fallback beacon nodes.

Cross-option checks

Besides the requires and conflicts rules in the tables, Grandine checks these when it starts:

• --network custom without --configuration-file (or --configuration-directory) fails with --configuration-file must be specified when connecting to custom network.
• A custom network without --eth1-rpc-urls needs a genesis state: --eth1-rpc-urls must be specified when connecting to custom network without --genesis-state-file.
• Validators attached to the built-in beacon node need an execution client: --eth1-rpc-urls must be specified when validators are present.
• --detect-doppelgangers with the built-in beacon node needs --track-liveness.
• --unfinalized-states-in-memory must be at least two epochs of slots.
• The HTTP API, metrics and validator API must not listen on the same address and port (identical addresses specified for ...).
• Each listening port is checked before startup: ... port (PORT) is unavailable; make sure no other instance of the application is running or specify a different port with OPTION.

Deprecated options

These still work but log a deprecation warning. Use the replacement.

Aliases

Removed options

Grandine has no hidden options. Older documentation mentions --slashing-enabled and --slashing-history-limit for the built-in slasher. These are no longer accepted on the command line: the slasher is disabled in the current code. See Slasher.

Subcommands

The tool subcommands and their own arguments are described in Subcommands and tools: