Building Command Line Interfaces with Typer in Python#

Typer’s Core Philosophy: Leveraging Type Hints#

Typer’s primary innovation lies in its deep integration with Python type hints (introduced in PEP 484). Function parameters annotated with type hints are automatically recognized by Typer as command-line arguments or options. The type hint itself (str, int, bool, Path, datetime, etc.) dictates how Typer attempts to parse the input string provided by the user on the command line.

• Automatic Parsing: Typer automatically converts command-line strings into the specified Python types.
• Automatic Validation: Basic validation is performed based on the type hint (e.g., ensuring an int argument is actually a number). More complex validation can be added.
• Automatic Help Text: Docstrings and parameter names, combined with type hints, are used to automatically generate comprehensive help messages for the CLI.

Arguments vs. Options#

CLIs typically distinguish between arguments and options:

• Arguments: Required values provided positionally or by name immediately after the command. They are typically essential inputs for the command to function. In Typer, function parameters without a default value are treated as arguments.
• Options: Optional values, usually preceded by a flag (e.g., --verbose, -f filename). They modify the command’s behavior. In Typer, function parameters with a default value are treated as options.

Typer automatically determines whether a parameter is an argument or an option based on the presence or absence of a default value.

Basic Typer Application Structure#

A minimal Typer application typically involves:

1. Importing the typer library.
2. Defining one or more Python functions that represent CLI commands.
3. Annotating function parameters with type hints.
4. Using typer.run() to execute the appropriate function based on the command-line input.

For more complex applications with multiple commands and subcommands, typer.Typer() is used to create a Typer application instance, to which commands can be added using decorators.

Step 1: Installation#

Typer is installed using pip. It is recommended to install it with the all extra to include dependencies like Rich (for beautiful help messages) and Shellingham (for shell completion).

1
pip install "typer[all]"

Step 2: Creating a Basic Command#

A command is simply a Python function. The simplest Typer application runs a single function.

Create a file, for example, main.py:

1
import typer
2

3
def main(name: str):
4
    """
5
    Greets the user with a name.
6

7
    Args:
8
        name: The name to greet.
9
    """
10
    print(f"Hello {name}")
11

12
if __name__ == "__main__":
13
    typer.run(main)

• The main function takes one parameter, name, annotated with the type hint str. Since it has no default value, Typer treats it as a required argument.
• The docstring is used by Typer to generate help text.
• typer.run(main) makes the main function the entry point for the CLI.

Step 3: Running the Basic Command#

Execute the script from the terminal:

1
python main.py World

Output:

1
Hello World

If the required argument is missing:

1
python main.py

Output (Typer’s automatic error and help message):

1
Usage: main.py [OPTIONS] NAME
2

3
Error: Missing argument 'NAME'.

Step 4: Adding an Option#

Options provide flexibility. Adding a parameter with a default value makes it an option. Let’s add an optional greeting formalization.

Modify main.py:

1
import typer
2

3
def main(name: str, formal: bool = False):
4
    """
5
    Greets the user with a name, optionally formally.
6

7
    Args:
8
        name: The name to greet.
9
        formal: Whether to use a formal greeting.
10
    """
11
    if formal:
12
        print(f"Good day, Sir/Madam {name}")
13
    else:
14
        print(f"Hello {name}")
15

16
if __name__ == "__main__":
17
    typer.run(main)

• A new parameter formal is added with a type hint bool and a default value False. Typer recognizes this as an optional flag. Boolean options automatically become flags like --formal.

Step 5: Running with the Option#

Run the command with and without the formal option:

1
python main.py Alice

Output:

1
Hello Alice

1
python main.py Bob --formal

Output:

1
Good day, Sir/Madam Bob

1
python main.py --help

Output (Typer’s automatic help text, enhanced by Rich if installed):

1
Usage: main.py [OPTIONS] NAME
2

3
  Greets the user with a name, optionally formally.
4

5
Arguments:
6
  NAME  The name to greet. [required]
7

8
Options:
9
  --formal  Whether to use a formal greeting. [default: False]
10
  --help    Show this message and exit.

This demonstrates how simply adding type hints and default values allows Typer to build sophisticated argument and option parsing.

Example: A Simple File Utility CLI#

Consider a utility with commands to create and read files.

Create file_cli.py:

1
import typer
2
from pathlib import Path
3

4
app = typer.Typer()
5

6
@app.command()
7
def create(file_path: Path, content: str = ""):
8
    """
9
    Creates a file with specified content.
10

11
    Args:
12
        file_path: The path where the file should be created.
13
        content: The content to write to the file. Defaults to empty.
14
    """
15
    try:
16
        file_path.write_text(content)
17
        print(f"File '{file_path.name}' created successfully.")
18
    except Exception as e:
19
        print(f"Error creating file: {e}")
20

21
@app.command()
22
def read(file_path: Path):
23
    """
24
    Reads and prints the content of a file.
25

26
    Args:
27
        file_path: The path of the file to read.
28
    """
29
    try:
30
        content = file_path.read_text()
31
        print(f"--- Content of {file_path.name} ---")
32
        print(content)
33
        print("--------------------------")
34
    except FileNotFoundError:
35
        print(f"Error: File not found at '{file_path}'.")
36
    except Exception as e:
37
        print(f"Error reading file: {e}")
38

39
if __name__ == "__main__":
40
    app() # Run the Typer application instance

• app = typer.Typer() creates the application instance.
• @app.command() decorator registers functions (create, read) as subcommands of the main application.
• Type hints like Path automatically handle converting the input string into a pathlib.Path object, simplifying file operations.

Running the File Utility CLI#

1
python file_cli.py --help

Output (showing available commands):

1
Usage: file_cli.py [OPTIONS] COMMAND [ARGS]...
2

3
Options:
4
  --install-completion [bash|zsh|fish|powershell|pwsh]
5
                                  Install completion for the specified shell.
6
  --show-completion [bash|zsh|fish|powershell|pwsh]
7
                                  Show completion for the specified shell.
8
  --help                          Show this message and exit.
9

10
Commands:
11
  create  Creates a file with specified content.
12
  read    Reads and prints the content of a file.

Creating a file:

1
python file_cli.py create my_document.txt --content "This is the first line.\nAnd this is the second."

Reading the file:

1
python file_cli.py read my_document.txt

Output:

1
--- Content of my_document.txt ---
2
This is the first line.
3
And this is the second.
4
--------------------------

Attempting to read a non-existent file:

1
python file_cli.py read non_existent_file.txt

Output:

1
Error: File not found at 'non_existent_file.txt'.

This example demonstrates how easy it is to structure a CLI with multiple commands using typer.Typer() and leverage powerful type hints like Path for practical tasks.