Ask HN: Why is there no specification for Command Line Interfaces?

PowerShell does this for .NET, doesn't it?

By "CLI" do you mean "shell interpreter/environment"?

Or do you mean "command-line interface for a given tool"

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"

For guidelines, there also are:

- GNU: https://www.gnu.org/prep/standards/html_node/Command_002dLin...

- POSIX: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1...

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.

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).

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.

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: https://click.palletsprojects.com/en/8.1.x/parameters/

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) https://github.com/guardrail-dev/guardrail , and Connexion (Python) https://github.com/spec-first/connexion .

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.

This x1000

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.

Can you go into more detail about the problems you think might be solved?

Because it's an API presenting as a human interface. It's a confused concept altogether.

Just like: there's no specification for function parameters and results.

Specification is too strict in this case, so it's less useful than "best practices" which's adapt to a context.

Maybe for the same reason that there's no specification for command line tool stdin/stdout aside from "text."

Command line arguments are an array of null-terminated strings, as is the environment (at least there we have the convention "<key>=<value>").

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".

I dug around my refs and I was about to recommend https://clig.dev/, 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:

- https://cs.github.com/?scopeName=All+repos&scope=&q=github.c...

[0]: https://github.com/spf13/cobra

Well, in a sense there is a spec, at the lowest level.

As an example, for a C program you have

    int main(int argc, char **argv) 
    {
        ...
    }

From there, it is just conventions on what the arguments mean.

Same reason there is no specification for GUI interfaces.

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.