Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

12 Factor CLI Apps

medium.com

Post reply on HN
Print view View original

71–80 of 253 posts

Re: 12 Factor CLI Apps

#71

Post by gvalkov »

dickeytk wrote: post #57
hornetblack wrote: post #50

Also on Color. Don't got go all pschadelic. I've found that some programs using 256-color is unreadable with my terminal colors. Also unix commands tend to have illegible colors in Powershell on Windows. (Ripgrep for example). Powershell defaults to a blue background.

Yeah if I get some time I should expand on that. There are some colors that don't work well at all for common scenarios (solarized, windows). Some of them we've blacklisted and do not use. Also for colors it's good to try to pick a decent palette of a couple-three colors and stick with it rather than try to categorize a bunch of different bits of output on a single command. Still, colors are awesome and make your CLI…

A problem with color is that people end up optimizing the aesthetics for their own terminal setup. There is a wild number of different color schemes out there and it's really hard to make something that looks good on all of them. In my experience the only safe choice is bold text (i.e. \033[1m) since it stands out in all cases.

Re: 12 Factor CLI Apps

#72

Post by kccqzy »

dickeytk wrote: post #46
stepvhen wrote: post #9

> I would skip man pages are they just aren’t used that often anymore. I understand that man pages might represent a minority, but I cannot express enough how wonderful it is to get the full manual of a program without interfacing with the web. Not to mention how powerful that is, since most apps have short names that are difficult to search for, but how accessible that makes the application.

For people that like man pages (there appears to be lots of you) do you think that man pages are more important than web or in-cli docs? Or just that they should be written in addition to and not missed out on? My (current) position is that they're useful, but not worth the extra effort for most CLIs. It's a cost-benefit thing. I'm genuinely curious as I've never had anyone request man pages in our CLI.

Well, man pages are the standard way to get documentation. Sometimes --help is detailed enough to be a replacement (in which case I can tolerate the lack of man pages), but usually not.

I don't really care about documentation on the web. In fact I'd rather you simply treat the man pages as the single source of truth and put the man pages on the web. Sort of like https://linux.die.net/man/

Re: 12 Factor CLI Apps

#73

Post by sytelus »

Does these CLI features like tables, OS notifications etc work cross-platform (Linux, Windows, OSX)? IS there any good library to develop such CLI apps?

Re: 12 Factor CLI Apps

#74

Post by TeMPOraL »

dickeytk wrote: post #68
enriquto wrote: post #60

Earlier quoted context omitted.

I for one prefer actual manpages than online documentation. The web documentation is cumbersome to find, forces me to open a browser window, and I cannot copy-paste easily from inside my terminal. Notice that if you already have help, you can build the manpages automatically from them using "help2man". You could get manpages for all your tools by simply adding a line into your makefile!

If the man pages are simply generated from the help output, why bother having them when you can just use `--help`?

Because the expectation on UNIX-like systems is that I can type `man foo` and get the manpage for `foo`.

It's good manners for a CLI app you want installed on someone's system to also integrate with the help infrastructure of that system.

Re: 12 Factor CLI Apps

#75

Post by a_e_k »

dickeytk wrote: post #67
gnomewascool wrote: post #59

I almost stopped reading at "I would skip man pages", but the rest of the article was mostly great advice. I disagree about 11 (using "main_command sub_command:sub-sub_command" rather than "main sub sub-sub" syntax), but it's mostly a matter of taste. Seriously, though, if you've already taken the time to write documentation, then there's no reason not to also generate a manpage. Just using pandoc to convert your, sa…

You could have a `--full` or `--verbose` flag on the help command to display the full output. That will work on Windows as well.

One style that I've seen that I really like is having the help system be its own first-class subcommand. E.g., just `p4 help` gives you the quick summary with a list of available subcommands, then something like `p4 help filelog` gives you the details on just the filelog subcommand. I find that this avoids the problem of a having a single help spiel that is either too brief or too verbose to be useful.

