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

51–60 of 253 posts

Re: 12 Factor CLI Apps

#51

Post by Beowolve »

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 basic *nix knowledge, much less knowledge of a terminal. The reality of the situation is that a business is going to hire people regardless of that ability. They want someone who can move the features out the door. Whether this is good or bad is probably beyond this conversation. I think, for those users, these sorts of helpful hints are extremely important because it makes them feel like they aren't stuck and helpless. I think that, to your point, it may be useful to have the CLI offer a "pro" mode in which you could set a config to not give you as verbose error messages. Annoying? Yes. However, it would strike a balance and serve both needs.

Re: 12 Factor CLI Apps

#52

Post by colemickens »

ynezz wrote: post #33
colemickens wrote: post #27

Earlier quoted context omitted.

The best part is that some people think 'brew' is a solid package manager and then show up in Linux and try to make 'linuxbrew' happen (no really, it is a thing). I just wish everyone would take a day and read an intro to nix/nixpkgs and the world would really be a better place. There are so many "popular" hyped tools these days that can barely do a fraction of what is going on in the Nix ecosystem, but it doesn't se…

> hype that brew, buildkit, linuxkit, etc all seem to get I'm not that much in devops/containers guy, bit I'm not aware about linuxkit alternative in the Linux world, care to elaborate?

As my comment implies, nix and nixpkgs can do what `linuxkit` does (in terms of image building, at least) but better and in a more powerful manner.

I can create nix derivations that look like a linuxkit yaml, but instead of having a bunch of opaque sha256 hashes to some container in them, it has symbolic references to packages that are defined in my nixpkgs repository. This nixpkgs repository includes package definitions for basically everything in a distribution. From it, out of the box, you can issue single commands to build: VM images, container images, images ready to deploy on GCE/AWS/Azure, all from a single set of package definitions.

This means I can issue a single command that will output a VM image (or a container) that includes the exact revisions of all of my software, down to the kernel options and compiler flags. It makes it trivial to take in patches for critical components and rebuild a base image. No cloning extra repos. No build, container build, push, grab sha256, copy sha256 into a yaml file. Just specify the patch, hit rebuild, done.

You can do this for VM images, specifying the total system configuration - how you want etcd/kubelet/etc running, for example. One command and you have a bootable Azure VHD. You can then use the same tree, or maybe a different branch, and declaratively(!), very minimally [1] build the most optimal container images that you then have deployed to Kubernetes or wherever.

And you can be sure that you can build this exact configuration in 1 year, 2 years, 3 years, etc, due to how Nix works.

I hope I've done a somewhat okay job of explaining this. I'm trying to take some time and write a "container oriented look at why Nix is cool" guide soon too.

[1]: https://grahamc.com/blog/nix-and-layered-docker-images

Re: 12 Factor CLI Apps

#53

Post by jstanley »

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…

I understand what you're saying, but this conversation is about the best way to design CLIs.

I agree that you can do lots of stuff suboptimally and still have a usable tool, but I disagree with the author on what the ideal error output looks like.

Re: 12 Factor CLI Apps

#54

Post by dickeytk »

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 description can and should be long to help clarify what is wrong. It's ok to be verbose. It's ok to spill out on multiple lines. 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. That user can just use `grep -C` anyways.

I agree that it's useful to include the app name though.

Re: 12 Factor CLI Apps

#55

Post by dickeytk »

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…

yes, exactly. I think being verbose and more human friendly is a much better way to design a tool than being terse and machine friendly.

Ultimately all we're doing is trying to save human time anyways.

Re: 12 Factor CLI Apps

#56

Post by colemickens »

3PS wrote: post #38
colemickens wrote: post #27

Earlier quoted context omitted.

The best part is that some people think 'brew' is a solid package manager and then show up in Linux and try to make 'linuxbrew' happen (no really, it is a thing). I just wish everyone would take a day and read an intro to nix/nixpkgs and the world would really be a better place. There are so many "popular" hyped tools these days that can barely do a fraction of what is going on in the Nix ecosystem, but it doesn't se…

Say what you will about Homebrew, but we need more package managers that can easily install without root. Not everyone has the time and energy to compile from source, and often it's a circular problem - I need to compile and install Python 3.7, which needs openssl, which needs to be compiled from source, which has even more dependencies... ad nauseam.

Why do we need more of them when we already have a number that are capable of deploying into a home directory? As someone who has worked on software that has needed packaging, and someone who tries to help out with packaging for a distribution, I can't imagine why we need more for the sake of having more.

Per my original comment, nix can do this, for example and already has an enormous number of packages packed, pre-built/cached, ready to go.

Re: 12 Factor CLI Apps

#57

Post by dickeytk »

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 look and feel 10x better than it is, so it's worth the extra effort.

Re: 12 Factor CLI Apps

#58

Post by andreareina »

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 agree that seeing a bunch of ~/. directories is annoying, but at the same time I do think that it makes sense for each application to manage its own hierarchy, rooted under e.g. ~/.apps/ instead of splitting it into ~/.config/, ~/.local/share/, etc.

Regardless, I think it probably makes sense to have a uniform interface for getting said directories, so that however the OS decides things should be laid out, the developer just needs to `local_config_dir(app_name)`. If the user (or at least administrator) can decide between / and /, all the better.

Re: 12 Factor CLI Apps

#59

Post by gnomewascool »

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, say, README.md gives good-enough results:

pandoc -s -f markdown_github -t man -o your_cli.1 README.md

(There probably are other good conversion methods.)

Why I like man:

Advantage over online docs:

It's offline and available directly in the terminal, without having to open a browser and it has a distraction-free, clean look. The only slight disadvantage is the lack of support for images, which are occasionally helpful, but in a pinch, for some use-cases, you can have ascii diagrams.

Advantages over "--help":

1. Conventionally, "--help" just provides a brief rundown/reminder of the options, so having full documentation is valuable.

2. If "--help" provides the full docs then:

a) You lose the option of having the brief rundown, which is also very valuable.

b) "man command" is slightly faster than "command --help" :p (yes, it is a slight pity that accessing the full docs is faster than accessing the brief version, if you use convention).

c) man deals with things like having nice output, with proper margins, at different terminal widths.

d) man deals with the formatting for you, providing consistency with all other applications.

FWIW I think that texinfo is (mostly) even better than man, as it considerably improves on the navigation, but it's been crippled by the FSF-Debian GFDL feud, which meant that the info pages weren't actually installed on many systems, and it's mostly a lost cause now.

Re: 12 Factor CLI Apps

#60

Post by enriquto »

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.

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!

Post reply on HN