Specify exit codes in the --help text

[tobysmith568]

Is your feature request related to a problem? Please describe.

I would like to have a way to specify expected exit codes to be documented in the --help output, so that users know what codes to expect.

Describe the solution you'd like

I suggest a method on the ICommandConfigurator interface like so for documenting exit codes:

add.AddCommand<CreateFileCommand>("create")
   .WithDescription(CreateFileDescription)
   .WithExitCode(0, "The file is created successfully")
   .WithExitCode(1, "The file could not be created because it failed validation")
   .WithExitCode(2, "Network error")
   .WithExitCode(3, "Server error")

Describe alternatives you've considered

I currently add a block of text to my descriptions like so:

private const string CreateFileDescription =
    """    
    Creates a new file
    
    [yellow]EXIT CODES:[/]
        0 The file is created successfully
        1 The file could not be created because it failed validation
        2 Network error
        3 Server error
    """;

add.AddCommand<CreateFileCommand>("create")
   .WithDescription(CreateFileDescription)

Which fits in quite nicely

However, the proposed solution above would mean the exit codes wouldn't need to appear between the description and the usages. I'd suggest the exit codes should appear last, after the options - but I'm open to thoughts. It also means that the formatting would be more standardised.

Additional context

Let me know if this is something you'd be open to receiving a PR for! Thanks

---

Please upvote :+1: this issue if you are interested in it.

[FrankRay78]

Well now, isn't this an interesting idea @tobysmith568

Out of interest, do you know of other CLI applications that do this? I'm interested if this is a 'standard' thing eg. POSIX, GNU, defacto, and if so, to see examples of it in the wild,

But if not, that's cool too, it will perhaps need more in-depth consideration as to standardization.

I've looked here https://clig.dev/ and it's very quiet in terms of return code handling, apart from:

"Return zero exit code on success, non-zero on failure. Exit codes are how scripts determine whether a program succeeded or failed, so you should report this correctly. Map the non-zero exit codes to the most important failure modes."

[FrankRay78]

ls --help does indeed show exit codes in the help output:

Exit status:
 0  if OK,
 1  if minor problems (e.g., cannot access subdirectory),
 2  if serious trouble (e.g., cannot access command-line argument).

I'm up for a PR @tobysmith568, if you wish.

[tobysmith568]

Hey, sorry I went a little silent on this. Ah okay great, yeah I'll give it a go and report back soon