Command-line tools

Required

• Take secrets from the environment or a file instead of a flag

  DSK-24

  Read tokens, passwords and keys from an environment variable, a file, standard input or the system keychain. The tool never accepts a secret as a command-line argument and never prints one.

Recommended

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

  DSK-20

  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

  DSK-21

  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

  DSK-22

  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

  DSK-23

  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

  DSK-25

  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.

• Give every command help with an example and a version flag

  DSK-26

  Every command answers --help with its purpose, its flags, one example and its exit codes, and exits 0. The tool answers --version with its version and build commit.