Similar to specifications like OpenAPI, etc. it seems like having something similar for CLIs would be cool. Why isn't there one already? How do you approach stubbing a CLI to interface with one or more APIs?<p>Edit: I forgot to mention the closest thing I've found is: https://clig.dev/ which is the most comprehensive "guide" I've seen to date.
For guidelines, there also are:<p>- GNU: <a href="https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html" rel="nofollow">https://www.gnu.org/prep/standards/html_node/Command_002dLin...</a><p>- POSIX: <a href="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html" rel="nofollow">https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1...</a>
What's the use case? I was thinking about this exact issue because my product ships several CLI tools, but I wasn't convinced it would be worth the effort.<p>An OpenAPI specification describes an HTTP interface, and I see it as useful because it makes it easier to write code in language-of-choice to generate HTTP requests (by generating client libraries from the OpenAPI spec).<p>For a CLI, the interface is the command-line. Usually people type these commands, or they end up in bash scripts, or sometimes they get called from programming language of choice by shelling out to the CLI. So I could see a use case for a CLI spec, which would make it easier to generate client libraries (which would shell out to the CLI)... but it seems a little niche.<p>Or maybe, as input to a documentation tool (like Swagger docs). I would imagine if you're using a CLI library like Python's Click, most of that data is already there. Click Parameters documentation: <a href="https://click.palletsprojects.com/en/8.1.x/parameters/" rel="nofollow">https://click.palletsprojects.com/en/8.1.x/parameters/</a><p>Or maybe, you could start from the spec and then generate code which enforces it. So any changes pass through the spec, which would make it easy to write code (server and client-side) / documentation / changelogs. Some projects like this: Guardrail (Scala) <a href="https://github.com/guardrail-dev/guardrail">https://github.com/guardrail-dev/guardrail</a> , and Connexion (Python) <a href="https://github.com/spec-first/connexion">https://github.com/spec-first/connexion</a> .<p>But without this ecosystem of tooling, documenting your CLI in a specification didn't really seem worth the effort. Of course, that's a bootstrapping problem.
I dug around my refs and I was about to recommend <a href="https://clig.dev/" rel="nofollow">https://clig.dev/</a>, but I see you've already found it. It's a great little reference to have when building a CLI. I typically read the code for other CLIs, particularly those written with the framework I'm using. The last framework I used was Cobra [0], and I studied how others did theirs:<p>- <a href="https://cs.github.com/?scopeName=All+repos&scope=&q=github.com%2Fspf13%2Fcobra+path%3A*.go+NOT+kubernetes" rel="nofollow">https://cs.github.com/?scopeName=All+repos&scope=&q=github.c...</a><p>[0]: <a href="https://github.com/spf13/cobra">https://github.com/spf13/cobra</a>
I think they mean why is it sometimes "./foo --help" vs "./foo -h" or "./thing --other=123 --value=456" but sometimes "./thing -o 123 -v 456"
Maybe for the same reason that there's no specification for command line tool stdin/stdout aside from "text."<p>Command line arguments are an array of null-terminated strings, as is the environment (at least there we have the convention "<key>=<value>").<p>It might be neat to define a schema language together with a validator that takes a schema and a "style" and then validates an array of strings. e.g. "validate gnu myschema.ext -- subcommand --flag -etc --thing=value arg arg".
Just like: there's no specification for function parameters and results.<p>Specification is too strict in this case, so it's less useful than "best practices" which's adapt to a context.
Same reason there is no specification for GUI interfaces.<p>There are trends, and patterns, and conventions in both GUI and CLI design but it's always going to be about the UX, the use case, the target audience, etc.
Well, in a sense there is a spec, at the lowest level.<p>As an example, for a C program you have<p><pre><code> int main(int argc, char **argv)
{
...
}
</code></pre>
From there, it is just conventions on what the arguments mean.
This x1000<p>Especially in the DevOps space, I find one CLI’s “update” will be another’s “apply”, one “delete” will be another “remove“, add/create, etc. It adds excessive cognitive load.
PowerShell does this for .NET, doesn't it?<p>By "CLI" do you mean "shell interpreter/environment"?<p>Or do you mean "command-line interface for a given tool"