#6485·clap

Usage text for --help/--version includes <COMMAND> if subcommand_required is set

Author: simonborjeCreated Aug 13, 2026Updated Aug 20, 2026
LabelsC-bugA-helpS-triage

Please complete the following tasks

Rust Version

rustc 1.97.1

Clap Version

clap 4.6.6

Minimal reproducible code

rust
use clap::Command;

fn cli() -> Command {
    Command::new("command_name")
        .subcommand_required(true)
        .subcommand(
            Command::new("test_command")
        )
}

fn main() {
    let _matches = cli().get_matches_from(vec!["command_name", "--hel"]);
}

Steps to reproduce the bug with the above code

Run the reproduction code to get the error output.

Actual Behaviour

The error text suggests that --help requires a <COMMAND>.

error: unexpected argument '--hel' found

  tip: a similar argument exists: '--help'

Usage: command_name --help <COMMAND>

For more information, try '--help'.

Expected Behaviour

The suggestion should not indicate that a command is required.

...
Usage: command_name --help
...

Additional Context

When misspelling an argument with ArgAction::Version or ::Help, for example the default --help argument, the usage text indicates that the argument requires a command (<COMMAND>). It seems that version and help commands don't actually require any command.

Debug Output

[clap_builder::builder::command]Command::_do_parse [clap_builder::builder::command]Command::_build: name="command_name" [clap_builder::builder::command]Command::_propagate:command_name [clap_builder::builder::command]Command::_check_help_and_version:command_name expand_help_tree=false [clap_builder::builder::command]Command::long_help_exists [clap_builder::builder::command]Command::_check_help_and_version: Building default --help [clap_builder::builder::command]Command::_check_help_and_version: Building help subcommand [clap_builder::builder::command]Command::_propagate_global_args:command_name [clap_builder::builder::debug_asserts]Command::_debug_asserts [clap_builder::builder::debug_asserts]Arg::_debug_asserts:help [clap_builder::builder::debug_asserts]Command::_verify_positionals [clap_builder::parser::parser]Parser::get_matches_with [clap_builder::parser::parser]Parser::parse [clap_builder::parser::parser]Parser::get_matches_with: Begin parsing '"--hel"' [clap_builder::parser::parser]Parser::possible_subcommand: arg=Ok("--hel") [clap_builder::parser::parser]Parser::get_matches_with: sc=None [clap_builder::parser::parser]Parser::parse_long_arg [clap_builder::parser::parser]Parser::parse_long_arg: Does it contain '='... [clap_builder::parser::parser]Parser::possible_long_flag_subcommand: arg="hel" [clap_builder::parser::parser]Parser::get_matches_with: After parse_long_arg NoMatchingArg { arg: "hel" } [clap_builder::parser::parser]Parser::did_you_mean_error: arg=hel [clap_builder::parser::parser]Parser::did_you_mean_error: longs=["help"] [clap_builder::parser::parser]Parser::remove_overrides: id="help" [clap_builder::parser::arg_matcher]ArgMatcher::start_custom_arg: id="help", source=CommandLine [clap_builder::builder::command]Command::groups_for_arg: id="help" [ clap_builder::output::usage]Usage::create_usage_with_title [ clap_builder::output::usage]Usage::create_usage_no_title [ clap_builder::output::usage]Usage::create_smart_usage [ clap_builder::output::usage]Usage::write_arg_usage; incl_reqs=true [ clap_builder::output::usage]Usage::write_args: incls=["help"] [ clap_builder::output::usage]Usage::get_args: unrolled_reqs=[] [ clap_builder::output::usage]Usage::create_usage_with_title: usage=Usage: command_name --help [clap_builder::builder::command]Command::color: Color setting... [clap_builder::builder::command]Auto [clap_builder::builder::command]Command::color: Color setting... [clap_builder::builder::command]Auto