CLI best practices

use the most common flags

the help flag : --help | -h | -?

 $ git --help
 usage: git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
            [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
            [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
            [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
            [--super-prefix=<path>] [--config-env=<name>=<envvar>]
            <command> [<args>]

 These are common Git commands used in various situations:

the version flag : –-version | -V

 $ docker --version
 Docker version 27.4.0, build bde2b89

the verbose flag : --verbose | -v | -v(*N)

 $ git branch
 * main

 $ git branch -v
 * main e9c9f79fc3b1 [behind 7] feat: implement `service` factory and refactor services (#193)

respect the args/flags syntax in the usage text
- [...] = optional
- <...> = mandatory
- cf. man git
trackable errors : https://www.shellcheck.net/wiki/SC2128
human-readable errors

$ shellcheck script.sh

In script.sh line 1:
echo "ok"
^-- SC2148 (error): Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive.

For more information:
  https://www.shellcheck.net/wiki/SC2148 -- Tips depend on target shell...

actionable error codes

$ git pusd
git: 'pusd' is not a git command. See 'git --help'.

The most similar command is
        push

Use error codes (0/1/++)
- https://mariadb.com/kb/en/operating-system-error-codes/
- https://www.agileconnection.com/article/overview-linux-exit-codes
Visually show progress, instead of halting
Flags over ags
- example : from memory, how to compress a folder with tar ? another command could be tar compress --recursive --input <path> --output <path>
Give the user output format choices so it can be piped into another tool : --output=<json|yaml|table>
provide autocompletion : docker inspect <TAB>
the commands should be as deterministic as possible

gmolveau/cli_best_practices.md

CLI best practices