6 ms·

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

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

warrenm 4y ago
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"
andrewfromx 4y ago
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"
- joshSzep 4y ago
  taste?
deleted 4y ago
[deleted]
Someone 4y ago
For guidelines, there also are: - GNU: https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html https://www.gnu.org/prep/standards/html_node/Command_002dLin... - POSIX: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1...
bobbiechen 4y ago
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/ 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 https://github.com/guardrail-dev/guardrail , and Connexion (Python) https://github.com/spec-first/connexion 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.
- digitalsanctum 4y ago
  You've touched on some use cases I've thought about and led me to ask the question. I also recently saw Microsoft take a higher level approach with CADL/Typespec: https://microsoft.github.io/typespec/ https://microsoft.github.io/typespec/ which could be cool if it reaches wide adoption.
yuppie_scum 4y ago
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.
- gabrielsroka 4y ago
  PowerShell has standardized verbs for this very reason. Takes a little getting used to but it's worth it: https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands https://learn.microsoft.com/en-us/powershell/scripting/devel...
hayst4ck 4y ago
Can you go into more detail about the problems you think might be solved?
- digitalsanctum 4y ago
  In the case where the CLI is just using endpoints defined by a single OpenAPI spec, it could be helpful to generate code for the CLI with some minor configuration and/or mapping of commands and args to OpenAPI spec endpoints. More broadly, an enterprise might define how CLIs are created including handling of authentication through such a specification.
  - hayst4ck 4y ago
    It sounds like what you are talking about is a very specific problem for a very specific use case and therefore packaging some piece of software around OpenAPI/whatever ingests its specs is closer to what you think would make the world a better place? cli_from_spec.py seems like a sane program to write. Google ended up using gflags which automatically adds command line arguments to a program as a side effect of code being imported. In this way, using the same library as someone else automatically creates some consistent command line behavior. My take is gflags not only creates side effects but abuses global scope and therefore encourages bad architecture.
ironmagma 4y ago
Because it's an API presenting as a human interface. It's a confused concept altogether.
revskill 4y ago
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.
MathMonkeyMan 4y ago
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".
ezekg 4y ago
I dug around my refs and I was about to recommend https://clig.dev/ 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.com%2Fspf13%2Fcobra+path%3A*.go+NOT+kubernetes https://cs.github.com/?scopeName=All+repos&scope=&q=github.c... [0]: https://github.com/spf13/cobra https://github.com/spf13/cobra
vivegi 4y ago
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.
bradwood 4y ago
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.

warrenm 4y ago

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"

andrewfromx 4y ago

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"

joshSzep 4y ago
taste?

deleted 4y ago

[deleted]

Someone 4y ago

For guidelines, there also are: - GNU: https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html https://www.gnu.org/prep/standards/html_node/Command_002dLin... - POSIX: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1...

bobbiechen 4y ago

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

digitalsanctum 4y ago
You've touched on some use cases I've thought about and led me to ask the question. I also recently saw Microsoft take a higher level approach with CADL/Typespec: https://microsoft.github.io/typespec/ https://microsoft.github.io/typespec/ which could be cool if it reaches wide adoption.

yuppie_scum 4y ago

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.

gabrielsroka 4y ago
PowerShell has standardized verbs for this very reason. Takes a little getting used to but it's worth it: https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands https://learn.microsoft.com/en-us/powershell/scripting/devel...

hayst4ck 4y ago

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

digitalsanctum 4y ago
In the case where the CLI is just using endpoints defined by a single OpenAPI spec, it could be helpful to generate code for the CLI with some minor configuration and/or mapping of commands and args to OpenAPI spec endpoints. More broadly, an enterprise might define how CLIs are created including handling of authentication through such a specification.
- hayst4ck 4y ago
  It sounds like what you are talking about is a very specific problem for a very specific use case and therefore packaging some piece of software around OpenAPI/whatever ingests its specs is closer to what you think would make the world a better place? cli_from_spec.py seems like a sane program to write. Google ended up using gflags which automatically adds command line arguments to a program as a side effect of code being imported. In this way, using the same library as someone else automatically creates some consistent command line behavior. My take is gflags not only creates side effects but abuses global scope and therefore encourages bad architecture.

ironmagma 4y ago

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

revskill 4y ago

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.

MathMonkeyMan 4y ago

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

ezekg 4y ago

I dug around my refs and I was about to recommend https://clig.dev/ 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.com%2Fspf13%2Fcobra+path%3A*.go+NOT+kubernetes https://cs.github.com/?scopeName=All+repos&scope=&q=github.c... [0]: https://github.com/spf13/cobra https://github.com/spf13/cobra

vivegi 4y ago

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.

bradwood 4y ago

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.