CLI: Help polish & add short, relevant help for usage/argument errors

[David Bennett (dkbennett)]

Summary of the Pull Request

This is a usability improvement for the CLI on errors related to user input. Currently anytime there is a usage error the full help is displayed for a command, which for some commands can be very lengthy and obscure the error information. This PR refines WSLC error handling so users receive help relevant to the type of failure. Invalid commands show command help, invalid options or arguments show only related help, and execution failures show only the error message.

This PR also uses the terms "argument" and "option" more consistently. Internally we consider them both "arguments" but for the user arguments are positional and options are flags and values.

Here's an example of the reworked short help showing different types of errors and the usage and relevant context that is shown instead of the full help:

PR Checklist

• Closes: Link to issue #xxx
• Communication: I've discussed this with core contributors already. If work hasn't been agreed, this work might be rejected
• Tests: Added/updated if needed and all pass
• Localization: All end user facing strings can be localized
• Dev docs: Added/updated if needed
• Documentation updated: If checked, please file a pull request on our docs repo and link it here: #xxx

Detailed Description of the Pull Request / Additional comments

• Separate command, argument, and execution errors.
• Show full help only for explicit help requests.
• Show usage and subcommands for command errors.
• Show usage and related options or arguments for input errors.
• Show only the error message for execution failures.
• Add a command-specific Run '<command> --help' for more information. hint.
• Show copyright and detailed descriptions only in full help.
• Use consistent option and argument terminology.
• List all accepted Boolean values in validation errors.
• Added new E2E Help tests to verify this functionality.

Validation Steps Performed

• Focused help tests
• CLI parser unit tests
• Argument validation tests
• Host-mode execution error tests
• Various manual ad-hoc testing

[Copilot]

Pull request overview

This PR refines WSLC CLI error handling so usage/argument errors no longer dump full command help, instead emitting shorter, context-relevant help (or only the error for execution failures). It also standardizes user-facing terminology around “options” vs “arguments” and adds/updates tests and localized strings to validate the new behavior.

Changes:

• Split CLI failures into command, argument, and execution error paths, adjusting help output accordingly (full vs focused help vs message-only).
• Extend exceptions/argument parsing to carry “relevant arguments” so short help can show just related options/arguments.
• Update localization strings and add/adjust unit + E2E tests to verify routing and output content.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/windows/wslc/WSLCCLIParserUnitTests.cpp	Validates argument-parser error messages more precisely by asserting exception text.
test/windows/wslc/WSLCCLIArgumentUnitTests.cpp	Updates expected exception type for host-network validation behavior.
test/windows/wslc/e2e/WSLCE2ESessionEnterTests.cpp	Adds E2E coverage ensuring execution errors don’t print help.
test/windows/wslc/e2e/WSLCE2EGlobalTests.cpp	Adds E2E assertions for “full help” vs “error help” content and the new “Run … --help” hint.
test/windows/wslc/e2e/WSLCE2EContainerRunTests.cpp	Tightens E2E expectations for host-network rejection output.
test/windows/wslc/e2e/WSLCE2EContainerCreateTests.cpp	Tightens E2E expectations for host-network rejection output.
src/windows/wslc/core/Main.cpp	Routes Argument/Command/Execution exceptions to the appropriate help/message output path.
src/windows/wslc/core/Exceptions.h	Introduces CLIException base + adds ArgumentException context (relevant Argument list) + ExecutionException.
src/windows/wslc/core/Command.h	Adds HelpOutput modes and extends OutputHelp API to accept relevant arguments.
src/windows/wslc/core/Command.cpp	Implements focused help output and rewraps validation exceptions with configured Argument metadata.
src/windows/wslc/commands/SessionEnterCommand.cpp	Reclassifies session option misuse as an execution failure to suppress help output.
src/windows/wslc/commands/RegistryCommand.cpp	Throws ArgumentException with relevant arguments for focused “related options” help.
src/windows/wslc/commands/ContainerListCommand.cpp	Throws ArgumentException with relevant arguments for focused help on option conflicts.
src/windows/wslc/arguments/ArgumentValidation.cpp	Attaches conflicting arguments for focused help; reclassifies host networking rejection as execution failure.
src/windows/wslc/arguments/ArgumentParser.cpp	Attaches the specific Argument to parse/validation errors for focused help.
src/windows/wslc/arguments/Argument.h	Adds Argument::IsOption() helper for option-vs-argument classification in help.
localization/strings/en-US/Resources.resw	Adds/updates localized strings for “related” headings, option terminology, and “Run … --help” hint.

Suppressed comments (1)

src/windows/wslc/arguments/ArgumentParser.cpp:165

• FindArgument() can return nullptr; WI_ASSERT is compiled out in release builds, so dereferencing *argument here can AV. Guard the pointer and fall back to returning an ArgumentException without a bound Argument when it is missing.

        const auto* argument = FindArgument(type);
        WI_ASSERT(argument != nullptr);
        return ArgumentException(Localization::WSLCCLI_FlagInvalidBooleanError(currArg), *argument);

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

src/windows/wslc/core/Command.cpp:549

• This uses std::ranges::find, but Command.cpp doesn’t include (and doesn’t include precomp.h). This can fail to compile depending on indirect includes. Prefer the form here (or add an explicit include for this TU).

                        const auto configuredArgument = std::ranges::find(definedArgs, exceptionArgument.Type(), &Argument::Type);

src/windows/wslc/core/Command.cpp:602

• GetArgumentsForHelp uses std::ranges::find, but Command.cpp doesn’t include (and it doesn’t include precomp.h). This is likely to break compilation. Prefer std::find_if (already available via ) or add an explicit include for this translation unit.

        const auto argument = std::ranges::find(arguments, type, &Argument::Type);
        THROW_HR_IF_MSG(E_INVALIDARG, argument == arguments.end(), "Argument type %zu is not configured for command", static_cast<size_t>(type));

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/windows/wslc/core/Exceptions.h:64

• ArgumentException(std::wstring_view, Argument) initializes m_arguments via an initializer-list (m_arguments{std::move(argument)}), which does not actually move (initializer_list elements are const) and performs an extra copy. This is also misleading for future maintainers if Argument ever becomes expensive-to-copy or move-only.

    ArgumentException(std::wstring_view message, Argument argument) : CommandException(message), m_arguments{std::move(argument)}
    {
    }