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

[m4sterbunny]

Closing this: there is no single logic route to identify from code whether flag is accepted where arity is not 1. Only testing can confirm. Will reduce the scope and adjust the original issue.