tyro._cli

Core public API.

Module Contents

tyro._cli.OutT
tyro._cli.cli(f: tyro._typing.TypeForm[OutT], *, prog: None | str = None, description: None | str = None, args: None | Sequence[str] = None, default: None | OutT = None, return_unknown_args: Literal[False] = False, use_underscores: bool = False, console_outputs: bool = True, config: None | Sequence[tyro.conf._markers.Marker] = None) → OutT[source]
tyro._cli.cli(f: tyro._typing.TypeForm[OutT], *, prog: None | str = None, description: None | str = None, args: None | Sequence[str] = None, default: None | OutT = None, return_unknown_args: Literal[True], use_underscores: bool = False, console_outputs: bool = True, config: None | Sequence[tyro.conf._markers.Marker] = None) → tuple[OutT, list[str]]
tyro._cli.cli(f: Callable[Ellipsis, OutT], *, prog: None | str = None, description: None | str = None, args: None | Sequence[str] = None, default: None = None, return_unknown_args: Literal[False] = False, use_underscores: bool = False, console_outputs: bool = True, config: None | Sequence[tyro.conf._markers.Marker] = None) → OutT
tyro._cli.cli(f: Callable[Ellipsis, OutT], *, prog: None | str = None, description: None | str = None, args: None | Sequence[str] = None, default: None = None, return_unknown_args: Literal[True], use_underscores: bool = False, console_outputs: bool = True, config: None | Sequence[tyro.conf._markers.Marker] = None) → tuple[OutT, list[str]]

Generate a command-line interface from type annotations and populate the target with arguments.

cli() is the core function of tyro. It takes a type-annotated function or class and automatically generates a command-line interface to populate it from user arguments.

Two main usage patterns are supported:

  1. With a function (CLI arguments become function parameters):

    import tyro

def main(a: str, b: str) -> None:
    print(a, b)

if __name__ == "__main__":
    tyro.cli(main)  # Parses CLI args, calls main() with them

  2. With a class (CLI arguments become object attributes):

    from dataclasses import dataclass
from pathlib import Path

import tyro

@dataclass
class Config:
    a: str
    b: str

if __name__ == "__main__":
    config = tyro.cli(Config)  # Parses CLI args, returns populated AppConfig
    print(f"Config: {config}")
Parameters:

  • f – The function or type to populate from command-line arguments. This must have type-annotated inputs for tyro to work correctly.

  • prog – The name of the program to display in the help text. If not specified, the script filename is used. This mirrors the argument from argparse.ArgumentParser().

  • description – The description text shown at the top of the help output. If not specified, the docstring of f is used. This mirrors the argument from argparse.ArgumentParser().

  • args – If provided, parse arguments from this sequence of strings instead of the command line. This is useful for testing or programmatic usage. This mirrors the argument from argparse.ArgumentParser.parse_args().

  • default – An instance to use for default values. This is only supported if f is a type like a dataclass or dictionary, not if f is a general callable like a function. This is useful for merging CLI arguments with values loaded from elsewhere, such as a config file.

  • return_unknown_args – If True, returns a tuple of the output and a list of unknown arguments that weren’t consumed by the parser. This mirrors the behavior of argparse.ArgumentParser.parse_known_args().

  • use_underscores – If True, uses underscores as word delimiters in the help text instead of hyphens. This only affects the displayed help; both underscores and hyphens are treated equivalently during parsing. The default (False) follows the GNU style guide for command-line options. https://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html

  • console_outputs – If set to False, suppresses parsing errors and help messages. This is useful in distributed settings where tyro.cli() is called from multiple workers but console output is only desired from the main process.

  • config – A sequence of configuration marker objects from tyro.conf. This allows applying markers globally instead of annotating individual fields. For example: tyro.cli(Config, config=(tyro.conf.PositionalRequiredArgs,))

Returns:

If f is a type (like a dataclass), returns an instance of that type populated with values from the command line. If f is a function, calls the function with arguments from the command line and returns its result. If return_unknown_args is True, returns a tuple of the result and a list of unused command-line arguments.

tyro._cli.get_parser(f: tyro._typing.TypeForm[OutT], *, prog: None | str = None, description: None | str = None, default: None | OutT = None, use_underscores: bool = False, console_outputs: bool = True, config: None | Sequence[tyro.conf._markers.Marker] = None) → tyro._argparse.ArgumentParser[source]
tyro._cli.get_parser(f: Callable[Ellipsis, OutT], *, prog: None | str = None, description: None | str = None, default: None | OutT = None, use_underscores: bool = False, console_outputs: bool = True, config: None | Sequence[tyro.conf._markers.Marker] = None) → tyro._argparse.ArgumentParser

Get the argparse.ArgumentParser object generated under-the-hood by tyro.cli(). Useful for tools like sphinx-argparse, argcomplete, etc.

For tab completion, we recommend using tyro.cli()’s built-in --tyro-write-completion flag.