12 Factor CLI Apps

A guide from Heroku containing 12 principles for creating great CLI apps: https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46

Rule 1: Great help is essential

show help with all of these:

# list all commands
$ mycli
$ mycli --help
$ mycli help
$ mycli -h

# get help for subcommand
$ mycli subcommand --help
$ mycli subcommand -h

Also consider shell completion!

Auto-documentation:

Rule 2: Prefer flags to arguments

Two ways for user to provide input: (positional) arguments, and flags.

Flags require a bit more typing, but make the CLI much clearer.

Example:

$ heroku fork --from FROMAPP --to TOAPP

Rule of thumb: 1 type of argument is fine, 2 types are very suspect, and 3 are never good.

If you pass off flags to another process, use -- argument to denote it should stop parsing arguments there and pass the rest of the arguments to the other process.

Rule 3: Make version number easy to find

Make all of these print the version:

$ mycli version # multi only
$ mycli --version
$ mycli -V

Rule 4: Mind stdout and stderr

Important to direct errors and messages to correct place

Example:

$ myapp > foo.txt
Warning: something went wrong

Don't want warning to get buried, or to have a problem with structured output.

In short: stdout is for output, stderr is for messaging.

If you wrap a subcommand, always display the stderr from that command to the user.

Rule 5: Handle things going wrong

Things go wrong a lot, especially with CLIs

Error messages should contain:

• error code
• error title
• error description
• how to fix
• url for more info

Example:

$ myapp dump -o myfile.out
Error: EPERM - Invalid permissions on myfile.out
Cannot write to myfile.out, file does not have write permissions.
Fix with: chmod +w myfile.out
https://github.com/jdxcode/myapp

Rule 6: Be fancy, know when to be fancy

Colors and dimming highlight important info

Spinners and progress bars inform user that program is still working

But be able to fall back to basic behavior (and know when to)

If user's stdout or stderr are not connected to tty, probably piping to file, so no colors. Also no spinny things. (they use ansi codes, which you don't want to output to a file.)

Let the user turn off fancy stuff with:

• TERM=dumb
• NO_COLOR being set
• --no-color flag being used
• MYAPP_NOCOLOR=1 environment variable for your CLI application alone