> Don’t bother with man pages. We believe that if you’re following these guidelines for help and documentation, you won’t need man pages.
I disagree strongly in all but exceptional cases. These exceptions would still benefit from a bare-bones man page with the most common options and a handful of examples of common usage.
> Traditionally, UNIX commands were written under the assumption they were going to be used primarily by other programs [...] it’s time to shed some of this baggage
UNIX commands are absolutely human first. If they weren't then the `ls` command would output a JSON PROTOBUF ASN.1 SQL DUMP rather than a plaintext list of file names.
> Use a command-line argument parsing library where you can
What you're doing a good job of here, is granting a loudspeaker to all the fresh community projects and excitement surrounding CLI. That's awesome. It's not appropriate for a best practices document, which should be making much more conservative recommendations, considering how prevalent arg parsers are in the standard libraries of languages.
> you won’t need man pages. Not enough people use man pages
If your program is something that's installed on the system (i.e. it's not distributed as a single-file executable like youtube-dl) then it should have a man page.
> Display output on success
Very unconventional advice. Strongly disagree.
> Disable color if your program is not in a terminal or the user requested it.
Now this, is something that contradicts the conventional wisdom, but I wholeheartedly agree with it. I don't like playing cat and mouse games with commands that conditionally turn colors off based on isatty(). I just want color. If I didn't want color, then it's so trivial to filter it out using sed 's/\x1b\[[;[:digit:]]*m//g'.
> The NO_COLOR environment variable is set.
Or more conventionally, TERM=dumb or the sed above. Never heard of NO_COLOR before.
> You may also want to add a MYAPP_NO_COLOR environment variable
This can be seen as environment variable pollution. Those strings need to be copied every time a process is spawned. Many of the C library routines for editing the environment are O(n) unfortunately because you can't assume it's sorted like they are on Windows.
> Only use prompts or interactive elements if stdin is an interactive terminal
Bad advice. Many programs like ispell / aspell / etc. are interactive in nature while being used primarily through pipes as a subprocess. The best advice I can give is to just never ever check if it's a tty because it doesn't matter. Just make your program behave the same regardless of environmental conditions. Otherwise it's a huge pain to automate, and that which can't be automated isn't worth doing as a cli program.
> Responsive is more important than fast. Print something to the user in <100ms
That's a low bar even for a web server. It takes 25 microseconds to launch a subprocess and wait for it to complete. That's the lower bound imposed by the practicalities of the Linux implementation of a vfork->execve->exit->wait4 roundtrip, which abstracts a heroic amount of work under the hood and decades of effort at improvements. So if you can't get your CLI program to do something within at least 100 microseconds, then you've got a serious problem with bloatware or third party telemetry and should seriously reconsider your language/library/tooling stack.
> TERM, TERMINFO and TERMCAP, if you’re going to use terminal-specific escape sequences.
That was good advice two decades ago. Just use the VT100 codes. Even Windows CMD.EXE supports VT100. Don't bother with the termcap thing unless you're trying to support like WYSE terminals or actual teletypewriters. Here's the dox on the subject: https://github.com/jart/cosmopolitan/blob/1fc91f3/tool/build...
> If a user hits Ctrl-C during clean-up operations that might take a long time, skip them. Tell the user what will happen when they hit Ctrl-C again, in case it is a destructive action.
Not worth prompting. Just kill it if you ctrl-c twice. I mean, if you're going to leave database objects in an inconsistent state, I mean then don't stop unless someone runs kill -9 or pulls the power plug. But vast majority of cases, stuff can be interrupted, trust the user, the prog should not whine.
> People are going to misuse your program. Be prepared for that. They will wrap it in scripts
You must really hate people like me. I've been using Unix for 23 years and I'm barely a newcomer. I like it because it lets me automate things. If a command line program treats me like a user, rather than being a tool to be used, then I won't touch it.
> Don’t bother with man pages. We believe that if you’re following these guidelines for help and documentation, you won’t need man pages.
I disagree strongly in all but exceptional cases. These exceptions would still benefit from a bare-bones man page with the most common options and a handful of examples of common usage.
These seem like very vague general points. For more concrete rules, see the GNU Coding Standards for Command Line Interfaces:
https://www.gnu.org/prep/standards/standards.html#Command_00...
Recent discussion at https://news.ycombinator.com/item?id=25304257
This was very helpful. I am writing my own Python command line tool, and this provides a clear guideline.
> Traditionally, UNIX commands were written under the assumption they were going to be used primarily by other programs [...] it’s time to shed some of this baggage
UNIX commands are absolutely human first. If they weren't then the `ls` command would output a JSON PROTOBUF ASN.1 SQL DUMP rather than a plaintext list of file names.
> Use a command-line argument parsing library where you can
What you're doing a good job of here, is granting a loudspeaker to all the fresh community projects and excitement surrounding CLI. That's awesome. It's not appropriate for a best practices document, which should be making much more conservative recommendations, considering how prevalent arg parsers are in the standard libraries of languages.
> you won’t need man pages. Not enough people use man pages
If your program is something that's installed on the system (i.e. it's not distributed as a single-file executable like youtube-dl) then it should have a man page.
> Display output on success
Very unconventional advice. Strongly disagree.
> Disable color if your program is not in a terminal or the user requested it.
Now this, is something that contradicts the conventional wisdom, but I wholeheartedly agree with it. I don't like playing cat and mouse games with commands that conditionally turn colors off based on isatty(). I just want color. If I didn't want color, then it's so trivial to filter it out using sed 's/\x1b\[[;[:digit:]]*m//g'.
> The NO_COLOR environment variable is set.
Or more conventionally, TERM=dumb or the sed above. Never heard of NO_COLOR before.
> You may also want to add a MYAPP_NO_COLOR environment variable
This can be seen as environment variable pollution. Those strings need to be copied every time a process is spawned. Many of the C library routines for editing the environment are O(n) unfortunately because you can't assume it's sorted like they are on Windows.
> Only use prompts or interactive elements if stdin is an interactive terminal
Bad advice. Many programs like ispell / aspell / etc. are interactive in nature while being used primarily through pipes as a subprocess. The best advice I can give is to just never ever check if it's a tty because it doesn't matter. Just make your program behave the same regardless of environmental conditions. Otherwise it's a huge pain to automate, and that which can't be automated isn't worth doing as a cli program.
> Responsive is more important than fast. Print something to the user in <100ms
That's a low bar even for a web server. It takes 25 microseconds to launch a subprocess and wait for it to complete. That's the lower bound imposed by the practicalities of the Linux implementation of a vfork->execve->exit->wait4 roundtrip, which abstracts a heroic amount of work under the hood and decades of effort at improvements. So if you can't get your CLI program to do something within at least 100 microseconds, then you've got a serious problem with bloatware or third party telemetry and should seriously reconsider your language/library/tooling stack.
> TERM, TERMINFO and TERMCAP, if you’re going to use terminal-specific escape sequences.
That was good advice two decades ago. Just use the VT100 codes. Even Windows CMD.EXE supports VT100. Don't bother with the termcap thing unless you're trying to support like WYSE terminals or actual teletypewriters. Here's the dox on the subject: https://github.com/jart/cosmopolitan/blob/1fc91f3/tool/build...
> If a user hits Ctrl-C during clean-up operations that might take a long time, skip them. Tell the user what will happen when they hit Ctrl-C again, in case it is a destructive action.
Not worth prompting. Just kill it if you ctrl-c twice. I mean, if you're going to leave database objects in an inconsistent state, I mean then don't stop unless someone runs kill -9 or pulls the power plug. But vast majority of cases, stuff can be interrupted, trust the user, the prog should not whine.
> People are going to misuse your program. Be prepared for that. They will wrap it in scripts
You must really hate people like me. I've been using Unix for 23 years and I'm barely a newcomer. I like it because it lets me automate things. If a command line program treats me like a user, rather than being a tool to be used, then I won't touch it.