Skip to content

CLI Arguments with Multiple Values

CLI arguments can also receive multiple values.

You can define the type of a CLI argument using typing.List.

from pathlib import Path
from typing import List

import typer


def main(files: List[Path], celebration: str):
    for path in files:
        if path.is_file():
            print(f"This file exists: {path.name}")
            print(celebration)


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

And then you can pass it as many CLI arguments of that type as you want:

$ python main.py ./index.md ./first-steps.md woohoo!

This file exists: index.md
woohoo!
This file exists: first-steps.md
woohoo!

Tip

We also declared a final CLI argument celebration, and it's correctly used even if we pass an arbitrary number of files first.

Info

A List can only be used in the last command (if there are subcommands), as this will take anything to the right and assume it's part of the expected CLI arguments.

CLI arguments with tuples

If you want a specific number of values and types, you can use a tuple, and it can even have default values:

from typing import Tuple

import typer
from typing_extensions import Annotated


def main(
    names: Annotated[
        Tuple[str, str, str], typer.Argument(help="Select 3 characters to play with")
    ] = ("Harry", "Hermione", "Ron"),
):
    for name in names:
        print(f"Hello {name}")


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

Tip

Prefer to use the Annotated version if possible.

from typing import Tuple

import typer


def main(
    names: Tuple[str, str, str] = typer.Argument(
        ("Harry", "Hermione", "Ron"), help="Select 3 characters to play with"
    ),
):
    for name in names:
        print(f"Hello {name}")


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

Check it:

// Check the help
$ python main.py --help

Usage: main.py [OPTIONS] [NAMES]...

Arguments:
  [NAMES]...  Select 3 characters to play with  [default: Harry, Hermione, Ron]

Options:
  --help                Show this message and exit.

// Use it with its defaults
$ python main.py

Hello Harry
Hello Hermione
Hello Ron

// If you pass an invalid number of arguments you will get an error
$ python main.py Draco Hagrid

Error: Argument 'names' takes 3 values

// And if you pass the exact number of values it will work correctly
$ python main.py Draco Hagrid Dobby

Hello Draco
Hello Hagrid
Hello Dobby