CLI Design: Crafting an Elegant Command Line UX in Python

Agenda

• CLI Tool Design Patterns
• Arguments
• CLI UI Elements
• Refactor: Sample Project

CLI Tool Design Patterns

• REPL
• Subcommand-based
• Script (the no-design pattern)

REPL

”Read-Eval-Print Loop”

Pros:

• State management (in-memory)

Cons:

• State management (ugh)
• Require user input – 👎 for CI pipelines

Takeaway: Consider whether you need to track program state, or if it could be written to disk instead

Subcommand-based

Top-level command, then subcommand(s) (e.g., git)

git commit -m "My commit message"

As if git commit is a command on its own, completely different from git push. man takes a hyphenated version of the subcommands:

man git-commit
man git-push

Script

A simple script.

Do you want to take on the complexity of developing a subcommand-based or REPL CLI tool?

Consider how your project will scale (adding more CLI options, etc.). Maybe you just need a couple scripts.

Design Patterns: In Summary

• REPL: If tracking program state is necessary (and can’t be kept on disc); not run in CI
• Subcommand-based: King of CLI design patterns
• Simple script: If a CLI tool isn’t worth the engineering effort, or doesn’t need to scale

Arguments

Nomenclature

• Argument/Arg: A value passed to a CLI program to modify functionality or provide required data
• Positional Arg: An arg only specified by its order
• Keyword Arg: A named arg that takes its own arg
• Flag: Implies binary functionality. Either on or off.
• Option: Refers to a kwarg or a flag; options should be optional, as implied by the name

(all are usually colloquially interchangeable)

Full Example

npm run myscript --script-shell /bin/bash --if-present

CLI Argument Best Practices

• Make short-form (single-character) aliases
  • -h/--help, -q/--quiet, -v/--verbose
• Allow combining short-form arguments
  • curl -Zks https://camball.io https://blog.camball.io
• Use conventional verbiage
  • Don’t call --verbose ”--include-debug-output”

CLI Argument Code Smells

(i.e., you likely can come up with a better design)

• Lots of positional arguments
• Positional arguments coming after options
• Required keyword arguments
• If ordering of options (any non-positional arguments (flags, kwargs)) matters
  • ✅ Commutative: curl -ks == curl -sk

Argument Parsing

• Python’s built-in argparse module
  • Can’t handle nested mutex arg groups
• click – Great for complex projects
• docopt – Cleanest solution for most projects
  • Declarative; documentation as code

Feature: Help Messages

All the major arg parsing libraries enable auto-generation of help messages (-h/--help).

By convention, users expect -h/--help.

npm -h
npm install -h

Trivially easy: Support it. Support it well.

Your tools are only as good as their documentation.

CLI UI Elements

Catalog

• Loading-related
  • [Parallel] Progress Bar
  • Spinner Wheels
• Confirmation (simple [Y/n])
• Select
• MultiSelect
• Password Input
• Questionnaire
• Table
• Coloured/Styled Output

Putting it all together: a CLI “UI Component Library”

python-prompt-toolkit

UI Component Demos

Sample Project

Let’s start with a basic command line tool.

Initially it has a quite crude implementation; we’ll refactor it using techniques we’ve discussed so that it’s not only a joy to use, but also has an improved DX.

Purpose of tool: provide information on words. Goals:

• Print definitions of words
  • Support looking up in alternate languages
• Print versions of words (plural, prefixed with indefinite article, ordinal numbers)
• Potentially more actions to take on words down the road…
• Question: What type of CLI tool should we implement, given the above requirements?

Datasources and Libraries

Free Dictionary API

curl -ks https://api.dictionaryapi.dev/api/v2/entries/en/dog | jq

[
  {
    "meanings": [
      {
        "definitions": [
          {
            "definition": "A mammal, Canis familiaris or Canis lupus familiaris, that has been domesticated for thousands of years, of highly variable appearance due to human breeding.",
            "example": "The dog barked all night long.",
            ...
          },
          ...
        ],
        ...
      },
      ...
    ],
    ...
  }
]

The inflect library

>>> import inflect
>>> inf = inflect.engine()
>>> 
>>> num_dogs = 2
>>> f"The {inf.ordinal(num_dogs)} dog is the last dog in line."
'The 2nd dog is the last dog in line.'
>>> f"There {inf.plural_verb("is", num_dogs)} {inf.number_to_words(num_dogs)} {inf.plural_noun("dog", num_dogs)} total."
'There are two dogs total.'
>>> 
>>> num_dogs = 1
>>> f"The {inf.ordinal(num_dogs)} dog is the last dog in line."
'The 1st dog is the last dog in line.'
>>> f"There {inf.plural_verb("is", num_dogs)} {inf.number_to_words(num_dogs)} {inf.plural_noun("dog", num_dogs)} total."
'There is one dog total.'

The codebase.

For Us to Improve

• Use docopt for easy argument parsing
• Add a --help command
• Display spinner wheels while waiting on individual API response
• Display progress bar when awaiting multiple words to be defined from API

Argument Parsing – Before

from sys import argv
from typing import Sequence

def parse_arguments(
    args: Sequence[str],
) -> tuple[list[str], dict[str, str | bool]]:
    """Parse arguments.

    Keyword arguments must follow positional arguments.

    Flag arguments are treated as keyword arguments, with a value of `True`.

    Keyword arguments and flags are a dictionary, i.e., duplicate kwargs are silently ignored.

    ### Parameters
    - :param `Sequence[str]` `args`: List of arguments.

    ### Returns
    :return: Tuple containing positional arguments and keyword arguments, respectively.
    :rtype: `tuple[list[str], dict[str, str | bool]]`
    """
    keyword_args: dict[str, str | bool] = dict()
    positional_args: list[str] = list()

    is_processing_keyword_args = False
    last_keyword_arg = ""

    for arg in args[1:]:
        # Consume keyword args
        if arg.startswith("-"):
            is_processing_keyword_args = True

            if arg.startswith("--"):
                keyword_args[arg] = ""
                last_keyword_arg = arg
            else:  # arg starts with only '-'
                keyword_args[arg] = True

            continue

        # Consume arguments passed to keyword args
        if is_processing_keyword_args:
            if (val := keyword_args[last_keyword_arg]) and isinstance(val, str):
                val += f" {arg}"
            else:
                val = arg

            keyword_args[last_keyword_arg] = val
            continue

        # Consume positional args
        positional_args.append(arg)

    return positional_args, keyword_args


def usage():
    print(
        """usage:
  wordinfo define <words>... [--language <language_code>]
  wordinfo plural <word>
  wordinfo indefinite <noun>
  wordinfo ordinal <number>
"""
    )


positional_args, keyword_args = parse_arguments(argv)

Argument Parsing – After

USAGE = """Word Information

Usage:
 wordinfo define <words>... [--language <language_code>]
 wordinfo plural <word>
 wordinfo indefinite <noun>
 wordinfo ordinal <number>
 wordinfo (-h | --help)

Options:
 -h --help                    Show this help message.
 --language <language_code>   Specify a language code.
"""

arguments = docopt(USAGE)

• 62 fewer lines of code
• Added help message support

Uncovered Topics

Not enough time!

• Installation & Distribution
• Config Management
• Cross-Platform Support
• Warning and Error Messages
• Logging & Error Reporting
• …so much more