Basics

In these examples, we show basic examples of using tyro.cli(): functions, dataclasses, supported annotations, and configuration.

Functions

In the simplest case, tyro.cli() can be used to run a function with arguments populated from the CLI.

# 01_functions.py
import tyro

def main(field1: str, field2: int = 3) -> None:
    """Function, whose arguments will be populated from a CLI interface.

    Args:
        field1: A string field.
        field2: A numeric field, with a default value.
    """
    print(field1, field2)

if __name__ == "__main__":
    tyro.cli(main)

We can use --help to show the help message, or --field1 and --field2 to set the arguments:

$ python ./01_functions.py --help
usage: 01_functions.py [-h] --field1 STR [--field2 INT]

Function, whose arguments will be populated from a CLI interface.

╭─ options ───────────────────────────────────────────────────────────────╮
│ -h, --help          show this help message and exit                     │
│ --field1 STR        A string field. (required)                          │
│ --field2 INT        A numeric field, with a default value. (default: 3) │
╰─────────────────────────────────────────────────────────────────────────╯

$ python ./01_functions.py --field1 hello
hello 3

$ python ./01_functions.py --field1 hello --field2 10
hello 10

Dataclasses

In addition to functions, tyro.cli() can also take dataclasses as input.

# 02_dataclasses.py
from dataclasses import dataclass
from pprint import pprint

import tyro

@dataclass
class Args:
    """Description.
    This should show up in the helptext!"""

    field1: str
    """A string field."""

    field2: int = 3
    """A numeric field, with a default value."""

if __name__ == "__main__":
    args = tyro.cli(Args)
    pprint(args)

To show the help message, we can use the --help flag:

$ python ./02_dataclasses.py --help
usage: 02_dataclasses.py [-h] --field1 STR [--field2 INT]

Description. This should show up in the helptext!

╭─ options ───────────────────────────────────────────────────────────────╮
│ -h, --help          show this help message and exit                     │
│ --field1 STR        A string field. (required)                          │
│ --field2 INT        A numeric field, with a default value. (default: 3) │
╰─────────────────────────────────────────────────────────────────────────╯

We can override field1 and field2:

$ python ./02_dataclasses.py --field1 hello
Args(field1='hello', field2=3)

$ python ./02_dataclasses.py --field1 hello --field2 5
Args(field1='hello', field2=5)

Multi-value Arguments

Arguments of both fixed and variable lengths can be annotated with standard Python collection types. For Python 3.7 and 3.8, we can use either from __future__ import annotations to support list[T] and tuple[T], or the older typing.List and typing.Tuple.

# 03_multivalue.py
import pathlib
from dataclasses import dataclass
from pprint import pprint

import tyro

@dataclass
class Config:
    # Example of a variable-length tuple. `list[T]`, `set[T]`,
    # `dict[K, V]`, etc are supported as well.
    source_paths: tuple[pathlib.Path, ...]
    """This can be multiple!"""

    # Fixed-length tuples are also okay.
    dimensions: tuple[int, int] = (32, 32)
    """Height and width."""

if __name__ == "__main__":
    config = tyro.cli(Config)
    pprint(config)

To print help:

$ python ./03_multivalue.py --help
usage: 03_multivalue.py [-h] --source-paths [PATH
                        [PATH ...]] [--dimensions INT INT]

╭─ options ──────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit    │
│ --source-paths [PATH [PATH ...]]                           │
│                         This can be multiple! (required)   │
│ --dimensions INT INT    Height and width. (default: 32 32) │
╰────────────────────────────────────────────────────────────╯

We can override arguments:

$ python ./03_multivalue.py --source-paths ./data --dimensions 16 16
Config(source_paths=(PosixPath('data'),), dimensions=(16, 16))

$ python ./03_multivalue.py --source-paths ./data1 ./data2
Config(source_paths=(PosixPath('data1'), PosixPath('data2')),
       dimensions=(32, 32))

