Group `--help` options into sections for commands with shared signing/transaction options

[leighmcculloch]

What problem does your feature solve?

53 commands across the CLI list all options in a single flat Options: section, mixing command-specific parameters with shared signing, transaction, and source-account options. This makes it hard to quickly identify the core parameters of a command vs the shared boilerplate.

The affected command groups are:

• All 22 stellar tx new subcommands
• All 22 stellar tx operation add subcommands
• 5 stellar contract subcommands (deploy, upload, extend, restore, invoke)
• stellar contract asset deploy
• stellar tx sign, stellar tx simulate, stellar message sign

For example, stellar tx new payment -h currently shows:

Options:
  -s, --source-account <SOURCE_ACCOUNT>   ...
      --sign-with-key <SIGN_WITH_KEY>     ...
      --hd-path <HD_PATH>                 ...
      --sign-with-lab                     ...
      --sign-with-ledger                  ...
      --fee <FEE>                         ...
      --inclusion-fee <INCLUSION_FEE>     ...
      --build-only                        ...
      --destination <DESTINATION>         ...
      --asset <ASSET>                     ...
      --amount <AMOUNT>                   ...
  -h, --help                              ...

The primary options (--destination, --asset, --amount) are buried among 8 shared options that appear identically on every tx new command.

What would you like to see?

Group the options into sections using clap's help_heading feature:

Options:
      --destination <DESTINATION>         Account to send to, e.g. `GBX...`
      --asset <ASSET>                     Asset to send, default native [default: native]
      --amount <AMOUNT>                   Amount of the asset to send, in stroops

Transaction Options:
  -s, --source-account <SOURCE_ACCOUNT>   Account that where transaction originates from...
      --fee <FEE>                         ⚠️ Deprecated, use `--inclusion-fee`...
      --inclusion-fee <INCLUSION_FEE>     Maximum fee amount for transaction inclusion...
      --build-only                        Build the transaction and only write the base64 xdr to stdout

Signing Options:
      --sign-with-key <SIGN_WITH_KEY>     Sign with a local key...
      --hd-path <HD_PATH>                 If using a seed phrase to sign...
      --sign-with-lab                     Sign with https://lab.stellar.org
      --sign-with-ledger                  Sign with a ledger wallet

Help Options:
  -h, --help                              Print help

Since the signing and transaction options come from shared structs, this can be fixed centrally by adding #[command(next_help_heading = "...")] or #[arg(help_heading = "...")] annotations in a few places, and all 53 commands benefit at once.

Relevant source files:

• cmd/soroban-cli/src/config/mod.rs — config::Args (source account, fee, inclusion fee)
• cmd/soroban-cli/src/config/sign_with.rs — sign_with::Args (sign-with-key, hd-path, sign-with-lab, sign-with-ledger)
• cmd/soroban-cli/src/commands/tx/args.rs — tx::Args (build-only, flattens config::Args)

What alternatives are there?

• Keep the current flat list (status quo, but harder to scan)
• Use subcommands instead of options for signing method (more disruptive change)

Links

Related internal discussion about this started at: https://stellarfoundation.slack.com/archives/C06KTGUULUF/p1773790328751939

❤️ Thanks for reporting @dmkozh.

[leighmcculloch]

Here's a survey of all commands affected by this issue (stellar-cli v25.2.0). Every command below has signing, transaction, or source-account options mixed into the flat Options: section alongside the command's primary options.

The "Primary Options" column shows the options that should remain under Options:. Everything else currently in that section (--source-account, --sign-with-key, --hd-path, --sign-with-lab, --sign-with-ledger, --fee, --inclusion-fee, --build-only) should be grouped under separate headings like Signing Options: and Transaction Options:.

stellar tx new subcommands (22 commands)

Command	Primary Options
stellar tx new account-merge	--account
stellar tx new begin-sponsoring-future-reserves	--sponsored-id
stellar tx new bump-sequence	--bump-to
stellar tx new change-trust	--line, --limit
stellar tx new claim-claimable-balance	--balance-id
stellar tx new clawback	--from, --asset, --amount
stellar tx new clawback-claimable-balance	--balance-id
stellar tx new create-account	--destination, --starting-balance
stellar tx new create-claimable-balance	--asset, --amount, --claimant
stellar tx new create-passive-sell-offer	--selling, --buying, --amount, --price
stellar tx new end-sponsoring-future-reserves	(none — only shared options)
stellar tx new liquidity-pool-deposit	--liquidity-pool-id, --max-amount-a, --max-amount-b, --min-price, --max-price
stellar tx new liquidity-pool-withdraw	--liquidity-pool-id, --amount, --min-amount-a, --min-amount-b
stellar tx new manage-buy-offer	--selling, --buying, --amount, --price, --offer-id
stellar tx new manage-data	--data-name, --data-value
stellar tx new manage-sell-offer	--selling, --buying, --amount, --price, --offer-id
stellar tx new path-payment-strict-send	--send-asset, --send-amount, --destination, --dest-asset, --dest-min, --path
stellar tx new path-payment-strict-receive	--send-asset, --send-max, --destination, --dest-asset, --dest-amount, --path
stellar tx new payment	--destination, --asset, --amount
stellar tx new revoke-sponsorship	--account-id, --asset, --data-name, --offer-id, --liquidity-pool-id, --claimable-balance-id, --signer-key
stellar tx new set-options	--inflation-dest, --master-weight, --low-threshold, --med-threshold, --high-threshold, --home-domain, --signer, --signer-weight, --set-required, --set-revocable, --set-clawback-enabled, --set-immutable, --clear-required, --clear-revocable, --clear-immutable, --clear-clawback-enabled
stellar tx new set-trustline-flags	--trustor, --asset, --set-authorize, --set-authorize-to-maintain-liabilities, --set-trustline-clawback-enabled, --clear-authorize, --clear-authorize-to-maintain-liabilities, --clear-trustline-clawback-enabled

stellar tx operation add subcommands (22 commands, same set)

These mirror the tx new subcommands exactly (same primary options plus --operation-source-account), with the same flat Options: mixing issue.

stellar contract subcommands (5 commands)

Command	Primary Options
stellar contract deploy	--wasm, --wasm-hash, --salt, --alias, --ignore-checks, --optimize, --package, --meta
stellar contract upload	--wasm, --optimize, --ignore-checks, --package, --meta
stellar contract extend	--id, --key, --key-xdr, --wasm, --wasm-hash, --durability, --ledgers-to-extend, --ttl-ledger-only
stellar contract restore	--id, --key, --key-xdr, --wasm, --wasm-hash, --durability, --ledgers-to-extend, --ttl-ledger-only
stellar contract invoke	--id, --is-view, --send

stellar contract asset subcommands (1 command)

Command	Primary Options
stellar contract asset deploy	--asset, --alias

Other commands (3 commands)

Command	Primary Options
stellar tx sign	(none — only signing options, but they could still benefit from a Signing Options: heading)
stellar tx simulate	--instruction-leeway
stellar message sign	--base64

Total: 53 commands affected