(The article sort of touches on this with mention of `mycli subcommand --help` as something that should show help and `mycli subcommand help` as potentially confusing `help` with an argument. But I find that making help a full subcommand tends to avoid avoid this ambiguity. And having the bare help command give the table of contents lends structure to the help system.)

Re: 12 Factor CLI Apps

#77

Post by dickeytk »

gvalkov wrote: post #71
dickeytk wrote: post #57

Earlier quoted context omitted.

Yeah if I get some time I should expand on that. There are some colors that don't work well at all for common scenarios (solarized, windows). Some of them we've blacklisted and do not use. Also for colors it's good to try to pick a decent palette of a couple-three colors and stick with it rather than try to categorize a bunch of different bits of output on a single command. Still, colors are awesome and make your CLI…

A problem with color is that people end up optimizing the aesthetics for their own terminal setup. There is a wild number of different color schemes out there and it's really hard to make something that looks good on all of them. In my experience the only safe choice is bold text (i.e. \033[1m) since it stands out in all cases.

red, yellow, green, cyan, and magenta are pretty safe. We've had complaints about others, but these are pretty reliable in my experience. dim is safe too, but doesn't work all the time. (Not working meaning just not dimmed)

Re: 12 Factor CLI Apps

#78

Post by dickeytk »

a_e_k wrote: post #75
dickeytk wrote: post #67

Earlier quoted context omitted.

You could have a `--full` or `--verbose` flag on the help command to display the full output. That will work on Windows as well.

One style that I've seen that I really like is having the help system be its own first-class subcommand. E.g., just `p4 help` gives you the quick summary with a list of available subcommands, then something like `p4 help filelog` gives you the details on just the filelog subcommand. I find that this avoids the problem of a having a single help spiel that is either too brief or too verbose to be useful. (The article s…

perhaps I should've called this out explicitly, but yes, I would expect a CLI to do this.

I have future plans for oclif to take this a step further and make the help contextual based on what you're working with. For example, if you wanted to see what commands might relate to a file you might get different commands than a directory.

Re: 12 Factor CLI Apps

#79

Post by jwilk »

enriquto wrote: post #63
gnomewascool wrote: post #59

I almost stopped reading at "I would skip man pages", but the rest of the article was mostly great advice. I disagree about 11 (using "main_command sub_command:sub-sub_command" rather than "main sub sub-sub" syntax), but it's mostly a matter of taste. Seriously, though, if you've already taken the time to write documentation, then there's no reason not to also generate a manpage. Just using pandoc to convert your, sa…

> Advantages of man over "--help": You can have the best both worlds if the manpages are built automatically from the "--help" output (e.g., using help2man). Then you can have "-h" give a brief rundown and "--help" give the full docs. > FWIW I think that texinfo is (mostly) even better than man, as it considerably improves on the navigation I am curious about that. Do you really like texinfo navigation? I find it com…

Typographical quality of automatically generated manpages is usually very poor.

Also, I expect man pages to be more detailed than --help.

Re: 12 Factor CLI Apps

#80

Post by enriquto »

TeMPOraL wrote: post #70
enriquto wrote: post #63

Earlier quoted context omitted.

> Advantages of man over "--help": You can have the best both worlds if the manpages are built automatically from the "--help" output (e.g., using help2man). Then you can have "-h" give a brief rundown and "--help" give the full docs. > FWIW I think that texinfo is (mostly) even better than man, as it considerably improves on the navigation I am curious about that. Do you really like texinfo navigation? I find it com…

I use info browser from Emacs and like it very much. The best benefit is that you can stuff a whole book into info pages - and projects using info usually drop their full manual in there, to be perused off-line and distraction-free.

How do you search for a word inside the whole info documentation of a program (say, gcc), and cycle through all appearances of that word? I never managed to do that (which is trivial for manpages).
Post reply on HN