Booleans and Flags

Booleans can either be expected to be explicitly passed in, or, if given a default value, automatically converted to flags.

To turn off conversion, see tyro.conf.FlagConversionOff.

# 04_flags.py
from dataclasses import dataclass
from pprint import pprint

import tyro

@dataclass
class Args:
    # Boolean. This expects an explicit "True" or "False".
    boolean: bool

    # Optional boolean. Same as above, but can be omitted.
    optional_boolean: bool | None = None

    # Pass --flag-a in to set this value to True.
    flag_a: bool = False

    # Pass --no-flag-b in to set this value to False.
    flag_b: bool = True

if __name__ == "__main__":
    args = tyro.cli(Args)
    pprint(args)

$ python ./04_flags.py --help
usage: 04_flags.py [-h] [OPTIONS]

╭─ options ────────────────────────────────────────────────────────────────╮
│ -h, --help                                                               │
│     show this help message and exit                                      │
│ --boolean {True,False}                                                   │
│     Boolean. This expects an explicit "True" or "False". (required)      │
│ --optional-boolean {None,True,False}                                     │
│     Optional boolean. Same as above, but can be omitted. (default: None) │
│ --flag-a, --no-flag-a                                                    │
│     Pass --flag-a in to set this value to True. (default: False)         │
│ --flag-b, --no-flag-b                                                    │
│     Pass --no-flag-b in to set this value to False. (default: True)      │
╰──────────────────────────────────────────────────────────────────────────╯

$ python ./04_flags.py --boolean True
Args(boolean=True, optional_boolean=None, flag_a=False, flag_b=True)

$ python ./04_flags.py --boolean False --flag-a
Args(boolean=False, optional_boolean=None, flag_a=True, flag_b=True)

$ python ./04_flags.py --boolean False --no-flag-b
Args(boolean=False, optional_boolean=None, flag_a=False, flag_b=False)

Choices

typing.Literal[] can be used to restrict inputs to a fixed set of literal choices.

# 05_choices.py
import dataclasses
from pprint import pprint
from typing import Literal

import tyro

@dataclasses.dataclass
class Args:
    # We can use Literal[] to restrict the set of allowable inputs, for example, over
    # a set of strings.
    string: Literal["red", "green"] = "red"

    # Integers also work. (as well as booleans, enums, etc)
    number: Literal[0, 1, 2] = 0

if __name__ == "__main__":
    args = tyro.cli(Args)
    pprint(args)

$ python ./05_choices.py --help
usage: 05_choices.py [-h] [--string {red,green}] [--number {0,1,2}]

╭─ options ──────────────────────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit                    │
│ --string {red,green}    We can use Literal[] to restrict the set of        │
│                         allowable inputs, for example, over a set of       │
│                         strings. (default: red)                            │
│ --number {0,1,2}        Integers also work. (as well as booleans, enums,   │
│                         etc) (default: 0)                                  │
╰────────────────────────────────────────────────────────────────────────────╯

$ python ./05_choices.py --string red
Args(string='red', number=0)

$ python ./05_choices.py --string blue
╭─ Parsing error ────────────────────────────────────────────────────────╮
│ Argument --string: invalid choice: 'blue' (choose from 'red', 'green') │
│ ────────────────────────────────────────────────────────────────────── │
│ For full helptext, run 05_choices.py --help                            │
╰────────────────────────────────────────────────────────────────────────╯

Enums

In addition to literals, enums can also be used to provide a fixed set of choices.

# 06_enums.py
import enum
from dataclasses import dataclass
from pprint import pprint

import tyro

class Color(enum.Enum):
    RED = enum.auto()
    BLUE = enum.auto()

@dataclass
class Config:
    color: Color = Color.RED
    """Color argument."""

    opacity: float = 0.5
    """Opacity argument."""

if __name__ == "__main__":
    config = tyro.cli(Config)
    pprint(config)

