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

111–120 of 253 posts

Re: 12 Factor CLI Apps

#111

Post by zbentley »

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

OSX does not automatically delete from that directory. See: https://developer.apple.com/library/archive/documentation/Ge...

> Your app is responsible for cleaning out cache data files when they are no longer needed. The system does not delete files from this directory.

However, many third-party tools delete from that directory with minimal caution if any, so it's a good idea to consider it ephemeral.

Re: 12 Factor CLI Apps

#112

Post by agumonkey »

Already__Taken wrote: post #92
emmanueloga_ wrote: post #29

Don't get me wrong! I love command line apps. But I wonder if we all have a bit of an Stockholm syndrome... there are several things that suck about them... While writing this I'm thinking on my experience trying to do anything with ffmpeg or imagemagick... or even find. * For any sufficiently complicated cmd line app, the list of arguments can be huge and the --help so terse as to be become useless. For man pages, t…

Powershell made 2 things gospel and I'm just sad it's going to take 20 years for other operating systems to realize that's the way to do it and something that replaces linux to see it in practice (i.e. it just won't) 1. Auto-complete is by-design part of the language/shell 1. Pre-approved Verb list that prefix commands helps discoverability and usability no end. Still learning? Get- will literally never cause a probl…

I never really found the verb list to be entirely satisfactory. It's great that they gave boundaries but I find it too verbose. There are other kinds of syntactic ergonomics with concise vocabulary (lisp has ! xxx p$ for instance, they're a bit harder to swallow but I find the code a bit more poetic and easier to remember as a pattern).

About the objects vs strings, Kalman Reti (of Symbolics IIRC) talked [1] about how an OS passing pointers could enjoy a much easier time instead of serializing everything as strings then deserializing, especially when done ad-hoc through sed/grep/perl/whatever .. It pains me to see this. It pains me to see how linux basic utils are 30% --usage, 30% output formatting (and they all share this).

MS did a great thing with PS.

[1] https://www.youtube.com/watch?v=o4-YnLpLgtk

Re: 12 Factor CLI Apps

#113

Post by zbentley »

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.

Regrettably, OSX recommends the use of the Library/Application Support directory, and provides several utility APIs for getting config/cache/data locations which point there as well: https://developer.apple.com/library/archive/documentation/Ge...

In general, if I'm targeting OSX, I use those locations as recommended, but make symlinks to relevant config/etc. from there to the XDG-suggested locations.

Re: 12 Factor CLI Apps

#114

Post by cyphar »

dickeytk wrote: post #54
jstanley wrote: post #48

> 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 w…

A few things to unpack here. First, this is just an example. A real world scenario would be something domain specific. Maybe I could come up with a better contrived example here. Still, conceivably the app could check the file owner before showing the message. If it was a common enough error, it might be useful to do something like this. There is a difference between an error title and error description. The descript…

The example provides the same error information three times ("EPERM", "Invalid permissions on myfile.out", "Cannot write to myfile.out, file does not have write permissions"), followed by a recommendation that might not be correct.

Yes, this is an example, but surely you'd want an example that shows the strength of doing this verbosely? A good example of a verbose error message system is Rust's compiler output (or newer clang/gcc outputs). Being verbose for no reason other than to be verbose is just wasting the users' time (or they just ignore the spam -- which is what I would do if I used a tool that spammed me with multiple lines of output whenever it hit an -EPERM).

Personally, something like:

  % foo ./bar
  foo: write config to "./bar": Permission denied
Is clearer to me than your example. Maybe something like

  % foo ./bar
  foo: write config to "./bar": Permission denied
  Hint: Have you tried ?
Is sometimes okay (and I have done this for my own projects as well), but it's something that should be done in moderation...

> You're much more likely to be helpful to a confused user than someone grepping logs and looking for terse output on a single line.

