standardizes syntax for t/f and makes clear when flag applies

[m4sterbunny]

Description

Clean up / verification of T/F
Boolean - 2 variants remain
required =<true|false>
optional [=<true|false>], where default is false and passing the boolean is optional, the bash example shows a flag only

Issue(s) fixed

Fixes #partial 1772

Preview

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
besu-docs	Ready	Preview	Comment	Dec 5, 2025 8:40am

[m4sterbunny]

Running through the logic here ahead of QA round. We have 3 conditions that apply to the boolean CLI options:

A. Optional, flag-only OK

If default is false, can document as --flag
If default is true, better to provide false example: --flag=false to highlight this
✔ --flag
✔ --flag=true
✔ --flag=false

B. Required, must be =true|false

document as --flag=<true|false>
❌ --flag
✔ --flag=true
✔ --flag=false

C. Optional, must be =true|false

document as --flag[=<true|false>]
❌ --flag
✔ --flag=true
✔ --flag=false

[m4sterbunny]

OK dived in that rabbit hole and came out knowing that there is a great deal that I do not know:

CLI Options That Can Be Passed as Flags Only

This table shows which CLI options from the provided list can be passed as flags only (e.g., --option) without requiring a boolean value (e.g., --option=false), based on examination of test examples in the Besu codebase.

Option	Default Value	Fallback Value	Arity	Category	Tests Confirm Flag Only
--auto-log-bloom-caching-enabled	true	none	"1"	2	❌ No
--discovery-enabled	true	none	"1"	2	❌ No
--p2p-enabled	true	none	"1"	2	❌ No
--plugin-continue-on-error	false	none	"1"	2	❌ No
--engine-jwt-disabled	false	none	omitted	2	✅ Yes
--engine-rpc-enabled	false	none	omitted	2	❌ No
--bonsai-limit-trie-logs-enabled	DEFAULT_LIMIT_TRIE_LOGS_ENABLED	true	omitted	1	✅ Yes
--color-enabled	null	none	omitted	2	❌ No
--era1-import-prepipeline-enabled	DEFAULT_ERA1_IMPORT_PREPIPELINE_ENABLED	none	"0..1"	2	❌ No
--genesis-state-hash-cache-enabled	false	none	omitted	2	❌ No
--graphql-http-enabled	false	none	omitted	2	✅ Yes
--graphql-mtls-enabled	false	none	omitted	2	❌ No
--graphql-tls-enabled	false	none	omitted	2	❌ No
--history-expiry-prune	false	none	omitted	2	❌ No
--json-pretty-print-enabled	DEFAULT_PRETTY_JSON_ENABLED	none	omitted	2	❌ No
--metrics-enabled	false	none	omitted	2	✅ Yes
--metrics-push-enabled	false	none	omitted	2	✅ Yes
--random-peer-priority-enabled	false	none	omitted	2	❌ No
--receipt-compaction-enabled	DEFAULT_RECEIPT_COMPACTION_ENABLED	true	omitted	1	✅ Yes
--remote-connections-limit-enabled	true	none	omitted	2	❌ No
--revert-reason-enabled	false	none	omitted	2	✅ Yes
--rpc-http-authentication-enabled	false	none	omitted	2	✅ Yes
--rpc-http-enabled	false	none	omitted	2	✅ Yes
--rpc-http-tls-ca-clients-enabled	false	none	omitted	2	❌ No
--rpc-http-tls-client-auth-enabled	false	none	omitted	2	❌ No
--rpc-http-tls-enabled	false	none	omitted	2	✅ Yes
--rpc-ws-authentication-enabled	false	none	omitted	2	✅ Yes
--rpc-ws-enabled	false	none	omitted	2	✅ Yes
--rpc-ws-ssl-client-auth-enabled	false	none	omitted	2	❌ No
--rpc-ws-ssl-enabled	false	none	omitted	2	❌ No
--snapsync-server-enabled	DEFAULT_SNAP_SERVER_ENABLED	true	"0..1"	1	✅ Yes
--snapsync-synchronizer-pre-checkpoint-headers-only-enabled	DEFAULT_SNAP_SYNC_SAVE_PRE_MERGE_HEADERS_ONLY_ENABLED	none	"0..1"	2	❌ No
--snapsync-synchronizer-transaction-indexing-enabled	DEFAULT_SNAP_SYNC_TRANSACTION_INDEXING_ENABLED	none	"0..1"	2	❌ No
--strict-tx-replay-protection-enabled	false	true	"0..1"	1	✅ Yes
--tx-pool-enable-balance-check	DEFAULT_TX_POOL_ENABLE_BALANCE_CHECK	true	"0..1"	1	❌ No
--tx-pool-enable-save-restore	DEFAULT_ENABLE_SAVE_RESTORE	true	"0..1"	1	❌ No
--tx-pool-no-local-priority	DEFAULT_NO_LOCAL_PRIORITY	true	"0..1"	1	❌ No
--version-compatibility-protection	null	none	omitted	2	❌ No

Category Definitions

• Category 1 - Optional, flag-only OK: The option is optional, and the user may specify either --flag (flag-only) OR --flag=<true|false>. These options have fallbackValue present in their @Option annotation, which allows flag-only usage even when setToggleBooleanFlags(false) is enabled. The arity attribute may be omitted, "0..1", or other values, but the presence of fallbackValue is the determining factor. Documentation syntax: [--flag[=<true|false>]]

  Note: arity cannot make flag-only legal without fallbackValue. arity = "0..1" or no arity specified theoretically means the user may provide a value, or not provide one (pass as flag), but with toggles disabled, a boolean option without a value is not automatically accepted UNLESS a fallbackValue is defined.

• Category 2 - Optional option, must pass =true|false: The option is optional, but if the user includes it, they must provide a value: --flag=<true|false>. Flag-only syntax is NOT allowed. These options do not have fallbackValue in their @Option annotation. The arity attribute may be "1" (always requires a value), "0..1" (optional value), or omitted (defaults to optional), but without fallbackValue and with setToggleBooleanFlags(false) enabled, flag-only usage is not permitted. Documentation syntax: [--flag=<true|false>]

  Notes: When arity = "1", when the user provides this option, a value MUST follow, i.e. flag is disallowed

Summary

The combo of arity + fallbackValue + toggleBooleanFlags(false) gets us close, however, test results clearly show exceptions in both directions. In theory:

• arity determines what could happen
• toggleBooleanFlags(false) limits what will happen
• fallbackValue is the only mechanism that allows flag-only usage

Notes

• Classification is based on @Option annotations (arity, fallbackValue, required attributes) and assumes setToggleBooleanFlags(false) is enabled globally in Besu
• Default values are extracted from the Java field initializations in the source code
• Fallback values are extracted from the fallbackValue attribute in the @Option annotation. When an option is used as a flag-only (e.g., --flag), the fallbackValue is used. When the option is not provided at all, the default value is used.
• Arity values are extracted from the arity attribute in the @Option annotation. When arity is omitted, it defaults to optional (equivalent to "0..1" for boolean options). Arity "1" means a value must be provided when the option is used. Arity "0..1" means the value is optional when the option is used.
• Tests Confirm Flag Only column shows which options are actually used as flags only in test examples, regardless of their theoretical category
• Category 1 options have fallbackValue present in their @Option annotation, which theoretically allows flag-only usage even with setToggleBooleanFlags(false)
• Category 2 options do not have fallbackValue, so theoretically require explicit =<true|false> syntax, but some are used as flags only in practice (as shown in tests)
• Options marked with ❌ in "Tests Confirm Flag Only" either explicitly require values in tests or no test example was found showing flag-only usage