feat(cli): organize help flags into logical sections

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - auto-fund spammer accounts periodically when running with `--forever` to prevent ETH depletion
 - add `--time-to-inclusion-bucket` flag to configure histogram bucket size in reports ([#498](https://github.com/flashbots/contender/pull/498))
 - move default data dir to `$XDG_STATE_HOME/contender` (`~/.local/state/contender`), with automatic migration from legacy `~/.contender` ([#460](https://github.com/flashbots/contender/issues/460))
+- organize `--help` output into logical sections for `spam` and `campaign` flags ([#408](https://github.com/flashbots/contender/issues/408))
 
 ## [0.9.0](https://github.com/flashbots/contender/releases/tag/v0.9.0) - 2026-03-17
 
@@ -93,4 +94,4 @@ Internal changes:
 
 - revamp error handling ([#378](https://github.com/flashbots/contender/pull/378))
 - DB schema bumped to `user_version = 6` to record campaign/stage metadata in runs.
-  - If you see a DB version mismatch, export/reset your DB: `contender db export` (optional backup) then `contender db reset` (or `drop`) to recreate with the new schema.
+  - If you see a DB version mismatch, export/reset your DB: `contender db export` (optional backup) then `contender db reset` (or `drop`) to recreate with the new schema.

crates/cli/CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - auto-fund spammer accounts periodically when running with `--forever` to prevent ETH depletion; refund interval is derived from `--min-balance`, `get_max_spam_cost()`, and `--tps`/`--tpb`
 - add `--time-to-inclusion-bucket` flag to configure histogram bucket size in reports ([#498](https://github.com/flashbots/contender/pull/498/changes))
 - move default data dir from `~/.contender` to `$XDG_STATE_HOME/contender` (defaults to `~/.local/state/contender`), with automatic migration of existing data ([#460](https://github.com/flashbots/contender/issues/460/changes))
+- organize `--help` output into logical sections for `spam` and `campaign` flags ([#408](https://github.com/flashbots/contender/issues/408))
 
 ## [0.9.0](https://github.com/flashbots/contender/releases/tag/v0.9.0) - 2026-03-17
 

crates/cli/src/commands/campaign.rs

@@ -3,7 +3,10 @@ use crate::commands::spam::SpamCampaignContext;
 use crate::commands::GenericDb;
 use crate::commands::{
     self,
-    common::{ScenarioSendTxsCliArgs, SendTxsCliArgsInner},
+    common::{
+        ScenarioSendTxsCliArgs, SendTxsCliArgsInner, HELP_HEADING_COMMON, HELP_HEADING_PAYLOAD,
+        HELP_HEADING_RUNTIME,
+    },
     SpamCliArgs,
 };
 use crate::error::CliError;
@@ -24,7 +27,7 @@ use uuid::Uuid;
 #[derive(Clone, Debug, Args)]
 pub struct CampaignCliArgs {
     /// Path to campaign config TOML
-    #[arg(help = "Path to campaign config TOML")]
+    #[arg(help = "Path to campaign config TOML", help_heading = HELP_HEADING_COMMON)]
     pub campaign: String,
 
     #[command(flatten)]
@@ -36,7 +39,8 @@ pub struct CampaignCliArgs {
         short,
         long,
         long_help = "HTTP JSON-RPC URL to use for bundle spamming (must support `eth_sendBundle`)",
-        visible_aliases = ["builder", "builder-rpc-url", "builder-rpc"]
+        visible_aliases = ["builder", "builder-rpc-url", "builder-rpc"],
+        help_heading = HELP_HEADING_COMMON,
     )]
     pub builder_url: Option<Url>,
 
@@ -46,7 +50,8 @@ pub struct CampaignCliArgs {
         long,
         default_value_t = 12,
         long_help = "The number of blocks to wait for pending transactions to land. If transactions land within the timeout, it resets.",
-        visible_aliases = ["wait"]
+        visible_aliases = ["wait"],
+        help_heading = HELP_HEADING_RUNTIME,
     )]
     pub pending_timeout: u64,
 
@@ -55,7 +60,8 @@ pub struct CampaignCliArgs {
         long = "rpc-batch-size",
         value_name = "N",
         default_value_t = 0,
-        long_help = "Max number of eth_sendRawTransaction calls to send in a single JSON-RPC batch request. 0 (default) disables batching and sends one eth_sendRawTransaction per tx."
+        long_help = "Max number of eth_sendRawTransaction calls to send in a single JSON-RPC batch request. 0 (default) disables batching and sends one eth_sendRawTransaction per tx.",
+        help_heading = HELP_HEADING_PAYLOAD,
     )]
     pub rpc_batch_size: u64,
 
@@ -64,15 +70,17 @@ pub struct CampaignCliArgs {
         long,
         help = "Ignore transaction receipts.",
         long_help = "Keep sending transactions without waiting for receipts.",
-        visible_aliases = ["ir", "no-receipts"]
+        visible_aliases = ["ir", "no-receipts"],
+        help_heading = HELP_HEADING_RUNTIME,
     )]
     pub ignore_receipts: bool,
 
     /// Disable nonce synchronization between batches.
     #[arg(
         long,
         help = "Disable nonce synchronization between batches.",
-        visible_aliases = ["disable-nonce-sync", "fast-nonces"]
+        visible_aliases = ["disable-nonce-sync", "fast-nonces"],
+        help_heading = HELP_HEADING_RUNTIME,
     )]
     pub optimistic_nonces: bool,
 
@@ -81,15 +89,17 @@ pub struct CampaignCliArgs {
         global = true,
         long,
         long_help = "Generate a report for the spam run(s) after the campaign completes.",
-        visible_aliases = ["report"]
+        visible_aliases = ["report"],
+        help_heading = HELP_HEADING_RUNTIME,
     )]
     pub gen_report: bool,
 
     /// Skip setup steps when running builtin scenarios.
     #[arg(
         long,
         global = true,
-        long_help = "If set, skip contract deployment & setup transactions when running builtin scenarios. Does nothing when running a scenario file."
+        long_help = "If set, skip contract deployment & setup transactions when running builtin scenarios. Does nothing when running a scenario file.",
+        help_heading = HELP_HEADING_RUNTIME,
     )]
     pub skip_setup: bool,
 
@@ -98,15 +108,17 @@ pub struct CampaignCliArgs {
         long = "timeout",
         long_help = "The time to wait for spammer to recover from failure before stopping contender.",
         value_parser = parse_duration,
-        default_value = "5min"
+        default_value = "5min",
+        help_heading = HELP_HEADING_RUNTIME,
     )]
     pub spam_timeout: Duration,
 
     /// Use eth_sendRawTransactionSync instead of eth_sendRawTransaction.
     #[arg(
         long = "send-raw-tx-sync",
         default_value_t = false,
-        long_help = "Use eth_sendRawTransactionSync instead of eth_sendRawTransaction. The RPC blocks until the tx is included, giving precise TTI. NOTE: incompatible with --rpc-batch-size."
+        long_help = "Use eth_sendRawTransactionSync instead of eth_sendRawTransaction. The RPC blocks until the tx is included, giving precise TTI. NOTE: incompatible with --rpc-batch-size.",
+        help_heading = HELP_HEADING_PAYLOAD,
     )]
     pub send_raw_tx_sync: bool,
 
@@ -115,7 +127,8 @@ pub struct CampaignCliArgs {
         global = true,
         default_value_t = false,
         long = "forever",
-        visible_aliases = ["indefinite", "indefinitely", "infinite"]
+        visible_aliases = ["indefinite", "indefinitely", "infinite"],
+        help_heading = HELP_HEADING_RUNTIME,
     )]
     pub run_forever: bool,
 
@@ -124,20 +137,28 @@ pub struct CampaignCliArgs {
         long = "flashblocks-ws-url",
         value_name = "URL",
         env = "FLASHBLOCKS_WS_URL",
-        long_help = "WebSocket URL for subscribing to flashblock pre-confirmations. When set, contender will track sub-block inclusion latency alongside full-block metrics."
+        long_help = "WebSocket URL for subscribing to flashblock pre-confirmations. When set, contender will track sub-block inclusion latency alongside full-block metrics.",
+        help_heading = HELP_HEADING_RUNTIME,
     )]
     pub flashblocks_ws_url: Option<Url>,
 
     /// Skip per-transaction debug traces when generating the report.
     #[arg(
         long,
         global = true,
-        long_help = "Skip per-transaction debug traces (debug_traceTransaction) when generating the campaign report. This significantly speeds up report generation for large runs at the cost of omitting the storage heatmap and tx gas used charts."
+        long_help = "Skip per-transaction debug traces (debug_traceTransaction) when generating the campaign report. This significantly speeds up report generation for large runs at the cost of omitting the storage heatmap and tx gas used charts.",
+        help_heading = HELP_HEADING_RUNTIME,
     )]
     pub skip_tx_traces: bool,
 
     /// Bucket size in milliseconds for the time-to-inclusion histogram.
-    #[arg(long, default_value_t = 1000, value_name = "MS", value_parser = clap::value_parser!(u64).range(1..=10000))]
+    #[arg(
+        long,
+        default_value_t = 1000,
+        value_name = "MS",
+        value_parser = clap::value_parser!(u64).range(1..=10000),
+        help_heading = HELP_HEADING_RUNTIME
+    )]
     pub time_to_inclusion_bucket: u64,
 }