Geth_cli

Chapter 8: Geth CLI Options & Flags

Overview

This chapter provides a comprehensive reference of Geth command-line options. Understanding these flags is essential for configuring and optimizing your Ethereum node.

---

8.1 Common Flags Reference

Network & Sync Options

Flag	Description	Example
--networkid	Network identifier	--networkid 1 (mainnet)
--syncmode	Sync mode: full, snap, light	--syncmode snap
--snap	Enable snap sync (deprecated, use syncmode)
--light.serve	Serve light clients	--light.serve 100
--light.maxpeers	Max light client peers	--light.maxpeers 80

Network IDs

Network	Chain ID	Network ID
Ethereum Mainnet	1	1
Sepolia	11155111	11155111
Goerli	5	5
Holesky	17000	17000
Private Testnet	Custom	Custom

---

8.2 HTTP/RPC Options

┌─────────────────────────────────────────────────────────────────────────────┐
│                         HTTP/RPC CONFIGURATION                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                         HTTP SERVER                                 │    │
│  │                                                                       │    │
│  │  --http                  Enable HTTP server                         │    │
│  │  --http.addr             Bind address (default: localhost)         │    │
│  │  --http.port             Port (default: 8545)                       │    │
│  │  --http.api              Enabled APIs                               │    │
│  │  --http.vhosts           Virtual hostnames (comma-separated)       │    │
│  │  --http.corsdomain       CORS domains                               │    │
│  │  --http.ratelimit        Rate limit (requests/sec)                 │    │
│  │  --http.ratelimitburst   Rate limit burst                          │    │
│  │                                                                       │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                       WEBSOCKET SERVER                               │    │
│  │                                                                       │    │
│  │  --ws                    Enable WebSocket server                   │    │
│  │  --ws.addr               Bind address                               │    │
│  │  --ws.port                Port (default: 8546)                      │    │
│  │  --ws.api                Enabled APIs                               │    │
│  │  --ws.origins            Allowed origins                            │    │
│  │  --ws.ratelimit          Rate limit (requests/sec)                 │    │
│  │  --ws.extradataprefix    Extra data prefix                         │    │
│  │                                                                       │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

API Namespaces

Namespace	Description
eth	Ethereum API (blocks, transactions, accounts)
net	Network status
web3	Web3 utilities
debug	Debugging & tracing APIs
txpool	Transaction pool information
erigon	Erigon-specific APIs
trace	Transaction tracing

Example: Configure HTTP API

geth \
  --http \
  --http.addr 0.0.0.0 \
  --http.port 8545 \
  --http.api eth,net,web3,debug,txpool \
  --http.vhosts "localhost,yourdomain.com" \
  --http.corsdomain "https://your-dapp.com"

---

8.3 Data & Storage Options

Data Directory

Flag	Description
--datadir	Path to database and keystore
--keystore	Path to keystore (default: datadir/keystore)
--config	Path to config file (TOML)

Database Options

# Database cache settings
--cache 4096              # Memory cache in MB
--database.engine pebbledb # Database engine (leveldb/pebbledb)

# State pruning
--pruneancientstore       # Prune ancient data after merge

# State history
--history.state 90000    # Number of state entries to keep
--history.transactions 90000  # Number of tx entries to keep

Storage Requirements

Mode	Storage (Mainnet)
Full (pruned)	~1.2 TB
Snap (pruned)	~1.2 TB
Archive	~12 TB

---

8.4 P2P Networking Options

Connection Settings

Flag	Description	Default
--port	P2P listening port	30303
--maxpeers	Maximum peer count	50
--maxpendpeers	Maximum pending connections	0
--nat	NAT traversal	any

Peer Discovery

# Bootnodes
--bootnodes enode://enr:...@bootnode1.example.com:30303

# Static peers
--staticnodes enode://...@peer1.example.com:30303

# Disable discovery (for private networks)
--nodiscover

# V5 discovery
--v5disc

Public Bootnodes

Mainnet:

--bootnodes "enr:-KG4QOtcL ... @bootnode.mainnet.ethdisco.net:30303"

Sepolia:

--bootnodes "enr:-KG4QOtcL ... @bootnode.sepolia.ethdisco.net:30303"

---

8.5 Transaction Pool Options

TxPool Configuration

┌─────────────────────────────────────────────────────────────────┐
│                    TRANSACTION POOL                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Pending Queue (Global Slots)                                    │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                                                           │  │
│  │  Default: 4096 slots                                    │  │
│  │  Flag: --txpool.globalslots 4096                        │  │
│  │                                                           │  │
│  └─────────────────────────────────────────────────────────┘  │
│                              │                                   │
│                              ▼                                   │
│  Queued Transactions (Global Queue)                             │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                                                           │  │
│  │  Default: 1024 queue                                    │  │
│  │  Flag: --txpool.globalqueue 1024                       │  │
│  │                                                           │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                                  │
│  Per-Account Limits:                                             │
│  - slots: 16 (default)                                         │
│  - queue: 64 (default)                                         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

