Specify how to request an OpenCLI specification from a tool

[cmcgee1024]

OpenCLI can become much more useful as a tool integration if there is a standard way to request from a tool its command structure. For example, a shell autocompletion system might not yet have knowledge of the tool, but if the user invokes it from the system path then it can request the OpenCLI specification from the tool and then provide assistance to the user. In order for workflows like this to work there needs to be a standard method to get the OpenCLI specification from the tool by invoking it.

There is an enormous number of command-line tools and scripts out there, and so the invocation mechanism will need to be unique enough to avoid most collisions with the universe of existing options. Also, the method of invoking the tool to query for an OpenCLI specification will need to be able to cause most tools that do not have OpenCLI specification support to exit with a non-zero exit code. Since there is a possibility of new versions of the specification in the future, this approach should take future versioning into account as well.

One potential approach is to use a globally unique option, specific to OpenCLI, such as --help-opencli, that is also intuitive to use. Future versions can become their own option --help-opencli<version> to permit tools to over different versions of the specification in the future.

[reitzig]

Seconded. Completion generation (my main use case as a user) has a couple of quasi-standards, but in general it's a mess. Just in the half dozen or so of tools I install with mise, I got

• $tool completion
• $tool completions
• $tool --generate-completion
• $tool --gen-completions
• $tool generate-shell-completion

Of course, OpenCLI would just add another quasi-standard, but I would at least expect to cover all adopting tools by one downstream script.

I'd propose to reserve $tool --[generate-]opencli and $tool [generate-]opencli, depending on whether it's a command-ey or option-ey CLI. That should fit in nicely with --version/version and --help/help which are basically standard.

[cmcgee1024]

The Swift Argument Parser project is currently discussing the future of an analogous feature to produce a JSON representation of a tool, called tool info, here: https://forums.swift.org/t/dropping-the-experimental-from-dump-help/82099/5

One suggestion in there is to logically extend the --help pseudo-standard using additional suffixes. For example, --help-hidden can show a variation of the help revealing hidden arguments. Dumping a format and version-specific representation of the help could be something like --help-dump-tool-info-v1.

Following this line of reasoning for OpenCLI might yield something like this:

<tool> --help-dump-opencli-v0.1

[patriksvensson]

I've gone with this convention in my own exporters (for System.CommandLine and Spectre.Console), and it makes sense.

I think it would be helpful though to be able to omit the version number. What do you think @cmcgee1024?

[cmcgee1024]

For type-ability I can see the argument that the version takes an extra 5 keystrokes. But, I suspect that for a json representation that it's probably not very common that users will be typing this out themselves.

I think, especially with a spec that's new and pre-1.0, that there can (and should be) the freedom for significant changes on the road to 1.0. As other languages and arg parsing frameworks come on board will bring their own particular semantics around command-line argument parsing that might change the spec in incompatible ways.

Asserting the version helps to communicate clearly what the client is expecting, a bit like with many REST API's. Introducing versioning right away is easier than adding it later. It also helps to remind everyone that this is on the road to a 1.0, but it's not there yet.

[idle-code]

On the other hand I suspect that there will be far more tools than clients. Wouldn't be easier for the tool to report version of the standard it was build with and make the client adapt?
For example: if the tool reports v2, it might mean that features required for its correct invocation are not supported by v1, therefore v1 client might not support proper completion for it.