Nitpicks:
Replace “pipe content” with “redirect content”
12 Factor CLI Apps
11–20 of 253 posts
Re: 12 Factor CLI Apps
#12Nitpicks: Replace “pipe content” with “redirect content”
nice catch, ty
Re: 12 Factor CLI Apps
#13This is all great advice. The one thing this does miss is distribution, which is a HUGE part of offering a great CLI app. Specifically, I'd say: 1. Make your OFFICIAL distribution channel the primary package manager on each platform (ex: on Mac, homebrew. Ubuntu, apt/snap). Beyond that, support as many as you have capacity to. 2. Also offer an official docker image which fully encapsulates the CLI tool and all of its…
yeah I agree 100%. Distribution of CLIs is a headache for the maintainer, but it's really important to get right if you want users to have a seamless experience.
Re: 12 Factor CLI Apps
#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%.
Re: 12 Factor CLI Apps
#15I disagree on the 2nd point. Flags prevent globbing by the shell and make the help text less clear.
Consider a usage line like this:
prog [password]
Also, an example like this:
git add ...
git add src/*
Consider an interface like this:
prog [--rm] [--name ] [args...]
prog --name --rm -- --name foo
{
"name": "--rm",
"args: ["--name", "foo"]
}
Re: 12 Factor CLI Apps
#16> 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.
Re: 12 Factor CLI Apps
#17I disagree on the 2nd point. Flags prevent globbing by the shell and make the help text less clear. Consider a usage line like this: prog [password] This tells you which argument is mandatory and which argument is optional in a second, without searching for the help text of --user and --password. Also, an example like this: git add ... Tells you that git add accepts multiple paths and you can invoke it with: git add…
I may try to expand on this in the article, but it's in there if you read between the lines. There is a difference between something that takes in multiple args of the same type and multiple TYPES of args. I'm arguing against multiple args of different types, not the same.
By definition any CLI that accepts variable args is fine here as it's all the same type.
The -- is a great point as well. It solves a lot of problems users have but a lot of time people don't even know about it. It solves issues with `heroku run` for example.
EDIT: updated to clarify my point
Re: 12 Factor CLI Apps
#18> 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.
I agree that man pages are wonderful. This point in the article really irked me.
Re: 12 Factor CLI Apps
#19> 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 web access to use in-CLI docs either, and that works on all platforms.
Having said this, I do plan on having man pages be an export type of the oclif docs (which is currently in-CLI and markdown). I intentionally made the output very similar to man pages already so it should be relatively easy to do.
Re: 12 Factor CLI Apps
#20> 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…
[deleted]