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?