TxPool Flags

Flag	Description	Default
--txpool.locals	Comma-separated accounts to prioritize
--txpool.nolocals	Disable local account prioritization
--txpool.price Limit	Minimum gas price	1 Gwei
--txpool.accountqueue	Max transactions per account queue	64
--txpool.accountslots	Max transactions per account pending	16

---

8.6 Gas & Miner Options

Miner Configuration

Flag	Description
--mine	Enable mining
--miner.threads	Number of mining threads
--miner.etherbase	Coinbase address for mining rewards
--miner.extradata	Extra data for mined blocks
--miner.gasprice	Minimum gas price for transactions
--miner.gaslimit	Block gas limit

Gas Price Settings

# Set minimum gas price for mining
geth --mine --miner.etherbase 0x... --miner.gasprice 20000000000

---

8.7 Logging & Debugging Options

Log Configuration

Flag	Description
--verbosity	Log level (0-6)
--vmodule	Per-module log level
--log.json	JSON logging format
--log.file	Log file path

Log Levels

Level	Description
0	Critical
1	Error
2	Warning
3	Info (default)
4	Debug
5	Trace

Examples

# Set verbosity to debug
--verbosity 4

# Debug only p2p module
--vmodule p2p=4,eth=3

# Log to file
--log.file /var/log/geth.log

# JSON logging
--log.json

---

8.8 Metrics & Profiling

Prometheus Metrics

# Enable metrics
--metrics

# Enable metrics server
--metrics.addr 0.0.0.0
--metrics.port 6060

# Custom metrics prefix
--metrics.prefix eth

Metrics Endpoints

Endpoint	Description
/debug/metrics	Prometheus metrics
/debug/metrics/prometheus	Prometheus format
/debug/pprof	pprof UI

pprof Profiling

# Enable pprof
--pprof

# pprof address
--pprof.addr 0.0.0.0
--pprof.port 6061

Access pprof

# Get heap profile
curl http://localhost:6061/debug/pprof/heap > heap.out

# CPU profile
curl http://localhost:6061/debug/pprof/profile > cpu.out

# View trace
go tool pprof http://localhost:6061/debug/pprof/trace

---

8.9 Configuration File

TOML Configuration

Create config.toml:

[Eth]
SyncMode = "snap"
NetworkId = 1

[Eth.TxPool]
Locals = ["0x742d35Cc6634C0532925a3b844Bc9e7595f1e3E4"]
NoLocals = false
Journal = "transactions.rlp"
Rejournal = 3600000000000

[Node]
DataDir = "/data/ethereum"
HTTPHost = "0.0.0.0"
HTTPPort = 8545
HTTPVirtualHosts = ["*"]
HTTPModules = ["eth", "net", "web3", "debug", "txpool"]

WSHost = "0.0.0.0"
WSPort = 8546
WSModules = ["eth", "net", "web3", "debug", "txpool"]

P2P = {
  MaxPeers = 100,
  Port = 30303,
}

[Metrics]
Enabled = true
Addr = "0.0.0.0"
Port = 6060

Using Config File

geth --config /path/to/config.toml

---

8.10 Complete Example

Production RPC Node

geth \
  --config /etc/geth/config.toml \
  --syncmode snap \
  --http \
  --http.addr "0.0.0.0" \
  --http.port 8545 \
  --http.api "eth,net,web3,debug,txpool" \
  --http.vhosts "*" \
  --http.corsdomain "*" \
  --ws \
  --ws.addr "0.0.0.0" \
  --ws.port 8546 \
  --ws.api "eth,net,web3,debug,txpool" \
  --ws.origins "*" \
  --datadir /data/ethereum \
  --port 30303 \
  --maxpeers 100 \
  --cache 8192 \
  --txpool.globalslots 8192 \
  --txpool.globalqueue 2048 \
  --metrics \
  --metrics.addr "0.0.0.0" \
  --metrics.port 6060 \
  --pprof \
  --pprof.addr "0.0.0.0" \
  --pprof.port 6061

---

8.11 Interview Questions

Question	Answer
What is the default HTTP port?	8545
What is the default P2P port?	30303
How to enable debug APIs?	--http.api eth,net,web3,debug
What does --cache flag do?	Sets memory cache in MB

---

Summary

• Geth has extensive CLI options for all configurations
• Key areas: HTTP/WS APIs, P2P networking, database, txpool
• Use TOML config file for complex setups
• Enable metrics for monitoring

---

Next Chapter

In Chapter 9: Erigon Client - High-Performance Ethereum, we’ll explore alternative Ethereum clients.

---

Last Updated: 2026-02-20