12 Factor CLI Apps - Revision history

Admin: /* Rule 12: Use XDG */

2018-10-30T03:47:04Z

Rule 12: Use XDG

← Older revision		Revision as of 03:47, 30 October 2018
Line 176:		Line 176:

	==Rule 12: Use XDG==		==Rule 12: Use XDG==

			{{Main\|XDG}}

	XDG-spec: https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html		XDG-spec: https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

Admin: /* Rule 12: Use XDG */

2018-10-30T03:45:59Z

Rule 12: Use XDG

← Older revision		Revision as of 03:45, 30 October 2018
Line 176:		Line 176:

	==Rule 12: Use XDG==		==Rule 12: Use XDG==

			XDG-spec: https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

	XDG is a spec for figuring out where to put files.		XDG is a spec for figuring out where to put files.

Admin: /* Flags */

2018-10-30T03:45:39Z

Flags

← Older revision		Revision as of 03:45, 30 October 2018
Line 188:		Line 188:

	[[Category:CLI]]		[[Category:CLI]]
			[[Category:Command Line]]

Admin: /* Rule 11: Be clear about subcommands */

2018-10-30T03:45:28Z

Rule 11: Be clear about subcommands

← Older revision		Revision as of 03:45, 30 October 2018
Line 174:		Line 174:
	$ heroku domains:add www.myapp.com		$ heroku domains:add www.myapp.com
	</pre>		</pre>

			==Rule 12: Use XDG==

			XDG is a spec for figuring out where to put files.

			Environment variables like XDG_CONFIG_HOME allow you to specify a config or data file location

			If not specified, use <code>~/.config/myapp</code> for config files, and <code>~/.local/share/myapp</code> for data files.

			Use <code>~/.cache/myapp</code> for cache files on Unix. Use <code>~/Library/Caches/myapp</code> on Mac. Use <code>%LOCALAPPDATA%\myapp</code> on Windows.

			==Flags==

			[[Category:CLI]]

Admin: /* Rule 7: Accept input from user */

2018-10-30T03:42:56Z

Rule 7: Accept input from user

← Older revision		Revision as of 03:42, 30 October 2018
Line 112:		Line 112:

	Check boxes and radio buttons can give user menus and make things a lot easier to use		Check boxes and radio buttons can give user menus and make things a lot easier to use

			==Rule 8: Use tables==

			Not the fancy tables with borders. Something you can parse with cut and grep and other command line utilities.

			Tables require thinking about screen width.

			By default, only show a few columns. Give the user a <code>--columns</code> flag to control that, where they pass a comma separated list of columns.

			Cut off rows that will spill over, and provide a <code>--no-truncate</code> option.

			Show column headers but provide a <code>--no-headers</code> option.

			Implement a <code>--filter</code> command line option to filter specific columns

			Allow sorting by column with <code>--sort</code>


			==Rule 9: Be speedy==

			Use the <code>time</code> utility to time your CLI

			<pre>
			<100ms: very fast (sadly, not feasible for scripting languages)
			100ms–500ms: fast enough, aim here
			500ms-2s: usable, but not going to impress anyone
			2s+: languid, users will prefer to avoid your CLI at this point
			</pre>

			==Rule 10: Encourage contributions==

			Open source, contributions file, license, code of conduct, etc.

			==Rule 11: Be clear about subcommands==

			CLIs can be single command (like cp or grep)

			Multi commands are like git, which have a subcommand as the first arg and then trailing arguments after that.

			One basic task => single command CLI

			Most CLIs would benefit from subcommands

			If user does not pass any arguments:

			* list subcommands for multi-command CLIs
			* display the help for single-CLIs
			* don't take a default action

			If you need subcommands below your subcommands, those are called "topics".

			Git uses spaces:

			<pre>
			$ git submodule add git@github.com:rainbow-mind-machine/rainbow-mind-machine
			</pre>

			Heroku uses colons:

			<pre>
			$ heroku domains:add www.myapp.com
			</pre>

Admin: /* Rule 6: Be fancy, know when to be fancy */

2018-10-30T03:25:34Z

Rule 6: Be fancy, know when to be fancy

← Older revision		Revision as of 03:25, 30 October 2018
Line 104:		Line 104:
	* <code>--no-color</code> flag being used		* <code>--no-color</code> flag being used
	* <code>MYAPP_NOCOLOR=1</code> environment variable for your CLI application alone		* <code>MYAPP_NOCOLOR=1</code> environment variable for your CLI application alone

			==Rule 7: Accept input from user==

			If the stdin is a tty, then you can accept input from the user. This should not be required, though, to ensure the tool can be automated/scripted.

			A good practice is to require user input for confirmation dialogs, if the action being taken is dangerous.

			Check boxes and radio buttons can give user menus and make things a lot easier to use

Admin: /* Rule 2: Prefer flags to arguments */

2018-10-30T03:20:46Z

Rule 2: Prefer flags to arguments

← Older revision		Revision as of 03:20, 30 October 2018
Line 24:		Line 24:

	==Rule 2: Prefer flags to arguments==		==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:

			<pre>
			$ heroku fork --from FROMAPP --to TOAPP
			</pre>

			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 <code>--</code> 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:

			<pre>
			$ mycli version # multi only
			$ mycli --version
			$ mycli -V
			</pre>

			==Rule 4: Mind stdout and stderr==

			Important to direct errors and messages to correct place

			Example:

			<pre>
			$ myapp > foo.txt
			Warning: something went wrong
			</pre>

			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:

			<pre>
			$ 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
			</pre>

			==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:

			* <code>TERM=dumb</code>
			* <code>NO_COLOR</code> being set
			* <code>--no-color</code> flag being used
			* <code>MYAPP_NOCOLOR=1</code> environment variable for your CLI application alone

Admin: Created page with "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== sho..."

2018-10-30T03:10:24Z

Created page with "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== sho..."

New page

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:

<pre>
# list all commands
$ mycli
$ mycli --help
$ mycli help
$ mycli -h

# get help for subcommand
$ mycli subcommand --help
$ mycli subcommand -h
</pre>

Also consider shell completion!

Auto-documentation:

[[Image:Autodoc.png|500px]]

==Rule 2: Prefer flags to arguments==