CLI Arguments with Multiple Values

CLI arguments can also receive multiple values.

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

Python 3.8+

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!

How to pass multiple argument values

For arguments that accept multiple values, you provide them as space-separated values after the command, without repeating a flag:

$ python main.py ./index.md ./first-steps.md foo bar baz

/// 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:

//// tab | Python 3.8+
```python hl_lines="8-10"
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)

////

🤓 Other versions and variants

Python 3.8+ - non-Annotated

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