$ python ./06_enums.py --help
usage: 06_enums.py [-h] [--color {RED,BLUE}] [--opacity FLOAT]

╭─ options ────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit  │
│ --color {RED,BLUE}      Color argument. (default: RED)   │
│ --opacity FLOAT         Opacity argument. (default: 0.5) │
╰──────────────────────────────────────────────────────────╯

$ python ./06_enums.py --color RED
Config(color=<Color.RED: 1>, opacity=0.5)

$ python ./06_enums.py --color BLUE --opacity 0.75
Config(color=<Color.BLUE: 2>, opacity=0.75)

Unions

X | Y or typing.Union can be used to expand inputs to multiple types.

# 07_unions.py
import dataclasses
import enum
from pprint import pprint
from typing import Literal, Optional

import tyro

class Color(enum.Enum):
    RED = enum.auto()
    GREEN = enum.auto()
    BLUE = enum.auto()

@dataclasses.dataclass
class Args:
    # Unions can be used to specify multiple allowable types.
    union_over_types: int | str = 0
    string_or_enum: Literal["red", "green"] | Color = "red"

    # Unions also work over more complex nested types.
    union_over_tuples: tuple[int, int] | tuple[str] = ("1",)

    # And can be nested in other types.
    tuple_of_string_or_enum: tuple[Literal["red", "green"] | Color, ...] = (
        "red",
        Color.RED,
    )

    # Optional[T] is equivalent to `T | None`.
    integer: Optional[Literal[0, 1, 2, 3]] = None

if __name__ == "__main__":
    args = tyro.cli(Args)
    pprint(args)

$ python ./07_unions.py --help
usage: 07_unions.py [-h] [OPTIONS]

╭─ options ──────────────────────────────────────────────────────────────────╮
│ -h, --help                                                                 │
│     show this help message and exit                                        │
│ --union-over-types INT|STR                                                 │
│     Unions can be used to specify multiple allowable types. (default: 0)   │
│ --string-or-enum {red,green,RED,GREEN,BLUE}                                │
│     Unions can be used to specify multiple allowable types. (default: red) │
│ --union-over-tuples {INT INT}|STR                                          │
│     Unions also work over more complex nested types. (default: 1)          │
│ --tuple-of-string-or-enum [{red,green,RED,GREEN,BLUE}                      │
│ [{red,green,RED,GREEN,BLUE} ...]]                                          │
│     And can be nested in other types. (default: red RED)                   │
│ --integer {None,0,1,2,3}                                                   │
│     Optional[T] is equivalent to `T | None`. (default: None)               │
╰────────────────────────────────────────────────────────────────────────────╯

$ python ./07_unions.py --union-over-types 3
Args(union_over_types=3,
     string_or_enum='red',
     union_over_tuples=('1',),
     tuple_of_string_or_enum=('red', <Color.RED: 1>),
     integer=None)

$ python ./07_unions.py --union-over-types three
Args(union_over_types='three',
     string_or_enum='red',
     union_over_tuples=('1',),
     tuple_of_string_or_enum=('red', <Color.RED: 1>),
     integer=None)

$ python ./07_unions.py --integer None
Args(union_over_types=0,
     string_or_enum='red',
     union_over_tuples=('1',),
     tuple_of_string_or_enum=('red', <Color.RED: 1>),
     integer=None)

$ python ./07_unions.py --integer 0
Args(union_over_types=0,
     string_or_enum='red',
     union_over_tuples=('1',),
     tuple_of_string_or_enum=('red', <Color.RED: 1>),
     integer=0)

Positional Arguments

Positional-only arguments in functions are converted to positional CLI arguments.

For more general positional arguments, see tyro.conf.Positional.

# 08_positional.py
from __future__ import annotations

import pathlib

import tyro

