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
╭─ Invalid choice ─────────────────────────────────────────────────────────────╮
│ invalid choice 'blue' for argument '--string'. Expected one of ('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.

Note: If a double-dash (’–’) appears in a command line, everything afterward will be considered positional.

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] PATH PATH [--verbose | --no-verbose]

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 tuple field parsed as a single argument.
    tuple_arg: tyro.conf.UsePythonSyntaxForLiteralCollections[tuple[int, float]] = (
        1,
        2.0,
    )

    # 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]

╭─ 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)                                       │
│ --tuple-arg (INT,FLOAT)  A tuple field parsed as a single argument.          │
│                          (default: '(1, 2.0)')                               │
│ --renamed STRING         A field with manually overridden properties!        │
│                          (default: Hello)                                    │
╰──────────────────────────────────────────────────────────────────────────────╯

$ python ./09_conf.py 5 --boolean True
Args(positional=5, boolean=True, fixed=5, tuple_arg=(1, 2.0), 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] -b STR

Check out a branch.

╭─ options ─────────────────────────────────────────────╮
│ -h, --help            show this help message and exit │
│ -b STR, --branch 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, config=(tyro.conf.CascadeSubcommandArgs,))

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

Example showing how to use counter actions.

╭─ options ────────────────────────────────────────────────────────────────────╮
│ -h, --help               show this help message and exit                     │
│ --verbosity              Verbosity level. (repeatable)                       │
│ -v, --aliased-verbosity  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]

Mutually Exclusive Groups

tyro.conf.create_mutex_group() can be used to create mutually exclusive argument groups, where either exactly one (required=True) or at most one (required=False) argument from the group can be specified.

The title parameter can be used to customize the group title in the help text.

# 14_mutex.py
from pathlib import Path
from typing import Annotated, Literal

import tyro

RequiredGroup = tyro.conf.create_mutex_group(required=True, title="output target")
OptionalGroup = tyro.conf.create_mutex_group(required=False, title="verbosity level")

def main(
    # Exactly one of --target-stream or --target-file must be specified.
    target_stream: Annotated[Literal["stdout", "stderr"] | None, RequiredGroup] = None,
    target_file: Annotated[Path | None, RequiredGroup] = None,
    # Either --verbose or --very-verbose can be specified (but not both).
    verbose: Annotated[bool, OptionalGroup] = False,
    very_verbose: Annotated[bool, OptionalGroup] = False,
) -> None:
    """Demonstrate mutually exclusive argument groups."""
    if very_verbose or verbose:
        print(f"{target_stream=} {target_file=}")
    if very_verbose:
        print(f"{target_stream=} {target_file=}")

if __name__ == "__main__":
    tyro.cli(
        main,
        # `DisallowNone` prevents `None` from being a valid choice for
        # `--target-stream` and `--target-file`.
        #
        # `FlagCreatePairsOff` prevents `--no-verbose` and `--no-very-verbose` from
        # being created.
        config=(tyro.conf.DisallowNone, tyro.conf.FlagCreatePairsOff),
    )

$ python ./14_mutex.py
╭─ Required mutex group ──────────────────────╮
│ Missing required argument group:            │
│   • --target-stream, --target-file          │
│ ─────────────────────────────────────────── │
│ For full helptext, run ./14_mutex.py --help │
╰─────────────────────────────────────────────╯

$ python ./14_mutex.py --help
usage: ./14_mutex.py [-h] [OPTIONS]

Demonstrate mutually exclusive argument groups.

╭─ options ──────────────────────────────────────────╮
│ -h, --help      show this help message and exit    │
╰────────────────────────────────────────────────────╯
╭─ output target ────────────────────────────────────╮
│ Exactly one argument must be passed in. (required) │
│ ────────────────────────────────────────────────── │
│ --target-stream {stdout,stderr}                    │
│                 (default: None)                    │
│ --target-file PATH                                 │
│                 (default: None)                    │
╰────────────────────────────────────────────────────╯
╭─ verbosity level ──────────────────────────────────╮
│ At most one argument can be overridden.            │
│ ────────────────────────────────────────────────── │
│ --verbose       (default: False)                   │
│ --very-verbose  (default: False)                   │
╰────────────────────────────────────────────────────╯

$ python ./14_mutex.py --target-stream stdout

$ python ./14_mutex.py --target-file /tmp/output.txt

$ python ./14_mutex.py --target-stream stdout --verbose
target_stream='stdout' target_file=None

$ python ./14_mutex.py --target-file /tmp/output.txt --very-verbose
target_stream=None target_file=PosixPath('/tmp/output.txt')
target_stream=None target_file=PosixPath('/tmp/output.txt')

$ python ./14_mutex.py --target-stream stdout --target-file /tmp/output.txt
╭─ Mutually exclusive arguments ────────────────────────────────────────╮
│ Arguments --target-stream and --target-file are not allowed together! │
│ ───────────────────────────────────────────────────────────────────── │
│ For full helptext, run ./14_mutex.py --help                           │
╰───────────────────────────────────────────────────────────────────────╯

$ python ./14_mutex.py --target-stream stdout --verbose --very-verbose
╭─ Mutually exclusive arguments ───────────────────────────────────╮
│ Arguments --verbose and --very-verbose are not allowed together! │
│ ──────────────────────────────────────────────────────────────── │
│ For full helptext, run ./14_mutex.py --help                      │
╰──────────────────────────────────────────────────────────────────╯