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

171–180 of 253 posts

Re: 12 Factor CLI Apps

#171

Post by falcolas »

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…

> I wonder if we all have a bit of an Stockholm syndrome

I used to agree with you on this point, but then came Bender. Chatbots singlehandedly liberated the CLI from the terminal and made them ubiquitous once again.

So yeah, it's not just the terminal where we're creating CLI applications anymore.

Re: 12 Factor CLI Apps

#172

Post by falcolas »

maaaats wrote: post #156
Walkman wrote: post #83

Unless you already know your users will want man pages, I wouldn’t bother also outputting them as they just aren’t used often enough anymore. I don't know where this is coming from, me and my colleagues are reading man pages every day. I would be interested how much others read them.

I never read man pages. If I need to check man, the tool failed in being user friendly. I'll then rather search online for what I need and blindly copy the first result on some stack exchange page..

If you can't immediately figure out how to properly set up and adjust a contractor's table saw, do you blame the table saw for being developed for professional contractors instead of newbies?

User friendlyness is a feature, and like all features it's not always worth adding to professional tools.

Re: 12 Factor CLI Apps

#173

Post by rdsubhas »

Really great advice here. But missing one key area:

Continuous Delivery / Change Management. I believe any policy without change management principles isn't really complete, especially when its about 12factor which is considered a gold standard for production.

* CLIs are notoriously difficult to update because you have to convince every single consumer to update it manually, otherwise you just have scattered logic everywhere. Having an update workflow is essential before releasing the first version in production.

* Closely tied, a clear Backwards compatibility policy.

Apart from those two major items, I have also found one optionally nice pattern to reason about CLIs:

Design CLIs like APIs wherever possible. Treat subcommands as paths, arguments as identifiers, and flags as query/post parameters. It's not always applicable, but doing that for large internal tools helps against the "kitchen sink" syndrome.

Re: 12 Factor CLI Apps

#174

Post by Klathmon »

felixfbecker wrote: post #153
davemp wrote: post #132

Earlier quoted context omitted.

I find PS tab complete to be sub par compared to fish. It’s too aggressive when there are multiple completions.

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 want is some UI that when I hit tab it autocompletes as much as possible until there's a decision to make, and then shows me the options. So in my example case, it would look something like this:

Type `Get-App` -> hit tab -> shows `Get-AppLocker` -> type "P" -> hit tab -> `Get-AppLockerPolicy` is displayed

bash-ish systems nail this, and they even have the "double tab" to list all options from that point which is normally pretty nice.

The PS idea of "keep hitting tab or shift-tab while you cycle through all possible options" sucks in comparison. Especially with discoverability (There are about 20 commands on my windows system that start with "Get-App", and in order to figure them all out I just need to keep hitting tab until it cycles around)

Re: 12 Factor CLI Apps

#175

Post by voltagex_ »

forkerenok wrote: post #40
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…

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.

Merge a separate video and audio file without looking it up - I've got a document stored that lists all the different commands I've used and hopefully some context about what they do.

Re: 12 Factor CLI Apps

#176

Post by falcolas »

majewsky wrote: post #97
cyphar wrote: post #61

Earlier quoted context omitted.

> do you think that man pages are more important than web or in-cli docs? Yes. * Web docs are a problem because I don't always have access to the internet when trying to do something on my computer, and usually there are so many kinds of web doc generators that you have to figure out how the information you want is laid out. Web docs are useful as a quick-start guide or a very lengthy reference guide -- but not for t…

> I still add support for "--help" for my projects (because it is handy, I will admit) Some applications (e.g. Git) make "--help" redirect to man. What do you think of that?

Personally, I still pull up "man git-pull" or similar. I'm actively annoyed that I have to remember that the AWS CLI is different in this regard.

Not to mention that using "--help" for man pages requires I open up a separate window when I typically just want a quick reference to the most used flags.

Moving man pages to a different command is like coming up with an alternative icon to the hamburger menu for your regular UI. Sure, all the functionality is still there, but it requires a full stop and search to remember where to find it.

Re: 12 Factor CLI Apps

#178

Post by falcolas »

majewsky wrote: post #95
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.

I also prefer manpages over web searches for multiple reasons: - works without internet: very important when you want to use a long train ride to write some code (I also have the entire rust-doc and all IETF RFCs on my disk for quick referencing) - quick and reliable access to known items: `man ascii` is way quicker than finding an ASCII table on the web (probably on Wikipedia). And finding the syntax for an obscure…

One more reason - the man pages will be specific to the version of your tool. My man pages on my mac will automatically pull up the BSD version of "ls", not the GNU version.

Re: 12 Factor CLI Apps

#179

Post by voltagex_ »

deadbunny wrote: post #140
Walkman wrote: post #83

Unless you already know your users will want man pages, I wouldn’t bother also outputting them as they just aren’t used often enough anymore. I don't know where this is coming from, me and my colleagues are reading man pages every day. I would be interested how much others read them.

> I don't know where this is coming from From people who don't know how to use man pages.

BSD manpages or Linux manpages? There are very few Linux manpages that I'd consider acceptable.

Re: 12 Factor CLI Apps

#180

Post by JdeBP »

mrcarrot wrote: post #129
azernik wrote: post #123

Earlier quoted context omitted.

If you're already piping to less, just use its search functionality; type '/', the regexp, and then enter.

You can also do that directly in 'man'.

No. All three of the responders so far have implied that this functionality is in man. It is not. It's in the pager that man invokes; ironically often, but not necessarily always, that very same less program.
Post reply on HN