Command-line-api: [feature] Add the ability to dump all commands and parameters to a json file

[KathleenDollard]

This was requested of the .NET CLI https://github.com/dotnet/cli/issues/10673. I feel it is needed across enough CLI's to warrant consideration as a feature of System.CommandLine. Key part is marked.

"Regarding the CLI docs published here: https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet?tabs=netcore21

One thing that will help us get docs published easily for CLI reference is if we can _dump the whole list of commands, descriptions, option/mandatory status, parameters list, etc_. This way we can easily diff between releases to see what has changed. It will also allow us to automate the documentation!

It's very troublesome to update the CLI ref which is literally a copy/paste of output from running the commands by hand..."

[jonsequitur]

This is a great idea. I would imagine implementing it as a directive. What would we expect the output format(s) to look like? Plain text seems clear. Would Markdown be useful?

Does it relate to another thing we've discussed which is being able to serialize and deserialize a parser grammar? Both could be used for example for ApprovalTest-style testing.

[Thraka]

I don't think you should output to a specific "style" like markdown, html, plain text. It should be a structured data file like .json. This way, the capabilities the cli reports can be consumed and transformed into whatever is needed for publishing docs.

I first discovered that the azure x-plat cli (defunct now) would output a file like this by calling
azure.exe --output-help or something like that. I wrote a tool that spun up a razor engine that would consume the commands.json file and then spit out multiple individual .md files to doc each command.

Lets say a year later the doc platform changes and instead of individual files per command are no longer allowed and we have to use one giant file, all we need to do is change our razor template, output the latest commands.json from dotnet.exe --output-help, and run the tool. Now it builds out the required .md files in the approved format for our docs system.

So a data file of some sort is the most flexible. Heck, a tool like that could be used as part of the build system too and you can auto generate the docs on each build.

[oising]

I was going to log a separate issue for my idea, but this one seems close enough - there really should be a common parameter to dump the parameters to _stdout_ as json. This would let powershell / powershell core's command line completion to query any binaries and provide tab completion very easily with a custom completer.

See this for more information.
https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/register-argumentcompleter?view=powershell-6

If this could make your 1.0 milestone, you'd seriously aid in adoption if this library would enable rich tab completion for powershell/pwsh, as anyone who used it would gain tab completion without any work at all. Currently you'd have to reigster your own completer. But for this, pwsh/powershell could ship with a built-in dotnet/command-line-api completer that need only register the exe name (as we cannnot know ahead of time which exe uses your lib) instead of struggling with figuring out the parameters.

[jonsequitur]

For dotnet-suggest we have a generalized completer that works for any app using System.CommandLine: https://github.com/dotnet/command-line-api/wiki/dotnet-suggest. Both PowerShell and bash are currently supported.