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

41–50 of 253 posts

Re: 12 Factor CLI Apps

#41

Post by therealjumbo »

dickeytk wrote: post #19
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.

The fact they don't run on windows means some subset of your users cannot even use them if they wanted to. Better to spend your time on something they can all read. I'm not saying they're not useful. If you've got plenty of time to write up docs, go ahead, but the reality is we only have so much time and I think we should spend our time writing in-CLI docs and web docs before we start man pages. Also, you don't need…

For man pages you could suggest writing markdown and using a build process to automatically generate man pages [1] in the event they aren't using oclif. EDIT: I think we've all been in areas without network access like on a plane and not having a man page in that scenario is very annoying.

Also, you briefly say a few things about CLI apps using a remote API, you may want to add to that and say a few things about the proxy environment variables [2]. These are indispensible for corporate users. I think some early, early version of npm didn't respect the no_proxy environment variable, and for the http_proxy and https_proxy it required some arcane combination of: proxy in a flag, proxy in a config file, proxy environment variable set. It really should be an OR not an AND...

Last but not least, another annoying thing was tools changing their config format or location. I think it was docker that changed their config file format and/or location like two or three times. Absolutely infuriating.

1. https://rtomayko.github.io/ronn/ronn.1.html

2. https://wiki.archlinux.org/index.php/proxy_settings

Re: 12 Factor CLI Apps

#42

Post by OJFord »

> 12. Follow XDG-spec

I'm so glad to see this included. I don't like $HOME being cluttered with . config directories, but worse than that, far too many when releasing on macOS say Oh Library/Application\ Support//vom/something is the standard config location on Mac, so I'll respect XDG on Linux but on Mac it should go there. No! Such an unfriendly location for editable config files.

Re: 12 Factor CLI Apps

#44

Post by dickeytk »

therealjumbo wrote: post #41
dickeytk wrote: post #19

Earlier quoted context omitted.

The fact they don't run on windows means some subset of your users cannot even use them if they wanted to. Better to spend your time on something they can all read. I'm not saying they're not useful. If you've got plenty of time to write up docs, go ahead, but the reality is we only have so much time and I think we should spend our time writing in-CLI docs and web docs before we start man pages. Also, you don't need…

For man pages you could suggest writing markdown and using a build process to automatically generate man pages [1] in the event they aren't using oclif. EDIT: I think we've all been in areas without network access like on a plane and not having a man page in that scenario is very annoying. Also, you briefly say a few things about CLI apps using a remote API, you may want to add to that and say a few things about the…

Oh believe me. I'm intimately familiar with proxies and CLI apps. I think that might be a good standalone article though as it only applies to CLIs that connect to APIs whereas this article is intended for all CLIs, period. (Minus that note about the user-agent I suppose).

We get away without using any config files in the Heroku CLI which is certainly preferable. (Well, there is a config file, but I don't think anyone's using it and it's undocumented. I think all it can do is disable colors) Config is another topic that I do think would warrant its own article as well. I may not be the best author though as we've tried to avoid config. (Though it's a common enough problem I do want to solve generically as possible in oclif).

As far as automatically building man pages, I still think that's a wasted effort. Nobody has ever asked for or even mentioned man pages in our CLI. Setting up a build process and distribution is considerable effort and maintenance burden.

Of course if the users of your CLI want man pages then of course build them. In my experience though, that's not what users want. Though it's important to note that a CLI that interacts with a cloud service is pretty useless without internet.

If no internet is the only compelling reason to support man pages, I'm still not convinced it's a better use of your time. The docs should already be available offline in the CLI itself.

Re: 12 Factor CLI Apps

#45

Post by dickeytk »

OJFord wrote: post #42

> 12. Follow XDG-spec I'm so glad to see this included. I don't like $HOME being cluttered with . config directories, but worse than that, far too many when releasing on macOS say Oh Library/Application\ Support/ /vom/something is the standard config location on Mac, so I'll respect XDG on Linux but on Mac it should go there. No! Such an unfriendly location for editable config files.

I am having an impossible time verifying this, but I recall reading that MacOS deletes unaccessed files eventually from `~/Library/Caches/*`. Which would be a compelling reason to use that for cache. (Not being able to verify this I didn't add it to the article)

If anyone can verify that I'm either right or wrong here that would be helpful.

Re: 12 Factor CLI Apps

#46

Post by dickeytk »

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.

Re: 12 Factor CLI Apps

#47

Post by tetha »

dickeytk wrote: post #16
breckuh wrote: post #14

> 1. Great help is essential I like how this is their #1. In my opinion the best way to do this is with tldr. https://github.com/tldr-pages/tldr I'd highly recommend folks create a tldr page for their CLI app. Add 4-8 examples to cover 80%+ of the most common use cases. -h flags, readmes & man pages can cover the other 20%.

I almost want to rewrite the help section to encourage examples even more. They're incredibly valuable. I hadn't considered this before you mentioned it, but oclif CLIs could integrate to tldr pretty well. It already supports arrays of strings for examples.

Yup. On CPAN, it is encouraged that the first part of your documentation after the table of contents is the synopsis[1]. The synopsis should clearly show how to do the common tricks with the library. From there you can link and refer to the more detailed documentation.

We're doing that for our internal CLI applications and it's great to be able to just copy-paste the common use case from the top of the documentation without searching much.

1: https://metacpan.org/pod/Carp

Re: 12 Factor CLI Apps

#48

Post by jstanley »

> Error: EPERM - Invalid permissions on myfile.out

> Cannot write to myfile.out, file does not have write permissions

> Fix with: chmod +w myfile.out

I actually much prefer:

"can't write myfile.out: Permission denied"

This shows the same information as the first 2 lines combined from the example, and the 3rd line is not necessarily the correct way to fix the problem anyway (e.g. you might be running it as your user when it should be root, chmod +w would not help).

If you are so convinced that chmod +w is the way to fix the problem, why not just do that and carry on without bugging the user?

And having each error confined to one line also means it's much less likely that some of the lines are missed, e.g. when grepping a log.

EDIT: And to add to this: it's sometimes useful to prefix the error messages with the name of the program that generated them, so that when you're looking at a combined log from different places, you know which of the programs actually wrote the error, e.g. "mycli: can't write myfile.out: Permission denied".

Re: 12 Factor CLI Apps

#49

Post by dickeytk »

tetha wrote: post #47
dickeytk wrote: post #16

Earlier quoted context omitted.

I almost want to rewrite the help section to encourage examples even more. They're incredibly valuable. I hadn't considered this before you mentioned it, but oclif CLIs could integrate to tldr pretty well. It already supports arrays of strings for examples.

Yup. On CPAN, it is encouraged that the first part of your documentation after the table of contents is the synopsis[1]. The synopsis should clearly show how to do the common tricks with the library. From there you can link and refer to the more detailed documentation. We're doing that for our internal CLI applications and it's great to be able to just copy-paste the common use case from the top of the documentation…

I feel the synopsis section of man pages often just becomes a bunch of useless garbage above the fold (for instance, look at `man git`).

Using it less as a complete docopts kind of thing and more of multiple common usages (like `man tar` and what you linked) is far more useful.

I think there is something here I hadn't really considered before. It's not an example, but also not a useless dump of flags. Food for thought I suppose.

Re: 12 Factor CLI Apps

#50

Post by hornetblack »

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.

Post reply on HN