---
title: "CLI Reference"
sidebar_position: 7
description: "Complete CLI flag reference for Erigon — all startup options, environment variables, and configuration settings."
---


# CLI Reference

The Erigon CLI has a wide range of flags that can be used to customize its behavior. There are 3 ways to configure Erigon, listed by priority:

* [Command line options](/fundamentals/configuring-erigon/#command-line-options) (flags)
* [Configuration file](/fundamentals/configuring-erigon/#configuration-file)
* [Environment variables](/fundamentals/configuring-erigon/#environment-variables)

:::tip
In order to see all the available options (flags) you must run the command:

```bash
./build/bin/erigon --help
```
:::

## Command line options

Flags are passed directly to the `erigon` binary at startup. Each flag starts with `--`, followed by the flag name and, where applicable, a value separated by a space or `=`. For example, to start Erigon on the Holesky testnet with a custom data directory and the JSON-RPC API enabled on port 8545:

```bash
./build/bin/erigon --chain=holesky --datadir=/data/erigon --http --http.port=8545
```

Flags can be combined freely, providing a high degree of customization. Here's a breakdown of the most important flags:

### General Options

These flags cover the general behavior and configuration of the Erigon client.

* `--datadir value`: Specifies the data directory for the databases.
  * Default: `/home/usr/.local/share/erigon`
* `--ethash.dagdir value`: Sets the directory to store the ethash mining DAGs.
  * Default: `/home/usr/.local/share/erigon-ethash`
* `--config value`: Sets Erigon flags using a YAML/TOML file.
* `--version, -v`: Prints the version information.
* `--help, -h`: Displays help information.
* `--chain value`: Sets the name of the [network](/fundamentals/supported-networks) to join.
  * Default: `mainnet`
* `--networkid value`: Explicitly sets the network ID.
  * Default: `1`
* `--identity value`: Sets a custom node name.
* `--externalcl`: Enables the external consensus layer.
  * Default: `false`, means that Caplin is enabled.
* `--override.osaka value`: Manually specifies the Osaka fork time.
  * Default: `0`
* `--override.amsterdam value`: Manually specifies the Amsterdam fork time.
  * Default: `0`
* `--vmdebug`: Records information for VM and contract debugging.
  * Default: `false`
* `--gdbme`: Restarts Erigon under gdb for debugging.
  * Default: `false`
* `--ethstats value`: The reporting URL for an ethstats service.
* `--trusted-setup-file value`: Absolute path to a `trusted_setup.json` file.
* `--prune.include-receipts, --persist.receipts, --experiment.persist.receipts.v2`: Downloads and caches historical receipts. Without it, receipts and logs are re-derived on demand from state history, so the related RPC calls still work, just with higher latency.
  * Default: `false` (disabled) in every prune mode
* `--keep.stored.chain.config`: Avoids overriding the chain configuration already stored in the database.
  * Default: `false`

### Development, testing, and block-production helpers

These flags are mainly for dev networks, testing, or specialized block-production setups.

* `--allow-insecure-unlock`: Allows insecure account unlocking when account-related RPCs are exposed by HTTP. Use only on trusted networks.
  * Default: `false`
* `--dev-validator-seed value`: Deterministic BLS key seed for the embedded dev validator; enables PoS dev mode.
  * Default: `devnet`
* `--dev-validator-count value`: Number of validators for PoS dev mode.
  * Default: `64`
* `--dev.slot-time value`: Slot duration in seconds for PoS dev mode.
  * Default: `6`
* `--miner.gaslimit value`: Target gas limit for mined blocks.
  * Default: `0`
* `--miner.extradata value`: Block extra data set by the miner; defaults to the client version string.
  * Default: client version string
* `--experimental.bal`: Generates block access lists.
  * Default: `false`
* `--experimental.always-generate-changesets`: Overrides changeset generation logic.
  * Default: `false`
* `--chaos.monkey`: Testing-only flag that enables spontaneous network, consensus, and other failures.
  * Default: `false`

### Database and Caching

These flags control database performance and memory usage. See [Database](/fundamentals/database) for the on-disk layout.

* `--db.pagesize value`: Sets the fixed page size for the database.
  * Default: `16KB`
* `--db.size.limit value`: Sets a runtime limit on the chaindata database size.
  * Default: `1TB`
* `--db.writemap`: Enables `WRITE_MAP` for fast database writes.
  * Default: `true`
* `--db.read.concurrency value`: Maximum number of concurrent open database read transactions (the MDBX read-transaction semaphore); when it is full, extra readers wait for a slot by default, though some RPC paths (HTTP/WebSocket) fail fast with an overload response instead. Raise it for nodes serving heavy parallel RPC. Lowering it does not reduce read concurrency: each parallel-execution worker holds a long-lived read transaction, so a value below the worker count would deadlock and is silently raised to it. To genuinely reduce read concurrency, lower `--exec.workers` instead.
  * Default: scales with the host as `min(max(10, GOMAXPROCS * 64), 9000)` — kept well above the CPU count because reads are I/O-bound, and capped below Go's roughly 10,000 OS-thread limit.
* `--database.verbosity value`: Enables internal database logs.
  * Default: `2`
* `--batchSize value`: Sets the batch size for the execution stage.
  * Default: `512M`
* `--etl.bufferSize value`: Buffer size for ETL operations.
  * Default: `256MB`
* `--bodies.cache value`: Sets the size limit for the block bodies cache.
  * Default: `268435456`
* `--state.cache value`: Sets the amount of data to store in the StateCache.
  * Default: `0MB`
* `--sync.parallel-state-flushing`: Enables parallel state flushing.
  * Default: `true`
* `--erigondb.domain.steps-in-frozen-file value`: Overrides the `steps_in_frozen_file` setting from `erigondb.toml` for the domain merge cap only (history and inverted-index merges are unaffected). Pass a positive integer to set an explicit cap, or `Inf` to leave the domain merge unbounded.
  * Default: unset (uses the value from `erigondb.toml`)
  * Use with care — an incorrect value may affect database structure.
* `--commitment.plainValues` *(New in v3.6)*: On the first start of a fresh datadir, write commitment values in plain form (no shortened key references). This is a one-time, per-datadir choice — it is ignored once `erigondb.toml` exists.
  * Default: `false`

### Pruning and Snapshots

Flags for managing how old chain data is handled and stored. See [Snapshots Management](/fundamentals/snapshots-management) for snapshot tooling and disk usage.

* `--prune.mode value`: Selects a pruning preset (`full`, `archive`, `minimal`, `blocks`). See also [Pruning Modes](/fundamentals/pruning-modes)
  * Default: `"full"`
* `--prune.distance value`: Keeps state history for the latest `N` blocks, or `keep-all` to keep everything.
  * Default: unset (retention follows `--prune.mode`)
* `--prune.distance.blocks value`: Keeps block history for the latest `N` blocks, or a named policy: `keep-post-merge` (prune pre-merge blocks only) or `keep-all` (keep every block).
  * Default: unset (retention follows `--prune.mode`)
* `--prune.include-commitment-history, --prune.experimental.include-commitment-history, --experimental.commitment-history`: Enables fast `eth_getProof` for executed blocks by storing commitment history. Requires +32 GB RAM. See [`eth_getProof`](/interacting-with-erigon/eth#eth_getproof).
  * Default: `false`
* `--prune.commitment-history.distance value`: Keeps commitment history for the latest `N` blocks, or `keep-all`. Empty or `0` (default) keeps everything. Requires `--prune.include-commitment-history`.
  * Default: unset (empty / `0`, keeps everything)
* `--prune.receipts.distance, --persist.receipts.distance value`: Keeps the receipt cache for the latest `N` blocks, or `keep-all`. Empty or `0` (default) follows the state-history window. Requires `--prune.include-receipts`.
  * Default: unset (empty / `0`, follows the state-history window)
* `--snap.skip-state-snapshot-download`: Skips state download and starts from genesis.
  * Default: `false`
* `--snap.keepblocks`: Workaround/debug — keeps ancient blocks in the DB instead of moving them into snapshots (useful for debugging).
  * Default: `false`
* `--snap.stop`: Workaround for snapshot-related bugs — stops producing new snapshot files (DB will grow as a result).
  * Default: `false`
* `--snap.state.stop`: Workaround for state-related bugs — stops producing new state files (DB will grow as a result).
  * Default: `false`
* `--snap.p2p-manifest` *(New in v3.5)* (experimental): Decentralized snapshot discovery — peers advertise their `chain.toml` manifest via ENR instead of the centralized `preverified.toml`. Opt-in; requires a compatible peer network.
  * Default: `false`
* `--snap.chaintoml-url value` *(New in v3.5)*: Fetch the preverified `chain.toml` directly from this URL instead of the default R2/GitHub CDN. Precedence: the `ERIGON_REMOTE_PREVERIFIED` environment variable (path to a local override file) wins over this URL and the default CDN; a local `preverified.toml` in the datadir also takes precedence — delete it to re-fetch from the URL.
  * Default: `""` (uses the built-in CDN)
* `--snap.download.to.block, --shadow.fork.block value`: Downloads snapshots only up to the given block number (exclusive). Intended for testing and shadow forks.
  * Default: `0` (disabled — downloads all available snapshots)

### Transaction Pool (TxPool)

Options for configuring the [transaction pool](/fundamentals/modules/txpool).

* `--txpool.api.addr value`: The TxPool API network address.
  * Default: Uses the value of `--private.api.addr`
* `--txpool.disable`: Disables the internal transaction pool.
  * Default: `false`
* `--txpool.pricelimit value`: Sets the minimum gas price for acceptance into the pool.
  * Default: `1`
* `--txpool.pricebump value`: Sets the price bump percentage to replace a transaction.
  * Default: `10`
* `--txpool.blobpricebump value`: Sets the price bump percentage for replacing a type-3 blob transaction.
  * Default: `100`
* `--txpool.accountslots value`: Sets the number of executable transaction slots per account.
  * Default: `16`
* `--txpool.blobslots value`: Sets the maximum number of blobs per account.
  * Default: `540`
* `--txpool.totalblobpoollimit value`: Sets the total limit on the number of all blobs in the pool.
  * Default: `5400`
* `--txpool.globalslots value`: Sets the maximum number of executable transaction slots for all accounts.
  * Default: `10000`
* `--txpool.globalbasefeeslots value`: Sets the maximum number of non-executable transactions with insufficient base fees.
  * Default: `30000`
* `--txpool.globalqueue value`: Sets the maximum number of non-executable transaction slots for all accounts.
  * Default: `30000`
* `--txpool.trace.senders value`: A comma-separated list of addresses whose transactions will be traced.
* `--txpool.commit.every value`: Sets how often transactions are committed to storage.
  * Default: `15s`
* `--txpool.gossip.disable`: Disables P2P gossip of transactions.
  * Default: `false`
* `--txpool.queued.dormancy value`: Evicts queued transactions from senders with no on-chain state changes for at least this duration (e.g. `3h`, `2h30m`).
  * Default: `3h0m0s`
  * Set to `0` to disable dormancy-based eviction.

### Network and Peers

These flags manage network connectivity, peer discovery, and traffic control. See [Default Ports](/fundamentals/default-ports) for the full port map.

* `--port value`: The main network listening port.
  * Default: `30303`
* `--p2p.protocol value`: The version of the `eth` P2P protocol.
  * Default: `69`, `70`, `71`
* `--nat value`: The NAT port mapping mechanism (See [here](/fundamentals/nat) for more details).
* `--nodiscover`: Disables peer discovery.
  * Default: `false`
* `--discovery.v4`, `--discv4`: Enables the Node Discovery Protocol v4 (Discv4) for managed ENRs and topic discovery.
  * Default: `false` (disabled by default since v3.4; discv5 is now the default discovery protocol)
* `--discovery.v5`, `--discv5`, `--v5disc`: Enables the Node Discovery Protocol v5 (Discv5) for managed ENRs and topic discovery.
  * Default: `true` (enabled by default since v3.4)
* `--netrestrict value`: Restricts network communication to specific IP networks.
* `--nodekey value`: The P2P node key file.
* `--nodekeyhex value`: The P2P node key as a hexadecimal string.
* `--discovery.dns value`: Sets DNS discovery entry points.
* `--bootnodes value`: Comma-separated enode URLs for P2P discovery bootstrap.
* `--staticpeers value`: Comma-separated enode URLs to connect to.
* `--trustedpeers value`: Comma-separated enode URLs for trusted peers.
* `--maxpeers value`: The maximum number of network peers.
  * Default: `32`

### RPC & API

Flags for configuring various RPC servers and their behavior. See [Interacting with Erigon](/interacting-with-erigon) for the JSON-RPC API reference.

* `--private.api.addr value`: The internal gRPC API address for Erigon's components.
  * Default: `127.0.0.1:9090`
* `--private.api.ratelimit value`: Limits the number of simultaneous internal API requests.
  * Default: `31872`
* `--http`: Enables the JSON-RPC HTTP server.
  * Default: `true`
* `--http.enabled`: An alternative flag to enable the HTTP server.
  * Default: `true`
* `--graphql`: Enables the GraphQL endpoint.
  * Default: `false`
* `--http.addr value`: The HTTP-RPC server listening interface.
  * Default: `localhost`
* `--http.port value`: The HTTP-RPC server listening port.
  * Default: `8545`
* `--authrpc.addr value`: The HTTP-RPC server listening interface for the Engine API.
  * Default: `localhost`
* `--authrpc.port value`: The HTTP-RPC server listening port for the Engine API.
  * Default: `8551`
* `--authrpc.jwtsecret value`: The path to the [JWT secret](/fundamentals/jwt) file for the consensus layer.
* `--http.compression`: Enables compression over HTTP-RPC.
  * Default: `true`
* `--http.corsdomain value`: A comma-separated list of domains for cross-origin requests.
* `--http.vhosts value`: A comma-separated list of virtual hostnames.
  * Default: `localhost`
* `--authrpc.vhosts value`: A comma-separated list of virtual hostnames for the Engine API.
  * Default: `localhost`
* `--http.api value`: The APIs offered over the HTTP-RPC interface.
  * Default: `eth,erigon,engine`
* `--ws`: Enables the WS-RPC server.
  * Default: `false`
* `--ws.port value`: The WS-RPC server listening port.
  * Default: `8546`
* `--ws.compression`: Enables compression over WebSocket.
  * Default: `true`
* `--ws.max.connections value`: Maximum number of concurrent WebSocket connections.
  * Default: `0` (unlimited)
* `--rpc.batch.concurrency value`: Limits the number of goroutines for batch requests.
  * Default: `2`
* `--rpc.max.concurrency value`: Maximum number of concurrent HTTP RPC requests (HTTP admission control).
  * Default: `0` (inherits value from `--db.read.concurrency`)
  * Set to `-1` to disable admission control (unlimited)
* `--rpc.streaming.disable`: Disables JSON streaming for heavy endpoints.
  * Default: `false`
* `--state.stream.disable`: Disables streaming of state changes from the core to the RPC daemon.
  * Default: `false`
* `--rpc.accessList value`: Specifies a granular API allowlist.
* `--rpc.gascap value`: Sets a cap on gas usage for `eth_call`/`estimateGas`.
  * Default: `50000000`
* `--rpc.batch.limit value`: Sets the maximum number of requests in a batch.
  * Default: `100`
* `--rpc.blockrange.limit value`: Sets the maximum block range for `eth_getLogs` and similar range queries.
  * Default: `1000`
  * Applies to: `eth_getLogs`, `erigon_getLogs`
* `--rpc.logs.maxresults value`: Sets the maximum number of log results returned per query.
  * Default: `20000`
  * Applies to: `eth_getLogs`, `erigon_getLogs`, `erigon_getLatestLogs`
  * Set to `0` to remove the limit entirely (use with caution on large ranges).
  * Works in tandem with `--rpc.blockrange.limit`: both constraints apply independently — a query can be blocked by either limit.
* `--rpc.logs.querylimit value`: Maximum number of alternative addresses or topics allowed per search position in the `eth_getLogs` filter criteria.
  * Default: `1000`
  * Applies to: `eth_getLogs`
  * Set to `0` or a negative value for no limit.
* `--rpc.returndata.limit value`: Sets the maximum return data size for `eth_call`.
  * Default: `100000`
* `--rpc.allow-unprotected-txs`: Allows unprotected transactions via RPC.
  * Default: `false`
* `--rpc.gethcompat`: Enables Geth-compatible storage iteration order for `debug_storageRangeAt` (results sorted by keccak256 hash). Disabled by default for performance.
  * Default: `false`
* `--rpc.txfeecap value`: Sets a cap on transaction fees in ether.
  * Default: `1`
* `--rpc.slow value`: Logs RPC requests slower than the specified threshold.
  * Default: `0s`
* `--rpc.evmtimeout value`: The maximum time to wait for an EVM call.
  * Default: `5m0s`
* `--rpc.overlay.getlogstimeout value`: The maximum time to wait for `overlay_getLogs`.
  * Default: `5m0s`
* `--rpc.overlay.replayblocktimeout value`: The maximum time to wait to replay a single block.
  * Default: `10s`
* `--rpc.txsync.defaulttimeout value`: The default timeout for `eth_sendRawTransactionSync` when the caller does not specify one.
  * Default: `25s`
* `--rpc.txsync.maxtimeout value`: The maximum timeout for `eth_sendRawTransactionSync`; larger requested timeouts are clamped to this value.
  * Default: `1m0s`
* `--rpc.subscription.filters.maxlogs value`: Maximum logs to store per subscription.
  * Default: `10000`
* `--rpc.subscription.filters.maxheaders value`: Maximum block headers to store per subscription.
  * Default: `10000`
* `--rpc.subscription.filters.maxtxs value`: Maximum transactions to store per subscription.
  * Default: `10000`
* `--rpc.subscription.filters.maxaddresses value`: Maximum addresses per subscription to filter logs by.
  * Default: `0`
* `--rpc.subscription.filters.maxtopics value`: Maximum topics per subscription to filter logs by.
  * Default: `0`
* `--rpc.subscription.filters.timeout value`: Timeout before idle subscription filters are evicted.
  * Default: `5m0s`
  * Set to `0` to disable eviction.
* `--http.timeouts.read value`: Maximum duration for reading a request.
  * Default: `30s`
* `--http.timeouts.write value`: Maximum duration before timing out a response write.
  * Default: `30m0s`
* `--http.timeouts.idle value`: Maximum idle time for a connection with keep-alives enabled.
  * Default: `2m0s`
* `--authrpc.timeouts.read value`: Maximum read duration for an Engine API request.
  * Default: `30s`
* `--authrpc.timeouts.write value`: Maximum write duration for an Engine API response.
  * Default: `30m0s`
* `--authrpc.timeouts.idle value`: Maximum idle time for an Engine API connection.
  * Default: `2m0s`
* `--healthcheck`: Enables gRPC health checks.
  * Default: `false`
* `--witness.cache.blocks value` *(New in v3.6)*: Number of recent blocks whose legacy `debug_executionWitness` result is eagerly cached in memory, keyed by block hash in an LRU. Each witness is held as serialized JSON and served verbatim on a hit, so memory use is roughly this count multiplied by the per-block witness size. Embedded RPC only, and requires `--prune.include-commitment-history` (runtime errors from `debug_executionWitness` and `eth_getWitness` name its `--prune.experimental.include-commitment-history` alias instead). This flag also gates `debug_subscribe("executionWitnesses")`, which pushes each witness over WebSocket as the cache builds it. That stream is best-effort rather than contiguous — catch-up bursts, skipped or failed builds, and slow subscribers all leave gaps — so a client that needs every height re-requests the missing ones with `debug_executionWitness`.
  * Default: `0` (cache disabled); values above the cap of `96` are clamped
* `--witness.cache.head-capture`: Serves recent-block `debug_executionWitness` on a minimal node without commitment-history by building each head block from a pinned parent commitment snapshot and the account/storage/code history the node keeps. Cache-only serving: out-of-window requests miss, and no history recompute is attempted. Embedded RPC only.
  * Default: `false`
* `--witness.cache.maxmb value`: Resident-memory cap, in MB, for the witness cache; whichever limit binds first wins between the byte budget and `--witness.cache.blocks` (still capped at `96`). `0` means count-only (no byte cap).
  * Default: `0`

### MCP Server

Flags for configuring the Model Context Protocol (MCP) server. The embedded [MCP server](/fundamentals/mcp) is **enabled by default** on
`127.0.0.1:8553`. Pass `--mcp.disable` to turn it off.

* `--mcp.disable`: Disables the embedded MCP server.
    * Default: `false`
* `--mcp.addr value`: The MCP server listening address.
  * Default: `127.0.0.1`
* `--mcp.port value`: The MCP server listening port.
  * Default: `8553`

### Logging and Profiling

Flags for controlling logging and performance profiling. See [Logs](/fundamentals/logs) for log files, levels, and rotation.

* `--log.json`: Formats console logs with JSON.
  * Default: `false`
* `--log.console.json`: Formats console logs with JSON.
  * Default: `false`
* `--log.dir.json`: Formats file logs with JSON.
  * Default: `false`
* `--verbosity value`: Sets the log level for console logs.
  * Default: `info`
* `--log.console.verbosity value`: Sets the log level for console logs.
  * Default: `info`
* `--log.dir.disable`: Disables disk logging.
  * Default: `false`
* `--log.dir.path value`: The path to store user and error logs.
* `--log.dir.prefix value`: The file name prefix for logs stored on disk.
* `--log.dir.verbosity value`: Sets the log verbosity for disk logs.
  * Default: `dbug`
* `--log.delays`: Enables block delay logging.
  * Default: `false`
* `--pprof`: Enables the pprof HTTP server.
  * Default: `false`
* `--pprof.addr value`: The pprof HTTP server listening interface.
  * Default: `127.0.0.1`
* `--pprof.port value`: The pprof HTTP server listening port.
  * Default: `6060`
* `--pprof.cpuprofile value`: Writes a CPU profile to a file.
* `--trace value`: Writes an execution trace to a file.
* `--vmtrace value`: Sets the provider tracer.
* `--vmtrace.jsonconfig value`: Sets the tracer's configuration.
* `--metrics`: Enables metrics collection and reporting. See [Creating a dashboard](/fundamentals/creating-a-dashboard).
  * Default: `false`
* `--metrics.addr value`: The stand-alone metrics HTTP server listening interface.
  * Default: `127.0.0.1`
* `--metrics.port value`: The metrics HTTP server listening port.
  * Default: `6061`

### Consensus and Forks

Flags related to consensus mechanisms and network forks.

* `--fakepow`: Disables proof-of-work verification.
  * Default: `false`
* `--gpo.blocks value`: The number of recent blocks to check for gas prices.
  * Default: `20`
* `--gpo.percentile value`: The percentile of recent transaction gas prices to use for a suggested gas price.
  * Default: `60`
* `--proposer.disable`: Disables the PoS proposer.
  * Default: `false`
* `--builder.maxblobs value`: Caps the number of blobs included in a locally built block.
  * Default: unset — the protocol maximum applies. Setting it to `0` excludes blob transactions from built blocks entirely.
* `--bor.heimdall value`: The URL of the Heimdall service.
  * Default: `http://localhost:1317`
* `--bor.withoutheimdall`: Runs without the Heimdall service.
  * Default: `false`
* `--bor.period`: Overrides the bor block period.
  * Default: `false`
* `--bor.minblocksize`: Ignores the bor block period and waits for `blocksize` transactions.
  * Default: `false`
* `--polygon.pos.ssf`: Enables Polygon PoS Single Slot Finality.
  * Default: `false`
* `--polygon.pos.ssf.block value`: Enables Polygon PoS Single Slot Finality from a specific block.
  * Default: `0`
* `--polygon.wit-protocol`: Enables the WIT protocol (`wit/0`) for stateless witness data exchange. Primarily useful on Bor (Polygon) chains — the witness buffer is only populated there — and must be set explicitly.
  * Default: `false`

### Sentry

Flags for configuring the [Sentry](/fundamentals/modules/sentry) component.

* `--sentry.api.addr value`: A comma-separated list of Sentry addresses.
* `--sentry.log-peer-info`: Logs detailed peer info when a peer connects or disconnects.
  * Default: `false`
* `--sentinel.addr value`: The address for the sentinel component.
  * Default: `localhost`
* `--sentinel.port value`: The port for the sentinel component.
  * Default: `7777`
* `--sentinel.bootnodes value`: Comma-separated enode URLs for P2P discovery bootstrap for the sentinel.
* `--sentinel.staticpeers value`: Connects to comma-separated consensus static peers.

### Downloader and Synchronization

These flags control the block synchronization and data downloading process, including the BitTorrent protocol settings. See [Downloader](/fundamentals/modules/downloader) for how snapshot downloading works.

* `--downloader.api.addr value`: The Downloader address.
* `--downloader.disable.ipv4`: Disables IPv4 for the Downloader.
  * Default: `false`
* `--downloader.disable.ipv6`: Disables IPv6 for the Downloader.
  * Default: `false`
* `--no-downloader`: Disables the Downloader component.
  * Default: `false`
* `--downloader.verify`: Verifies snapshots on startup.
  * Default: `false`
* `--sync.loop.throttle value`: Sets the minimum time between sync loop starts.
* `--sync.loop.block.limit value`: Sets the maximum number of blocks to process per loop iteration.
  * Default: `5000`
* `--sync.loop.break.after value`: Sets the last stage of the sync loop to run.
* `--bad.block value`: Marks a block as bad and forces a reorg.
* `--webseed value`: Comma-separated URLs for network support infrastructure.

#### BitTorrent Options

* `--torrent.port value`: The port to listen for the BitTorrent protocol.
  * Default: `42069`
* `--torrent.maxpeers value`: An unused parameter.
  * Default: `100`
* `--torrent.conns.perfile value`: The number of connections per file.
  * Default: `10`
* `--torrent.trackers.disable`: Disables conventional BitTorrent trackers.
  * Default: `false`
* `--torrent.upload.rate value`: The upload rate in bytes per second.
  * Default: `16mb`
* `--torrent.download.rate value`: Sets the torrent download rate cap. Default: `512mb`. Use a lower value on shared machines to avoid saturating the connection; use `Inf` to remove the limit.
* `--torrent.webseed.download.rate value`: The download rate for webseeds. If not set, rate limit is shared with torrent.
* `--torrent.verbosity value`: Sets the verbosity level for BitTorrent logs. 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail (must set `--verbosity` to equal or higher level)
  * Default: `1`

### Fork Choice Update (FCU)

Flags for configuring Fork Choice Update behavior.

* `--fcu.timeout value`: FCU timeout before switching to async processing (use `0` to disable).
  * Default: `1s`
* `--fcu.background.prune`: Enables background pruning after FCU.
  * Default: `true`
* `--fcu.background.commit`: Enables background flush and commit after FCU.
  * Default: `false`

### Execution

Flags for configuring the parallel block execution engine.

**All `--exec.*` flags are new in v3.5** — they expose, as CLI flags, execution toggles that on earlier releases were settable only via the `EXEC3_*` / `NO_*` environment variables (which still work).

* `--exec.workers value`: Number of parallel block-execution workers (equivalent to the `EXEC3_WORKERS` env var). Overridden by `--exec.serial`.
  * Default: the number of CPU cores (inherited from the `EXEC3_WORKERS` default when the flag is not set).
  * Note: `erigon --help` describes this flag's default as "half the number of CPU cores". That value is not actually applied — when `--exec.workers` is omitted, Erigon uses `EXEC3_WORKERS`, which defaults to the full CPU-core count. The flag-help text is a known inconsistency in the binary.
* `--exec.serial`: Force serial execution by clamping the parallel executor to a single worker. Wins over `--exec.workers` and `EXEC3_WORKERS` — use to disable parallelism for diagnostics or like-for-like baseline comparisons.
  * Default: `false`
* `--exec.no-prune`: Disable all DB pruning: state-aggregator (Domain/InvertedIndex) plus stage-level pruning (Execution: ChangeSets3/BlockAccessList; TxLookup; WitnessProcessing; Snapshots: PruneAncientBlocks/canonical markers/retirement). Equivalent to `NO_PRUNE=true`. Diagnostic / perf-comparison use only.
  * Default: `false`
* `--exec.no-merge`: Disable state-aggregator file merges for Domain / History / Inverted-Index. Equivalent to `NO_MERGE=true`. Diagnostic / perf-comparison use only.
  * Default: `false`
* `--exec.no-background-maintenance`: Suppress background state-aggregator and E2 block-snapshot retirement goroutines so execution is not perturbed by housekeeping work. Equivalent to `NO_BACKGROUND_E3_BUILD=true`. Diagnostic / focused-performance-testing use only — NOT an operational setting.
  * Default: `false`
* `--exec.batched-io`: Enable BAL-driven I/O optimisations — read-ahead pre-warming of the DB page cache (`READ_AHEAD=true`) and version-map pre-population from BAL hints (`IGNORE_BAL=false`). Disable for cold-read or non-BAL scheduling performance measurements.
  * Default: `true`
* `--exec.state-cache`: Enable the executor's domain-shared read cache. Equivalent to `USE_STATE_CACHE=true`. Disable for cold-read performance measurements.
  * Default: `true`

**Commitment-trie construction.** The following flags change how the commitment (state-root) trie is computed during execution. Both default off and are intended for comparing root hashes against a sequential sync before enabling broadly.

* `--experimental.parallel-commitment` *(New in v3.6)* (experimental): Compute the commitment trie with the fully parallel `ParallelPatriciaHashed` implementation. Equivalent to the `COMMITMENT_PARALLEL=true` environment variable.
  * Default: `false`
* `--experimental.streaming-commitment` *(New in v3.6)* (experimental): Compute the commitment trie with the `StreamingCommitter`, which overlaps trie folding with block execution. If set, takes precedence over `--experimental.parallel-commitment`. No environment-variable equivalent.
  * Default: `false`

### Caplin (Consensus Layer)

Flags for configuring the [Caplin](/fundamentals/caplin) consensus layer.

* `--caplin.discovery.addr value`: The address for the Caplin DISCV5 protocol.
  * Default: `0.0.0.0`
* `--caplin.discovery.port value`: The port for the Caplin DISCV5 protocol.
  * Default: `4000`
* `--caplin.discovery.tcpport value`: The TCP port for the Caplin DISCV5 protocol.
  * Default: `4001`
* `--caplin.checkpoint-sync-url value`: The checkpoint sync endpoint.
* `--caplin.subscribe-all-topics`: Subscribes to all gossip topics.
  * Default: `false`
* `--caplin.max-peer-count value`: The maximum number of peers to connect to.
  * Default: `128`
* `--caplin.enable-upnp`: Enables NAT porting for Caplin.
  * Default: `false`
* `--caplin.local-discovery`: Also attempts to find peers over private IPs. May cause issues with some hosts (for example, Hetzner).
  * Default: `false`
* `--caplin.nat value`: NAT port mapping for Caplin P2P. Sets the external IP advertised in the discv5 ENR and libp2p multiaddrs while the socket binds to `--caplin.discovery.addr`. Required when running inside Docker or behind NAT. Accepted values: `""` (none), `"extip:1.2.3.4"`, `"stun"`, `"stun:<host>"`, `"upnp"`, `"pmp"`, `"pmp:192.168.0.1"`.
  * Default: `""` (no NAT mapping)
* `--caplin.max-inbound-traffic-per-peer value`: The maximum inbound traffic per second per peer.
  * Default: `1MB`
* `--caplin.max-outbound-traffic-per-peer value`: The maximum outbound traffic per second per peer.
  * Default: `1MB`
* `--caplin.adaptable-maximum-traffic-requirements`: Makes the node adaptable to traffic based on the number of validators.
  * Default: `true`
* `--caplin.blocks-archive`: Enables backfilling for blocks.
  * Default: `false`
* `--caplin.blobs-archive`: Enables backfilling for blobs.
  * Default: `false`
* `--caplin.states-archive`: Enables the archival node for historical states.
  * Default: `false`
* `--caplin.blobs-immediate-backfill`: Tells Caplin to immediately backfill blobs.
  * Default: `false`
* `--caplin.blobs-no-pruning`: Disables blob pruning.
  * Default: `false`
* `--caplin.columns-keep-slots value`: Number of slots to retain PeerDAS data column sidecars. Increase for DA oracle or rollup nodes that need longer column history.
  * Default: `131072` (~18 days)
* `--caplin.checkpoint-sync.disable`: Disables checkpoint sync.
  * Default: `false`
* `--caplin.resume-max-staleness-epochs value`: Max epochs a locally-finalized state may be stale for Caplin to resume from it on restart instead of remote checkpoint syncing. Data-availability bound; larger values are clamped to the anchor fork's sidecar-retention window.
  * Default: `0` (resolves to the anchor fork's sidecar-retention window)
* `--caplin.snapgen`: Enables snapshot generation.
  * Default: `false`
* `--caplin.mev-relay-url value`: The MEV relay endpoint.
* `--caplin.validator-monitor`: Enables Caplin validator monitoring metrics.
  * Default: `false`
* `--caplin.custom-config value`: Sets a custom config for Caplin.
* `--caplin.custom-genesis value`: Sets a custom genesis for Caplin.
* `--caplin.use-engine-api`: Uses the Engine API for internal Caplin.
  * Default: `false`
* `--beacon.api.read.timeout value`: HTTP read timeout for the Beacon API server, in seconds.
  * Default: `5`
* `--beacon.api.write.timeout value`: HTTP write timeout for the Beacon API server, in seconds.
  * Default: `31536000` (~1 year)
* `--beacon.api.idle.timeout value`: HTTP idle (keep-alive) timeout for the Beacon API server, in seconds.
  * Default: `25`

### Shutter Network Encrypted Transactions

Flags for configuring the [Shutter Network](/staking/shutter-network) encrypted transactions mempool.

* `--shutter`: Enables the Shutter encrypted transactions mempool.
  * Default: `false`
* `--shutter.p2p.bootstrap.nodes value`: Overrides the default P2P bootstrap nodes.
* `--shutter.p2p.listen.port value`: Overrides the default P2P listen port.
  * Default: `0`

## Configuration file

You can configure Erigon using a YAML or TOML configuration file by specifying its path with the `--config` flag.

:::tip
**Note**: flags specified in the configuration file can be overridden by directly setting them in the Erigon command line.
:::

Both in YAML and TOML files boolean operators (`false`, `true`) and strings without spaces can be specified without quotes, while strings with spaces must be included in `""` or `''` quotes.

### YAML

Use the `--config` flag to point at the YAML configuration file.

```bash
./build/bin/erigon --config ./config.yaml --chain=holesky
```

Example of a YAML config file:

```yaml
datadir : 'your datadir'
chain : "mainnet"
http : true
http.api : ["eth","debug","net"]
```

In this case the `--chain` flag in the command line will override the value in the YAML file and Erigon will run on the Holesky testnet.

### TOML

Use the `--config` flag to point at the TOML configuration file.

```bash
./build/bin/erigon --config ./config.toml
```

Example of a TOML config file:

```toml
datadir = 'your datadir'
chain = "mainnet"
http = true
"http.api" = ["eth","debug","net"]
```

## Environment variables

Erigon supports configuration through environment variables, primarily for experimental features and advanced settings.

### Core Environment Variables

**Database and Performance:**

* `MDBX_LOCK_IN_RAM` - Locks MDBX database in RAM for better performance
* `MDBX_DIRTY_SPACE_MB` - Sets dirty space limit for MDBX database
* `SNAPSHOT_MADV_RND` - Controls snapshot memory advice randomization (default: `true`)

**Synchronization and Pruning:**

* `NO_PRUNE` - Disables pruning when set to true (flag equivalent: `--exec.no-prune`)
* `NO_MERGE` - Disables merging operations (flag equivalent: `--exec.no-merge`)
* `PRUNE_TOTAL_DIFFICULTY` - Controls total difficulty pruning (default: `true`)
* `MAX_REORG_DEPTH` - Sets maximum reorganization depth (default: `96`)
* `CAPLIN_STATE_PRUNE_DISABLE` - Disables pruning of Caplin's state indexing DB after ranges are frozen into snapshots (default: `false`)
* `CAPLIN_STATE_PRUNE_TIMEOUT` - Overrides the per-pass time budget for Caplin state pruning (a duration, e.g. `500ms`; default derived from the chain's slot time)

**Execution and Processing:**

* `EXEC3_PARALLEL` - Enables parallel block execution (Block-STM). **Default changed to `true` in v3.5** — parallel execution is now on by default. Set to `false` or use `--exec.serial` to revert to single-threaded execution.
* `EXEC3_WORKERS` - Sets number of parallel execution workers (default: number of CPU cores)
* `STAGES_ONLY_BLOCKS` - Limits stages to blocks only

### Memory and Debugging Variables

**Memory Management:**

* `NO_MEMSTAT` - Disables memory statistics collection
* `SAVE_HEAP_PROFILE` - Enables automatic heap profiling
* `HEAP_PROFILE_THRESHOLD` - Memory usage percentage threshold for heap profiling (default: 35%)

**Tracing and Debugging:**

* `TRACE_ACCOUNTS` - Comma-separated list of accounts to trace
* `TRACE_BLOCKS` - Comma-separated list of block numbers to trace
* `TRACE_INSTRUCTIONS` - Enables instruction-level tracing

### Docker Environment Variables

When running Erigon in [Docker](/fundamentals/docker-compose), you can configure user permissions and data directories:

* `DOCKER_UID` - The UID of the Docker user
* `DOCKER_GID` - The GID of the Docker user
* `XDG_DATA_HOME` - The data directory mounted to containers

### Usage Examples

**Basic Performance Tuning:**

```bash
export MDBX_LOCK_IN_RAM=true
export SNAPSHOT_MADV_RND=false
./build/bin/erigon --datadir=/path/to/data
```

**Memory Debugging:**

```bash
export SAVE_HEAP_PROFILE=true
export HEAP_PROFILE_THRESHOLD=45
./build/bin/erigon --datadir=/path/to/data
```

**Docker Deployment:**

```bash
export DOCKER_UID=$(id -u)
export DOCKER_GID=$(id -g)
export XDG_DATA_HOME=/preferred/data/folder
make docker-compose
```