def main(
    source: pathlib.Path,
    dest: pathlib.Path,
    /,  # Mark the end of positional arguments.
    verbose: bool = False,
) -> None:
    """Command-line interface defined using a function signature. This
    docstring is parsed to generate helptext.

    Args:
        source: Source path.
        dest: Destination path.
        verbose: Explain what is being done.
    """
    print(f"{source=}\n{dest=}\n{verbose=}")

if __name__ == "__main__":
    tyro.cli(main)

$ python 08_positional.py --help
usage: 08_positional.py [-h] [--verbose | --no-verbose] PATH PATH

Command-line interface defined using a function signature. This docstring is
parsed to generate helptext.

╭─ positional arguments ─────────────────────────────────────────╮
│ PATH              Source path. (required)                      │
│ PATH              Destination path. (required)                 │
╰────────────────────────────────────────────────────────────────╯
╭─ options ──────────────────────────────────────────────────────╮
│ -h, --help        show this help message and exit              │
│ --verbose, --no-verbose                                        │
│                   Explain what is being done. (default: False) │
╰────────────────────────────────────────────────────────────────╯

$ python 08_positional.py ./a ./b
source=PosixPath('a')
dest=PosixPath('b')
verbose=False

$ python 08_positional.py ./test1 ./test2 --verbose
source=PosixPath('test1')
dest=PosixPath('test2')
verbose=True

Configuration via typing.Annotated[]

The tyro.conf module contains utilities that can be used in conjunction with typing.Annotated to configure command-line interfaces beyond what is expressible via static type annotations. To apply options globally, these same flags can also be passed via the config argument of tyro.cli().

Features here are supported, but generally unnecessary and should be used sparingly.

# 09_conf.py
import dataclasses

from typing_extensions import Annotated

import tyro

@dataclasses.dataclass
class Args:
    # A numeric field parsed as a positional argument.
    positional: tyro.conf.Positional[int]

    # A boolean field.
    boolean: bool = False

    # A numeric field that can't be changed via the CLI.
    fixed: tyro.conf.Fixed[int] = 5

    # A field with manually overridden properties.
    manual: Annotated[
        str,
        tyro.conf.arg(
            name="renamed",
            metavar="STRING",
            help="A field with manually overridden properties!",
        ),
    ] = "Hello"

if __name__ == "__main__":
    print(tyro.cli(Args, config=(tyro.conf.FlagConversionOff,)))

$ python ./09_conf.py --help
usage: 09_conf.py [-h] [OPTIONS] INT

╭─ positional arguments ─────────────────────────────────────────────────────╮
│ INT                     A numeric field parsed as a positional argument.   │
│                         (required)                                         │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ options ──────────────────────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit                    │
│ --boolean {True,False}  A boolean field. (default: False)                  │
│ --fixed {fixed}         A numeric field that can't be changed via the CLI. │
│                         (fixed to: 5)                                      │
│ --renamed STRING        A field with manually overridden properties!       │
│                         (default: Hello)                                   │
╰────────────────────────────────────────────────────────────────────────────╯

$ python ./09_conf.py 5 --boolean True
Args(positional=5, boolean=True, fixed=5, manual='Hello')

Argument Aliases

tyro.conf.arg() can be used to attach aliases to arguments.

# 10_aliases.py
from typing import Annotated

import tyro

def checkout(
    branch: Annotated[str, tyro.conf.arg(aliases=["-b"])],
) -> None:
    """Check out a branch."""
    print(f"{branch=}")

if __name__ == "__main__":
    tyro.cli(checkout)

$ python ./10_aliases.py --help
usage: 10_aliases.py [-h] --branch STR

Check out a branch.

╭─ options ───────────────────────────────────────────────╮
│ -h, --help              show this help message and exit │
│ --branch STR, -b STR    (required)                      │
╰─────────────────────────────────────────────────────────╯

$ python ./10_aliases.py --branch main
branch='main'

$ python ./10_aliases.py -b main
branch='main'

Type Aliases (3.12+)

