Is there a “standard” format for command line/shell help text?

by

Typically, your help output should include:

  • Description of what the app does
  • Usage syntax, which:
    • Uses [options] to indicate where the options go
    • arg_name for a required, singular arg
    • [arg_name] for an optional, singular arg
    • arg_name... for a required arg of which there can be many (this is rare)
    • [arg_name...] for an arg for which any number can be supplied
    • note that arg_name should be a descriptive, short name, in lower, snake case
  • A nicely-formatted list of options, each:
    • having a short description
    • showing the default value, if there is one
    • showing the possible values, if that applies
    • Note that if an option can accept a short form (e.g. -l) or a long form (e.g. --list), include them together on the same line, as their descriptions will be the same
  • Brief indicator of the location of config files or environment variables that might be the source of command line arguments, e.g. GREP_OPTS
  • If there is a man page, indicate as such, otherwise, a brief indicator of where more detailed help can be found

Note further that it’s good form to accept both -h and --help to trigger this message and that you should show this message if the user messes up the command-line syntax, e.g. omits a required argument.

More Related Contents:

  1. How do I copy a folder from remote to local using scp?
  2. Useless use of cat?
  3. How can I reverse the order of lines in a file?
  4. How can I shuffle the lines of a text file on the Unix command line or in a shell script?
  5. How do I use the lines of a file as arguments of a command?
  6. Shell command to find lines common in two files
  7. How to download GitHub Release from private repo using command line
  8. How can I check the version of sed in OS X?
  9. How to kill all processes matching a name?
  10. How to ssh to vagrant without actually running “vagrant ssh”?
  11. CMake’s execute_process and arbitrary shell scripts
  12. Emacs shell scripts – how to put initial options into the script?
  13. Take a full page screenshot with Firefox on the command-line
  14. How to run SWI-Prolog from the command line?
  15. “No such file or directory” but it exists
  16. What is the purpose of “&&” in a shell command?
  17. How can I parse a YAML file from a Linux shell script?
  18. How to read a file into a variable in shell?
  19. How to merge 2 JSON objects from 2 files using jq?
  20. How to pass command line arguments to a rake task
  21. Unix time and leap seconds
  22. What is the $? (dollar question mark) variable in shell scripting? [duplicate]
  23. How to mark a build unstable in Jenkins when running shell scripts
  24. Rearrange columns using cut
  25. How do you filter out all unique lines in a file?
  26. How do I parse command line arguments in Scala? [closed]
  27. Which terminal command to get just IP address and nothing else?
  28. How to add text at the end of each line in unix
  29. how do I use the grep –include option for multiple file types?
  30. Batch convert latin-1 files to utf-8 using iconv

Leave a Comment