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

181–190 of 253 posts

Re: 12 Factor CLI Apps

#181

Post by voltagex_ »

kccqzy wrote: post #72
dickeytk wrote: post #46

Earlier quoted context omitted.

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/

https://manpages.debian.org/ffmpeg (or whatever package) is good, too.

Re: 12 Factor CLI Apps

#182

Post by JdeBP »

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.

Erroneously naming it "XDG-spec" is not very good, though. It is the "XDG Base Directory Specification", just one of several XDG specs.

* https://freedesktop.org/wiki/Specifications/

* https://standards.freedesktop.org/

Re: 12 Factor CLI Apps

#183

Post by IcePic »

dickeytk wrote: post #103
dkersten wrote: post #102

Earlier quoted context omitted.

Its easier to google a terse one-line error than a multi line error.

That's what the error code is for

IBM does that, some ANS4543 code that is the real error, _then_ a possibly translated-to-your-language error sentence that tries to help you, but if it isn't enough, you google for the error code and can potentially find help regardless of what language the blog post is in, or the forum link or whatever.

Re: 12 Factor CLI Apps

#184

Post by scbrg »

Riverheart wrote: post #142
scbrg wrote: post #104

Earlier quoted context omitted.

I see no benefit whatsoever to web docs over man pages. man pages are immediately available, where you are (the CLI) without an internet connection or a web browser. I expect the -h flag to give me a summary of the flags and arguments, to remind me of the particular name of the flag I'm missing. I most certainly don't want the whole documentation there, partly because the whole documentation is (presumably) large eno…

In my limited experience, manpages give you a wall of text when 9/10 times you just want a oneliner example of how to do something. Web resources generally address the lack of real world examples in manpages.

Then you use your pager's search functionality and go to the EXAMPLES section. If there is no EXAMPLES section, that's not the fault of the format, but of the author. Presumably, the same author would be equally good (or bad) at providing examples no matter if the target format was a man page or a web page.

Re: 12 Factor CLI Apps

#185

Post by lzybkr »

Klathmon wrote: post #174
felixfbecker wrote: post #153

Earlier quoted context omitted.

What do you mean by aggressive?

I don't know what they mean, but I know that I really dislike how PS's autocomplete works. If the possible commands are (for the sake of discussion) `Get-AppLockerFileInformation` and `Get-AppLockerPolicy`. If you type `Get-App` and hit Tab, it will autofill to `Get-AppLockerFileInformation` which I just really don't like, and I need to keep hitting tab to cycle through all other possible `Get-App*` commands. What I…

With PSReadLine, you can change that:

  Set-PSReadLineOption -EditMode Emacs
Or

  Set-PSReadLineKeyHandler -Key Tab -Function Complete

Re: 12 Factor CLI Apps

#186

Post by JdeBP »

IcePic wrote: post #183
dickeytk wrote: post #103

Earlier quoted context omitted.

That's what the error code is for

IBM does that, some ANS4543 code that is the real error, _then_ a possibly translated-to-your-language error sentence that tries to help you, but if it isn't enough, you google for the error code and can potentially find help regardless of what language the blog post is in, or the forum link or whatever.

Indeed, on OS/2 one didn't google for the error code. One used the HELP command, one of whose modes of operation was looking up and printing the short and long message texts for such codes. The latter would often contain both EXPLANATION and ACTION parts.

    [C:\]help sys0003 
    SYS0003: The system cannot find the path specified. 
    EXPLANATION: The path named in the command does not 
    exist for the drive specified or the path was 
    entered incorrectly. 

    [C:\]help sys0002
    SYS0002: The system cannot find the file specified.
    Explanation: The filename is incorrect or does not exist. 
    Action: Check the filename and retry the command.

Re: 12 Factor CLI Apps

#187

Post by gambler »

dsr_ wrote: post #164
AnIdiotOnTheNet wrote: post #147

Earlier quoted context omitted.

At this point I'm not really sure what makes command-line so great. We should have something like it in the GUI sapce that works much better but, like you said, "stolkholm syndrome". Why can't a pipeline be a more complicated multi-io workflow? In a 2D GUI this would be trivial to construct and read, but in a 1D command line it would get confusing in a hurry. And the concept works much better with AV, I can easily co…

Text is exact, programmable, repeatable and transmissible. exact: in many GUI tools, you can have non-default settings that you changed via menus. Where are they stored? Which ones are currently active? Does it matter that you selected four objects first, then a transform tool, then another object? programmable: > find /var/spool/program/data -name foop* -mtime +3d -print vs "open the file manager, go to /var/spool/p…

Command line is not the only HCI that can use text. Also, no one (except immense mental inertia) stops developers from producing serializable graphical interfaces.

Re: 12 Factor CLI Apps

#188

Post by boomlinde »

jessaustin wrote: post #133
JepZ wrote: post #121

> 7. Prompt if you can Please don't. There is nothing wrong with interactive tools, but by default, they should not be. So instead of making non-interactive session possible via flags, the default should be to be non-interactive. If there is an option to start an interactive session, everything is fine. Otherwise, you would never know when your script could run into some kind of interactive session (and therefore bre…

My interpretation was that the prompt is for required information. In the example graphic, "run demo" really does require that "stage" be specified. This is considered more user-friendly than simply crashing. If you don't want to see the prompt, provide that information as a flag or in a config file or whatever.

User friendly until the user decides to invoke that command in a cron job and ends up with a headless process waiting for additional input.

Re: 12 Factor CLI Apps

#189

Post by jessaustin »

andrewla wrote: post #169
jessaustin wrote: post #133

Earlier quoted context omitted.

My interpretation was that the prompt is for required information. In the example graphic, "run demo" really does require that "stage" be specified. This is considered more user-friendly than simply crashing. If you don't want to see the prompt, provide that information as a flag or in a config file or whatever.

> This is considered more user-friendly than simply crashing (I'm going to assume the passive voice means "the article considers this more user-friendly" rather than some sort of commonly accepted fact). I disagree with this strongly and agree with the GP -- I would much rather have the command exit with a message saying that a required parameter is missing. For example, if I have a script using a command and the com…

So you want the script to [EDIT:] exit with an error code rather than hanging around waiting for input? That seems possible, with some sort of generous (e.g. 5 minutes) exit timer on the prompt. Would that satisfy your concerns? If not, what else is needed here?

ps. the verb "considered" is a good sign that this is an opinion, and would be even in a more "active" sentence.

Re: 12 Factor CLI Apps

#190

Post by kurtisc »

>Still, you need to be able to fall back and know when to fall back to more basic behavior. If the user’s stdout isn’t connected to a tty (usually this means their piping to a file), then don’t display colors on stdout. (likewise with stderr)

GCC does this, leading to no colour output where it would be useful if you're building with Google's Ninja-build. Maybe there are some people who do pipe GCC output to a file - I've never had to. If you do this with your app, I'd appreciate being able to re-enable the colour.

Post reply on HN