In Python 3.12, the type statement is introduced to create type aliases.

# 11_type_aliases_py312.py
import dataclasses

import tyro

# Lazily-evaluated type alias.
type Field1Type = Inner

@dataclasses.dataclass
class Inner:
    a: int
    b: str

@dataclasses.dataclass
class Args:
    """Description.
    This should show up in the helptext!"""

    field1: Field1Type
    """A field."""

    field2: int = 3
    """A numeric field, with a default value."""

if __name__ == "__main__":
    args = tyro.cli(Args)
    print(args)

$ python ./11_type_aliases_py312.py --help
usage: 11_type_aliases_py312.py [-h] [--field2 INT] --field1.a INT --field1.b
                                STR

Description. This should show up in the helptext!

╭─ options ─────────────────────────────────────────────────────────────────╮
│ -h, --help            show this help message and exit                     │
│ --field2 INT          A numeric field, with a default value. (default: 3) │
╰───────────────────────────────────────────────────────────────────────────╯
╭─ field1 options ──────────────────────────────────────────────────────────╮
│ A field.                                                                  │
│ ────────────────────────────────                                          │
│ --field1.a INT        (required)                                          │
│ --field1.b STR        (required)                                          │
╰───────────────────────────────────────────────────────────────────────────╯

Counters

Repeatable ‘counter’ arguments can be specified via tyro.conf.UseCounterAction.

# 12_counters.py
from typing_extensions import Annotated

import tyro
from tyro.conf import UseCounterAction

def main(
    verbosity: UseCounterAction[int],
    aliased_verbosity: Annotated[UseCounterAction[int], tyro.conf.arg(aliases=["-v"])],
) -> None:
    """Example showing how to use counter actions.

    Args:
        verbosity: Verbosity level.
        aliased_verbosity: Same as above, but can also be specified with -v, -vv, -vvv, etc.
    """
    print("Verbosity level:", verbosity)
    print("Verbosity level (aliased):", aliased_verbosity)

if __name__ == "__main__":
    tyro.cli(main)

$ python ./12_counters.py --help
usage: 12_counters.py [-h] [--verbosity] [--aliased-verbosity]

Example showing how to use counter actions.

╭─ options ──────────────────────────────────────────────────────────────────╮
│ -h, --help         show this help message and exit                         │
│ --verbosity        Verbosity level. (repeatable)                           │
│ --aliased-verbosity, -v                                                    │
│                    Same as above, but can also be specified with -v, -vv,  │
│                    -vvv, etc. (repeatable)                                 │
╰────────────────────────────────────────────────────────────────────────────╯

$ python ./12_counters.py --verbosity
Verbosity level: 1
Verbosity level (aliased): 0

$ python ./12_counters.py --verbosity --verbosity
Verbosity level: 2
Verbosity level (aliased): 0

$ python ./12_counters.py -vvv
Verbosity level: 0
Verbosity level (aliased): 3

Instantiating Classes

In addition to functions and dataclasses, we can also generate CLIs from the constructors of standard Python classes.

# 13_classes.py
import tyro

class Args:
    def __init__(
        self,
        field1: str,
        field2: int,
        flag: bool = False,
    ):
        """Arguments.

        Args:
            field1: A string field.
            field2: A numeric field.
            flag: A boolean flag.
        """
        self.data = [field1, field2, flag]

if __name__ == "__main__":
    args = tyro.cli(Args)
    print(args.data)

$ python ./13_classes.py --help
usage: 13_classes.py [-h] --field1 STR --field2 INT [--flag | --no-flag]

Arguments.

╭─ options ────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit  │
│ --field1 STR            A string field. (required)       │
│ --field2 INT            A numeric field. (required)      │
│ --flag, --no-flag       A boolean flag. (default: False) │
╰──────────────────────────────────────────────────────────╯

$ python ./13_classes.py --field1 hello --field2 7
['hello', 7, False]