Command-line behaviour

Recommended

• Exit with zero only when the command did everything it was asked

  DEV-1

  Exit 0 only when every action succeeded, and exit with a code from 1 to 125 on any failure. Document each code in the help text and keep its meaning fixed.

• Write results to stdout and everything else to stderr

  DEV-2

  Write only the command's result to standard output. Progress, warnings, prompts and errors go to standard error. Colour and spinners appear only when the stream is a terminal and NO_COLOR is unset.

• Offer JSON output with a stable shape

  DEV-3

  Give every command that prints data a --json flag. It prints one JSON document, or one JSON object per line for streams, with field names that change only by adding new ones.

• Never wait for input when no person is there

  DEV-4

  Prompt only when standard input is a terminal. Otherwise fail at once with a message that names the flag that answers the question, and offer --yes and --no-input flags.

• Show a dry run and ask before destructive commands

  DEV-5

  Give every command that deletes, overwrites or sends something a --dry-run flag that lists what it would do. Ask for confirmation before it acts, unless --yes is passed.

• Make command-line tools read the locale or say they do not

  DEV-6

  A command-line tool that prints translated text picks its language from LC_ALL, then LC_MESSAGES, then LANG. A tool in one language says so in its help. Machine-readable output is the same in every locale.

• Clean up and exit with 128 plus the signal number when stopped

  DEV-13

  On SIGINT or SIGTERM, start no new work, delete temporary and lock files, restore the terminal and exit with 128 plus the signal number. A second Ctrl+C exits at once.

Read this with

• Desktop apps and extensions playbook

  Command-line tools have their own playbook. Exit codes, JSON output and prompts decide whether scripts and agents can use them.