From 10d0305b5ec6b06ac42144ae28f947f44300e699 Mon Sep 17 00:00:00 2001 From: Georgios Konstantopoulos Date: Fri, 5 May 2023 18:46:39 -0700 Subject: [PATCH] docs: add cli reference (#2589) --- book/cli/cli.md | 92 +++++++++++++++++++ book/cli/db.md | 115 +++++++++++++++++++++++- book/cli/drop-stage.md | 72 +++++++++++++++ book/cli/dump-stage.md | 83 ++++++++++++++++- book/cli/node.md | 200 ++++++++++++++++++++++++++++++++++++++++- book/cli/p2p.md | 154 ++++++++++++++++++++++++++++++- book/cli/stage.md | 135 +++++++++++++++++++++++++++- 7 files changed, 846 insertions(+), 5 deletions(-) diff --git a/book/cli/cli.md b/book/cli/cli.md index c31a0bc93..3e17dd3e3 100644 --- a/book/cli/cli.md +++ b/book/cli/cli.md @@ -1 +1,93 @@ # CLI Reference + +The Reth node is operated via the CLI by running the `reth node` command. To stop it, press `ctrl-c`. You may need to wait a bit as Reth tears down existing p2p connections or other cleanup tasks. + +However, Reth has more commands than that: + +```bash +reth --help +``` + +Some of the most useful commands as a node developer are: +* [`reth node`](./node.md): Starts the Reth node's components, including the JSON-RPC. +* [`reth db`](./db.md): Administrative TUI to the key-value store +* [`reth p2p`](./p2p.md): P2P-related utilities +* [`reth stage`](./stage.md): Runs a stage in isolation. Useful for testing and benchmarking. +* [`reth drop-stage`](./drop-stage.md): Drops all the tables associated with a stage. Useful for resetting state. +* [`reth dump-stage`](./dump-stage.md): Dumps all the tables associated with a stage to a new database. Useful for creating snapshots + +See below for the full list of commands. + +## Commands + +```bash +$ reth --help +Reth + +Usage: reth [OPTIONS] + +Commands: + node + Start the node + init + Initialize the database from a genesis file + import + This syncs RLP encoded blocks from a file + db + Database debugging utilities + stage + Run a single stage + dump-stage + Dumps a stage from a range into a new database + drop-stage + Drops a stage's tables from the database + p2p + P2P Debugging utilities + test-chain + Run Ethereum blockchain tests + test-vectors + Generate Test Vectors + config + Write config to stdout + merkle-debug + Debug state root calculation + help + Print this message or the help of the given subcommand(s) + +Options: + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version + +Logging: + --log.persistent + The flag to enable persistent logs + + --log.directory + The path to put log files in + + [default: /Users/georgios/Library/Caches/reth/logs] + + --log.journald + Log events to journald + + --log.filter + The filter to use for logs written to the log file + + [default: debug] + +Display: + -v, --verbosity... + Set the minimum log level. + + -v Errors + -vv Warnings + -vvv Info + -vvvv Debug + -vvvvv Traces (warning: very verbose!) + + -q, --quiet + Silence all log output +``` diff --git a/book/cli/db.md b/book/cli/db.md index 8ce65ded2..aa9068e17 100644 --- a/book/cli/db.md +++ b/book/cli/db.md @@ -1 +1,114 @@ -# reth db +# `reth db` + +Database debugging utilities + +```bash +$ reth db --help + +Usage: reth db [OPTIONS] + +Commands: + stats + Lists all the tables, their entry count and their size + list + Lists the contents of a table + seed + Seeds the database with random blocks on top of each other + drop + Deletes all database entries + help + Print this message or the help of the given subcommand(s) + +Options: + --datadir + The path to the data dir for all reth files and subdirectories. + + Defaults to the OS-specific data directory: + + - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/` + - Windows: `{FOLDERID_RoamingAppData}/reth/` + - macOS: `$HOME/Library/Application Support/reth/` + + [default: default] + + --db + The path to the database folder. If not specified, it will be set in the data dir for the + chain being used. + + --chain + The chain this node is running. + + Possible values are either a built-in chain or the path to a chain specification file. + + Built-in chains: + - mainnet + - goerli + - sepolia + + [default: mainnet] + + -h, --help + Print help (see a summary with '-h') + +Display: + -v, --verbosity... + Set the minimum log level. + + -v Errors + -vv Warnings + -vvv Info + -vvvv Debug + -vvvvv Traces (warning: very verbose!) +``` + +## `reth db stats` + +```bash +$ reth db stats --help +Lists all the tables, their entry count and their size + +Usage: reth db stats [OPTIONS] + +Options: + -h, --help +``` + +## `reth db list` + +```bash +$ reth db list --help +Lists the contents of a table + +Usage: reth db list [OPTIONS] + +Arguments: +
+ The table name + +Options: + -s, --start + Where to start iterating + + [default: 0] + + -l, --len + How many items to take from the walker + + [default: 5] + + -h, --help + Print help (see a summary with '-h') +``` + +## `reth db drop` + +```bash +$ reth db drop --help +Deletes all database entries + +Usage: reth db drop [OPTIONS] + +Options: + -h, --help + Print help (see a summary with '-h') +``` diff --git a/book/cli/drop-stage.md b/book/cli/drop-stage.md index 2702af29a..59a224db7 100644 --- a/book/cli/drop-stage.md +++ b/book/cli/drop-stage.md @@ -1 +1,73 @@ # reth drop-stage + +```bash +$ reth drop-stage --help +Drops a stage's tables from the database + +Usage: reth drop-stage [OPTIONS] + +Arguments: + + [possible values: headers, bodies, senders, execution, hashing, merkle, tx-lookup, history] + +Options: + --datadir + The path to the data dir for all reth files and subdirectories. + + Defaults to the OS-specific data directory: + + - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/` + - Windows: `{FOLDERID_RoamingAppData}/reth/` + - macOS: `$HOME/Library/Application Support/reth/` + + [default: default] + + --db + The path to the database folder. If not specified, it will be set in the data dir for the + chain being used. + + --chain + The chain this node is running. + + Possible values are either a built-in chain or the path to a chain specification file. + + Built-in chains: + - mainnet + - goerli + - sepolia + + [default: mainnet] + + -h, --help + Print help (see a summary with '-h') + +Logging: + --log.persistent + The flag to enable persistent logs + + --log.directory + The path to put log files in + + [default: /Users/georgios/Library/Caches/reth/logs] + + --log.journald + Log events to journald + + --log.filter + The filter to use for logs written to the log file + + [default: debug] + +Display: + -v, --verbosity... + Set the minimum log level. + + -v Errors + -vv Warnings + -vvv Info + -vvvv Debug + -vvvvv Traces (warning: very verbose!) + + -q, --quiet + Silence all log output +``` diff --git a/book/cli/dump-stage.md b/book/cli/dump-stage.md index 0f318adfc..d7355557e 100644 --- a/book/cli/dump-stage.md +++ b/book/cli/dump-stage.md @@ -1 +1,82 @@ -# reth dump-stage +# `reth dump-stage` + +```bash +$ reth dump-stage --help +Dumps a stage from a range into a new database + +Usage: reth dump-stage [OPTIONS] + +Commands: + execution + Execution stage + storage-hashing + StorageHashing stage + account-hashing + AccountHashing stage + merkle + Merkle stage + help + Print this message or the help of the given subcommand(s) + +Options: + --datadir + The path to the data dir for all reth files and subdirectories. + + Defaults to the OS-specific data directory: + + - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/` + - Windows: `{FOLDERID_RoamingAppData}/reth/` + - macOS: `$HOME/Library/Application Support/reth/` + + [default: default] + + --db + The path to the database folder. If not specified, it will be set in the data dir for the + chain being used. + + --chain + The chain this node is running. + + Possible values are either a built-in chain or the path to a chain specification file. + + Built-in chains: + - mainnet + - goerli + - sepolia + + [default: mainnet] + + -h, --help + Print help (see a summary with '-h') + +Logging: + --log.persistent + The flag to enable persistent logs + + --log.directory + The path to put log files in + + [default: /Users/georgios/Library/Caches/reth/logs] + + --log.journald + Log events to journald + + --log.filter + The filter to use for logs written to the log file + + [default: debug] + +Display: + -v, --verbosity... + Set the minimum log level. + + -v Errors + -vv Warnings + -vvv Info + -vvvv Debug + -vvvvv Traces (warning: very verbose!) + + -q, --quiet + Silence all log output + +``` diff --git a/book/cli/node.md b/book/cli/node.md index d834e960f..0a63971b9 100644 --- a/book/cli/node.md +++ b/book/cli/node.md @@ -1 +1,199 @@ -# reth node +# `reth node` + +The main node operator command. + +```bash +$ reth node --help + +Start the node + +Usage: reth node [OPTIONS] + +Options: + --datadir + The path to the data dir for all reth files and subdirectories. + + Defaults to the OS-specific data directory: + + - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/` + - Windows: `{FOLDERID_RoamingAppData}/reth/` + - macOS: `$HOME/Library/Application Support/reth/` + + [default: default] + + --config + The path to the configuration file to use. + + --p2p-secret-key + Secret key to use for this node. + + This will also deterministically set the peer ID. If not specified, it will be set in the data dir for the chain being used. + + --chain + The chain this node is running. + + Possible values are either a built-in chain or the path to a chain specification file. + + Built-in chains: + - mainnet + - goerli + - sepolia + + [default: mainnet] + + -h, --help + Print help (see a summary with '-h') + +Metrics: + --metrics + Enable Prometheus metrics. + + The metrics will be served at the given interface and port. + +Networking: + -d, --disable-discovery + Disable the discovery service + + --disable-dns-discovery + Disable the DNS discovery + + --disable-discv4-discovery + Disable Discv4 discovery + + --discovery.port + The UDP port to use for P2P discovery/networking. default: 30303 + + --trusted-peers + Target trusted peer enodes --trusted-peers enode://abcd@192.168.0.1:30303 + + --trusted-only + Connect only to trusted peers + + --bootnodes + Bootnodes to connect to initially. + + Will fall back to a network-specific default if not specified. + + --peers-file + The path to the known peers file. Connected peers are dumped to this file on nodes + shutdown, and read on startup. Cannot be used with `--no-persist-peers`. + + --no-persist-peers + Do not persist peers. + + --nat + NAT resolution method + + [default: any] + + --port + Network listening port. default: 30303 + +Rpc: + --http + Enable the HTTP-RPC server + + --http.addr + Http server address to listen on + + --http.port + Http server port to listen on + + --http.api + Rpc Modules to be configured for http server + + --http.corsdomain + Http Corsdomain to allow request from + + --ws + Enable the WS-RPC server + + --ws.addr + Ws server address to listen on + + --ws.port + Ws server port to listen on + + --ws.origins + Origins from which to accept WebSocket requests + + --ws.api + Rpc Modules to be configured for Ws server + + --ipcdisable + Disable the IPC-RPC server + + --ipcpath + Filename for IPC socket/pipe within the datadir + + --authrpc.addr + Auth server address to listen on + + --authrpc.port + Auth server port to listen on + + --authrpc.jwtsecret + Path to a JWT secret to use for authenticated RPC endpoints + + --auto-mine + Automatically mine blocks for new transactions + +Debug: + --debug.continuous + Prompt the downloader to download blocks one at a time. + + NOTE: This is for testing purposes only. + + --debug.terminate + Flag indicating whether the node should be terminated after the pipeline sync + + --debug.tip + Set the chain tip manually for testing purposes. + + NOTE: This is a temporary flag + + --debug.max-block + Runs the sync only up to the specified block + + --debug.print-inspector + Print opcode level traces directly to console during execution + + --debug.hook-block + Hook on a specific block during execution + + --debug.hook-transaction + Hook on a specific transaction during execution + + --debug.hook-all + Hook on every transaction in a block + +Logging: + --log.persistent + The flag to enable persistent logs + + --log.directory + The path to put log files in + + [default: /Users/georgios/Library/Caches/reth/logs] + + --log.journald + Log events to journald + + --log.filter + The filter to use for logs written to the log file + + [default: debug] + +Display: + -v, --verbosity... + Set the minimum log level. + + -v Errors + -vv Warnings + -vvv Info + -vvvv Debug + -vvvvv Traces (warning: very verbose!) + + -q, --quiet + Silence all log output +``` diff --git a/book/cli/p2p.md b/book/cli/p2p.md index ba842ce92..9d84a65bf 100644 --- a/book/cli/p2p.md +++ b/book/cli/p2p.md @@ -1 +1,153 @@ -# reth p2p +# `reth p2p` + +```bash +$ reth p2p --help +P2P Debugging utilities + +Usage: reth p2p [OPTIONS] + +Commands: + header + Download block header + body + Download block body + help + Print this message or the help of the given subcommand(s) + +Options: + --config + The path to the configuration file to use. + + --chain + The chain this node is running. + + Possible values are either a built-in chain or the path to a chain specification file. + + Built-in chains: + - mainnet + - goerli + - sepolia + + [default: mainnet] + + --datadir + The path to the data dir for all reth files and subdirectories. + + Defaults to the OS-specific data directory: + + - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/` + - Windows: `{FOLDERID_RoamingAppData}/reth/` + - macOS: `$HOME/Library/Application Support/reth/` + + [default: default] + + --p2p-secret-key + Secret key to use for this node. + + This also will deterministically set the peer ID. + + -d, --disable-discovery + Disable the discovery service + + --disable-dns-discovery + Disable the DNS discovery + + --disable-discv4-discovery + Disable Discv4 discovery + + --discovery.port + The UDP port to use for P2P discovery/networking. default: 30303 + + --trusted-peer + Target trusted peer + + --trusted-only + Connect only to trusted peers + + --retries + The number of retries per request + + [default: 5] + + --nat + [default: any] + + -h, --help + Print help (see a summary with '-h') + +Logging: + --log.persistent + The flag to enable persistent logs + + --log.directory + The path to put log files in + + [default: /Users/georgios/Library/Caches/reth/logs] + + --log.journald + Log events to journald + + --log.filter + The filter to use for logs written to the log file + + [default: debug] + +Display: + -v, --verbosity... + Set the minimum log level. + + -v Errors + -vv Warnings + -vvv Info + -vvvv Debug + -vvvvv Traces (warning: very verbose!) + + -q, --quiet + Silence all log output +``` + +## `reth p2p header` + +```bash +$ reth p2p header --help +Download block header + +Usage: reth p2p header [OPTIONS] + +Arguments: + + The header number or hash + +Options: + --p2p-secret-key + Secret key to use for this node. + + This also will deterministically set the peer ID. + + -h, --help + Print help (see a summary with '-h') +``` + + +## `reth p2p body` + + +```bash +$ reth p2p body --help +Download block body + +Usage: reth p2p body [OPTIONS] + +Arguments: + + The block number or hash + +Options: + --p2p-secret-key + Secret key to use for this node. + + This also will deterministically set the peer ID. + + -h, --help + Print help (see a summary with '-h') +``` diff --git a/book/cli/stage.md b/book/cli/stage.md index 4026f6e0c..51b219138 100644 --- a/book/cli/stage.md +++ b/book/cli/stage.md @@ -1 +1,134 @@ -# reth stage +# `reth stage` + +```bash +Run a single stage. + +Usage: reth stage [OPTIONS] --from --to + +Arguments: + + The name of the stage to run + + [possible values: headers, bodies, senders, execution, hashing, merkle, tx-lookup, history] + +Options: + --config + The path to the configuration file to use. + + --datadir + The path to the data dir for all reth files and subdirectories. + + Defaults to the OS-specific data directory: + + - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/` + - Windows: `{FOLDERID_RoamingAppData}/reth/` + - macOS: `$HOME/Library/Application Support/reth/` + + [default: default] + + --chain + The chain this node is running. + + Possible values are either a built-in chain or the path to a chain specification file. + + Built-in chains: + - mainnet + - goerli + - sepolia + + [default: mainnet] + + --p2p-secret-key + Secret key to use for this node. + + This also will deterministically set the peer ID. + + --metrics + Enable Prometheus metrics. + + The metrics will be served at the given interface and port. + + --from + The height to start at + + -t, --to + The end of the stage + + -s, --skip-unwind + Normally, running the stage requires unwinding for stages that already have been run, in order to not rewrite to the same database slots. + + You can optionally skip the unwinding phase if you're syncing a block range that has not been synced before. + + -h, --help + Print help (see a summary with '-h') + +Networking: + -d, --disable-discovery + Disable the discovery service + + --disable-dns-discovery + Disable the DNS discovery + + --disable-discv4-discovery + Disable Discv4 discovery + + --discovery.port + The UDP port to use for P2P discovery/networking. default: 30303 + + --trusted-peers + Target trusted peer enodes --trusted-peers enode://abcd@192.168.0.1:30303 + + --trusted-only + Connect only to trusted peers + + --bootnodes + Bootnodes to connect to initially. + + Will fall back to a network-specific default if not specified. + + --peers-file + The path to the known peers file. Connected peers are dumped to this file on nodes + shutdown, and read on startup. Cannot be used with `--no-persist-peers`. + + --no-persist-peers + Do not persist peers. + + --nat + NAT resolution method + + [default: any] + + --port + Network listening port. default: 30303 + +Logging: + --log.persistent + The flag to enable persistent logs + + --log.directory + The path to put log files in + + [default: /Users/georgios/Library/Caches/reth/logs] + + --log.journald + Log events to journald + + --log.filter + The filter to use for logs written to the log file + + [default: debug] + +Display: + -v, --verbosity... + Set the minimum log level. + + -v Errors + -vv Warnings + -vvv Info + -vvvv Debug + -vvvvv Traces (warning: very verbose!) + + -q, --quiet + Silence all log output + +```