Help command usage section can be misleading

[sensslen]

I recently started using System.Commandline in https://github.com/sensslen/nuget-license. It's very nice to get the automatic help command, however the usage section can be very misleading. I publish that tool to a dotnet tool with the name of nuget-license (however the executable name is NuGetLicenseCore.

I get

$ nuget-license -h
Description:
  A .net tool to print and validate the licenses of .net code. This tool supports .NET (Core), .NET Standard and .NET
  Framework projects.

Usage:
  NuGetLicenseCore [options]

Options:
  -i, --input <i>                                       The project (or solution) file for which to analyze dependency
                                                        licenses
  -ji, --json-input <ji>                                File in json format that contains an array of all files to be
                                                        evaluated. The Files can either point to a project or a
                                                        solution.
  -t, --include-transitive                              If set, the whole license tree is followed in order to
                                                        determine all nuget's used by the projects
  -a, --allowed-license-types <a>                       File in json format that contains an array of all allowed
                                                        license types
  -ignore, --ignored-packages <ignore>                  File in json format that contains an array of nuget package
                                                        names to ignore (e.g. useful for nuget packages built
                                                        in-house). Note that even though the packages are ignored,
                                                        their transitive dependencies are not. Wildcard characters (*)
                                                        are supported to specify ranges of ignored packages.
  -mapping, --licenseurl-to-license-mappings <mapping>  File in json format that contains a dictionary to map license
                                                        urls to licenses.
  -override, --override-package-information <override>  File in json format that contains a list of package and license
                                                        information which should be used in favor of the online
                                                        version. This option can be used to override the license type
                                                        of packages that e.g. specify the license as file.
  -d, --license-information-download-location <d>       When set, the application downloads all licenses given using a
                                                        license URL to the specified folder.
  -o, --output <Json|JsonPretty|Markdown|Table>         This parameter allows to choose between tabular and json
                                                        output. [default: Table]
  -err, --error-only                                    If this option is set and there are license validation errors,
                                                        only the errors are returned as result. Otherwise all
                                                        validation results are always returned.
  -include-ignored, --include-ignored-packages          If this option is set, the packages that are ignored from
                                                        validation are still included in the output.
  -exclude-projects, --exclude-projects-matching        This option allows to specify project name(s) to exclude from
  <exclude-projects>                                    the analysis. This can be useful to exclude test projects from
                                                        the analysis when supplying a solution file as input. Wildcard
                                                        characters (*) are supported to specify ranges of ignored
                                                        projects. The input can either be a file name containing a list
                                                        of project names in json format or a plain string that is then
                                                        used as a single entry.
  -isp, --include-shared-projects                       If set, shared projects (.shproj) will be included in the
                                                        analysis. By default, shared projects are excluded.
  -f, --target-framework <f>                            This option allows to select a Target framework moniker
                                                        (https://learn.microsoft.com/en-us/dotnet/standard/frameworks)
                                                        for which to analyze dependencies.
  -fo, --file-output <fo>                               The destination file to put the validation output to. If
                                                        omitted, the output is printed to the console.
  -file-mapping, --licensefile-to-license-mappings      File in json format that contains a dictionary to map license
  <file-mapping>                                        files to licenses.
  -?, -h, --help                                        Show help and usage information
  --version                                             Show version information

As you can see the usage section could be left out without issues and can be misleading, as the calling tool name is not correct.

I think the usage section should either use args[0] as the tool name or at the minimum allow the usage section to be omitted....

[KalleOlaviNiemitalo]

Why not rename the executable to match the tool command name?

[sensslen]

That's all done by the dotnet pack command. It creates a nuget package that is then pubished to nuget.org. I'd have to explicitely add rename tasks to the pack command.

Renaming would therefore require extra effort. Also if someone decides to rename the executable after distribution the same problem occurs again. Even worse: if someone creates a link with a different name.

All that to say renaming the tool would maybe resolve some of the pain but certainly not fix the problem entirely.

[KalleOlaviNiemitalo]

I'd have to explicitely add rename tasks to the pack command.

Or just set the AssemblyName property in the project?

[baronfel]

In general an app can be renamed though - think of tools like busybox that change their entire behavior based on how that are invoked.

I think it's entirely reasonable that the Help output could be sensitive to this - the .NET tool expression of an app and the compiled and separately distributed binary version of that app need not have the same 'names'.

[KalleOlaviNiemitalo]

Might be blocked by dotnet/runtime#101837

[sensslen]

Is there a reasonable way to hide the usage section? That would be an elegant workaround for my use case

[KalleOlaviNiemitalo]

There used to be, but it was removed in the API simplification.

[sensslen]

There used to be, but it was removed in the API simplification.

Well - that's not good news then....