Skip to content

Instantly share code, notes, and snippets.

@gmolveau

gmolveau/cli_best_practices.md

Created February 27, 2025 20:12
Show Gist options
  • Save gmolveau/1c602beb59bb10c17fda7201d7e4044f to your computer and use it in GitHub Desktop.
Save gmolveau/1c602beb59bb10c17fda7201d7e4044f to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. gmolveau created this gist Feb 27, 2025.
    72 changes: 72 additions & 0 deletions cli_best_practices.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,72 @@
    # CLI best practices

    - use the most common flags
    - the `help` flag : `--help | -h | -?`

    ```bash
    $ 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`

    ```bash
    $ docker --version
    Docker version 27.4.0, build bde2b89
    ```

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

    ```bash
    $ 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

    ```bash
    $ 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

    ```bash
    $ 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