Hello fellow nixers!

I'm openning a new thread here to discuss one of the points on the latest newsletter (issue #96) that bothered me: 12 Factor CLI apps.

TLDR: They list 12 points you should follow to make a great CLI app.

I like to see articles like this, that give advice on how to build new CLI tools. This one is a good example as well, but I must say that some points bother me a bit.

There is this point about the "help" feature of your apps, saying that you should offer multiple ways to display the help:

The idea is that as the user can think of all this help commands, you should handle them all.
I disagree here. First of all, it complexify you program, as it forces you to handle edge-cases, for example if you don't make use of long options, or subcommands.
Moreover, it's said that the help text should display common usage example, and detail the options.
This is noisy and unhelpful, especially because they make it look like a manpage, and right after says that manpages are depreciated an unhelpful. because nobody uses them, and that you should use online READMEs for example.
Manpages are the only reliable documentation you can get offline.


The other point that bother me, is the one about errors. It says that the error messages should include the error code, a description, how to fix it and a link to your project.

This is, IMO, a reaaaaaaally bad idea!

The error number is totally useless. It exist so that you can get a description of your error, so if you display the error message itself, then it's not needed.
As for the description, what's the point of:

Quote:sort input --outpout=file.out
file.out: Permission denied
You don't have permission to write to 'file.out'

As for the way to fix it... Meh... That's even more dangerous. You can never know what the environment on which your tool will run.
Imagine that it runs on a read-only file system, or in a place where you shouldn't have right access.
You definitely don't want to tells the users what to do if you don't know the environment.


What about you guys? what do you think?

I find it disturbing to read the term "apps" with "CLI", to be honest.

I do agree with the perception that there often are too many ways to achieve the same goal.


That hurts my brain.

Well I do agree with you that we shouldn't talk about "apps" when it comes to cli tools. But that is a different topic ;)

Few thoughts:

Quote:First of all, it complexify you program, as it forces you to handle edge-cases, for example if you don't make use of long options, or subcommands.

This is basically developer experience vs. user experience. It's true that you probably should not use all of these for simple scripts, but on the other hand, simple scripts don't need to be "great CLI apps". Great software requires great user experience, and handling these common cases is not that complex.

Quote:Moreover, it's said that the help text should display common usage example, and detail the options.
This is noisy and unhelpful

This is completely subjective, but I'm fairly certain that most users greatly appreciate writing out at least the most common use case and few options.

Quote:Manpages are the only reliable documentation you can get offline.

Yes. Luckily --help and man pages are not mutually exclusive. Both is best.

On error messages I mostly agree, though you should probably consider greater detail on more complex cases.

As I see it, --help should only be a reminder for the syntax and available flags.
For example, you would use --help when I'm not sure if the flag to make chmod do recursion is -r or -R.
--help should be clean and easy to read. The detailed usage goes to the manual.

If you buy a chainsaw and have no idea how to use it, you check the manual. If you want a reminder about what a button does, there's the pictogram above it.

I use "chef" at work to auromatize deployments, which has a "knife" command that does not have a manual, so you MUST use their painful embedded help.
You type "knife help" and get rewarded by a wall of text that doesn't even fit on my 1920x1600 monitor.
You run it again through "less", and AH, you forgot to redirect stderr to stdout. 3rd try.
You finally find the subcommand you want, type "knife help subcommand", and get the same wall as before. Because the command is fucking "knife subcommand help", and it's not specified in the previous shitty help.

Trying to provide interactive help is confusing, and all you can do is provide meaningless examples because you don't make full sentences in such help text to describe how it works.
This is what you do in manuals though, which is why they are still relevant and important.
Especially when the manoage includes an EXAMPLE section ;)

As I said in the newsletter, this is sort of the current "hype" of writing cli tools, with ton of prettifier and helpers, and that doesn't follow any of the usual conventions or good practices for writing good cli programs.

(12-10-2018, 01:52 PM)z3bra Wrote: There is this point about the "help" feature of your apps, saying that you should offer multiple ways to display the help:
app
app -h
app --help
app help

Any library that you include to parse command line arguments the standard way won't have that last option and won't show any help on the first option if no arguments are mandatory. That's how much bad practice this is.

(12-10-2018, 07:12 PM)z3bra Wrote: As I see it, --help should only be a reminder for the syntax and available flags.
For example, you would use --help when I'm not sure if the flag to make chmod do recursion is -r or -R.
--help should be clean and easy to read. The detailed usage goes to the manual.

I can't agree more with that one. The help that span on more than a screen size bother me the most because you have to pass them in a pager, so then you're better off reading a manpage.

Maybe I should mention something that has not been said yet. I'm all in with colors for command line tools but they should be disabled by default. Maybe the tool should follow that $NO_COLOR environment too.

As for all the good practices I think we discussed that topic a lot in other places too: https://nixers.net/showthread.php?tid=1893
Some good links that were in that entry of the newsletter that are good to mention are:
http://julio.meroh.net/2013/09/cli-desig...ap-up.html
https://monkey.org/~marius/unix-tools-hints.html
http://www.catb.org/~esr/writings/taoup/html/