There are two sides to this. Outputting lots of text can also cause a user to get confused (if we're talking about making things easy for not-necessarily-technical users).

When teaching (high-school) students to program, we quickly learned that even somewhat verbose output like Python's stacktraces can cause students to suddenly become anxious because there's a pile of text on their screen telling them they did something wrong. Adding more text to output does not always help, and you should keep that in mind.

Re: 12 Factor CLI Apps

#115

Post by ibotty »

jwilk wrote: post #87
ibotty wrote: post #62

Earlier quoted context omitted.

I prefer a well-written man page to any other information. Git (and a few others) do open the man page when invoking `--help`. That's a way to avoid some overhead.

I hate when programs do that. When I type "foo --help", I want concise help message for foo. If wanted foo man page, I would have typed "man foo".

man pages can include concise usage examples as well.

Re: 12 Factor CLI Apps

#116

Post by IcePic »

Beowolve wrote: post #51
jstanley wrote: post #48

> 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 w…

So, I understand the basis of your comment. You have the knowledge to know that there are other things that may be "the right way" given your situation. I think what the author is getting at is that there are users who don't have that knowledge. Giving them a hint that is verbose and non arcane can make a world of difference. Speaking from personal experience, there are many developers that I have met who don't have…

Then again, on a recent linux system, the non-ability to write to the file might be permissions. Or an immutable attr, or selinux, or apparmor, or setfacl flags or a RO mount where it lies. As soon as you decide to print out the solution to "can't write to: X" you are in for a page full of advice on what to look for. Perhaps the disk was full, perhaps uid was wrong, perhaps the 5% reserved-for-root-only kicked in. You'd end up writing a unix sysadmin guide, and then perhaps the parent dir had too strict perms to allow you to write to a file in it...

Re: 12 Factor CLI Apps

#117

Post by larkeith »

emmanueloga_ wrote: post #29

Don't get me wrong! I love command line apps. But I wonder if we all have a bit of an Stockholm syndrome... there are several things that suck about them... While writing this I'm thinking on my experience trying to do anything with ffmpeg or imagemagick... or even find. * For any sufficiently complicated cmd line app, the list of arguments can be huge and the --help so terse as to be become useless. For man pages, t…

> Sometimes I end up passing the help output through grep, then copy-pasting the flags from the output, and then hoping I got the right flag.

  man x | grep -P y -C 3 | less
...is my standard here (-C 3 includes the pre- and succeeding 3 lines). For all the delights of CLIs, man pages are by default opaque walls of text. And dear lord the number of regex variants... - at this point, if at all possible, I'll avoid application-specific flavours entirely, and just pipe to grep -P (perl-style regex).

I might suggest, however, that image/video manipulation is a case for which CLIs are uniquely unsuitable.

There surely are better ways (as you mentioned, Powershell appears to be a step or three in the right direction, though I have little familiarity with it), but it seems as though the greatest difficulty is in maintaining full backwords compatibility, while still encouraging new applications to make full use of novel features - not to mention the effort of modifying old applications to fit new standards that would need be expended.

Re: 12 Factor CLI Apps

#118

Post by pleasecalllater »

tajen wrote: post #65
forkerenok wrote: post #40

Earlier quoted context omitted.

Speaking for myself of ffmpeg and imagemagick, I don't find the CLI itself difficult, I find that their application domain is a bit complicated for a layman. Meaning I usually struggle to comprehend what particular options mean rather than how they bind to CLI. Maybe indeed a good intuitive UI would give more intuition about the more obscure options. But then again, a good intuitive UI is a quest of its own.

What is difficult with ffmpeg is the sub-language in each argument, which depends on the filter you’re using. I can learn to lookup the manual, but if I have to go to the internet to learn the syntax of the filter, I’m better off googling my usecas.

And using multiple filters in one call is even more funny. Getting the output and parse it too, as it can be different in different versions and it's terribly inconsistent between filters.

Re: 12 Factor CLI Apps

#119

Post by larkeith »

davidhcefx wrote: post #89
kolme wrote: post #84

Earlier quoted context omitted.

I strongly disagree on this one too. That's the first place I look for help and it annoys me to no end when a CLI program that doesn't come with one. I stopped taking seriously the article at that point and quickly skimmed through the rest of it. Man pages are a great unix culture heritage, please new developers don't give up on them!

I myself also love reading man pages, but speaking of compatibility, I have to say that “--help” is a more universal way of showing help pages. Of course it’s better to have both of them though.

--help is fine, but almost never a substitute for a full man page, except for the most trivial of applications (unless your --help is as complete as a man page, in which case... good on you for providing full documentation, but I'll hate you a bit every time I unthinkingly drop two hundred lines of text in my terminal.)

Re: 12 Factor CLI Apps

#120

Post by oblio »

bayindirh wrote: post #85

I don't agree with 7 and 8. I like silent apps while working, and actually I'm used to applications saying nothing if everything is correct. Also, "outputting something to stdout just because I can" kills scriptability a lot. Using tables, colors and other stuff requires a lot of terminal support. MacOS terminal, iTerm, Linux terminals supports a lot of stuff, but not always (our team is generally using XTerm for exa…

You can just have a "quiet" mode for scripting. Or even better, detect if you're connected to a TTY.
Post reply on HN