.. Comment: this file is automatically generated by `update_example_docs.py`.
   It should not be modified manually.

.. _example-category-basics:

Basics
======

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


.. _example-01_functions:

Functions
---------

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


.. code-block:: python
    :linenos:

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

.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./01_functions.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./01_functions.py [-h] --field1 <span style="font-weight: bold">STR</span> [--field2 <span style="font-weight: bold">INT</span>]
    
    Function, whose arguments will be populated from a CLI interface.
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">─────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help    <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                    </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --field1 <span style="font-weight: bold">STR  </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> string</span><span style="font-weight: lighter"> field.</span> <span style="color: #e60000">(required)                         </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --field2 <span style="font-weight: bold">INT  </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> numeric</span><span style="font-weight: lighter"> field,</span><span style="font-weight: lighter"> with</span><span style="font-weight: lighter"> a</span><span style="font-weight: lighter"> default</span><span style="font-weight: lighter"> value.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 3)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">───────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./01_functions.py --field1 hello</strong>
    hello 3
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./01_functions.py --field1 hello --field2 10</strong>
    hello 10
    </pre>
.. _example-02_dataclasses:

Dataclasses
-----------

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


.. code-block:: python
    :linenos:

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

.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./02_dataclasses.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./02_dataclasses.py [-h] --field1 <span style="font-weight: bold">STR</span> [--field2 <span style="font-weight: bold">INT</span>]
    
    Description. This should show up in the helptext!
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">─────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help    <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                    </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --field1 <span style="font-weight: bold">STR  </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> string</span><span style="font-weight: lighter"> field.</span> <span style="color: #e60000">(required)                         </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --field2 <span style="font-weight: bold">INT  </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> numeric</span><span style="font-weight: lighter"> field,</span><span style="font-weight: lighter"> with</span><span style="font-weight: lighter"> a</span><span style="font-weight: lighter"> default</span><span style="font-weight: lighter"> value.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 3)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">───────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>

We can override ``field1`` and ``field2``:

.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./02_dataclasses.py --field1 hello</strong>
    Args(field1='hello', field2=3)
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./02_dataclasses.py --field1 hello --field2 5</strong>
    Args(field1='hello', field2=5)
    </pre>
.. _example-03_multivalue:

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 :py:class:`typing.List` and :py:data:`typing.Tuple`.


.. code-block:: python
    :linenos:

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

.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./03_multivalue.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./03_multivalue.py [-h] --source-paths <span style="font-weight: bold">[PATH</span><span style="font-weight: bold"> [PATH</span><span style="font-weight: bold"> ...]]</span> [--dimensions <span style="font-weight: bold">INT</span><span style="font-weight: bold"> INT</span>]
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help            <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit   </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --source-paths <span style="font-weight: bold">[PATH</span><span style="font-weight: bold"> [PATH</span><span style="font-weight: bold"> ...]]                        </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                       <span style="font-weight: lighter">This</span><span style="font-weight: lighter"> can</span><span style="font-weight: lighter"> be</span><span style="font-weight: lighter"> multiple!</span> <span style="color: #e60000">(required)  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --dimensions <span style="font-weight: bold">INT</span><span style="font-weight: bold"> INT  </span><span style="font-weight: lighter">Height</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> width.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 32</span><span style="color: #008080"> 32)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>

We can override arguments:

.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./03_multivalue.py --source-paths ./data --dimensions 16 16</strong>
    Config(source_paths=(PosixPath('data'),), dimensions=(16, 16))
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./03_multivalue.py --source-paths ./data1 ./data2</strong>
    Config(source_paths=(PosixPath('data1'), PosixPath('data2')),
           dimensions=(32, 32))
    </pre>
.. _example-04_flags:

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 :class:`tyro.conf.FlagConversionOff`.


.. code-block:: python
    :linenos:

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




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./04_flags.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./04_flags.py [-h] [OPTIONS]
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help             <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --boolean <span style="font-weight: bold">{True,False}                                                      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                        <span style="font-weight: lighter">Boolean.</span><span style="font-weight: lighter"> This</span><span style="font-weight: lighter"> expects</span><span style="font-weight: lighter"> an</span><span style="font-weight: lighter"> explicit</span><span style="font-weight: lighter"> "True"</span><span style="font-weight: lighter"> or</span><span style="font-weight: lighter"> "False".</span>  <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                        <span style="color: #e60000">(required)                                           </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --optional-boolean <span style="font-weight: bold">{None,True,False}                                        </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                        <span style="font-weight: lighter">Optional</span><span style="font-weight: lighter"> boolean.</span><span style="font-weight: lighter"> Same</span><span style="font-weight: lighter"> as</span><span style="font-weight: lighter"> above,</span><span style="font-weight: lighter"> but</span><span style="font-weight: lighter"> can</span><span style="font-weight: lighter"> be</span><span style="font-weight: lighter"> omitted.</span>  <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                        <span style="color: #008080">(default:</span><span style="color: #008080"> None)                                      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --flag-a, --no-flag-a  <span style="font-weight: lighter">Pass</span><span style="font-weight: lighter"> --flag-a</span><span style="font-weight: lighter"> in</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> set</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> value</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> True.</span> <span style="color: #008080">(default:</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                        <span style="color: #008080">False)                                               </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --flag-b, --no-flag-b  <span style="font-weight: lighter">Pass</span><span style="font-weight: lighter"> --no-flag-b</span><span style="font-weight: lighter"> in</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> set</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> value</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> False.</span>       <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                        <span style="color: #008080">(default:</span><span style="color: #008080"> True)                                      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./04_flags.py --boolean True</strong>
    Args(boolean=True, optional_boolean=None, flag_a=False, flag_b=True)
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./04_flags.py --boolean False --flag-a</strong>
    Args(boolean=False, optional_boolean=None, flag_a=True, flag_b=True)
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./04_flags.py --boolean False --no-flag-b</strong>
    Args(boolean=False, optional_boolean=None, flag_a=False, flag_b=False)
    </pre>
.. _example-05_choices:

Choices
-------

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


.. code-block:: python
    :linenos:

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




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./05_choices.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./05_choices.py [-h] [--string <span style="font-weight: bold">{red,green}</span>] [--number <span style="font-weight: bold">{0,1,2}</span>]
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help            <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                       </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --string <span style="font-weight: bold">{red,green}  </span><span style="font-weight: lighter">We</span><span style="font-weight: lighter"> can</span><span style="font-weight: lighter"> use</span><span style="font-weight: lighter"> Literal[]</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> restrict</span><span style="font-weight: lighter"> the</span><span style="font-weight: lighter"> set</span><span style="font-weight: lighter"> of</span><span style="font-weight: lighter"> allowable </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                       <span style="font-weight: lighter">inputs,</span><span style="font-weight: lighter"> for</span><span style="font-weight: lighter"> example,</span><span style="font-weight: lighter"> over</span><span style="font-weight: lighter"> a</span><span style="font-weight: lighter"> set</span><span style="font-weight: lighter"> of</span><span style="font-weight: lighter"> strings.</span> <span style="color: #008080">(default: </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                       <span style="color: #008080">red)                                                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --number <span style="font-weight: bold">{0,1,2}      </span><span style="font-weight: lighter">Integers</span><span style="font-weight: lighter"> also</span><span style="font-weight: lighter"> work.</span><span style="font-weight: lighter"> (as</span><span style="font-weight: lighter"> well</span><span style="font-weight: lighter"> as</span><span style="font-weight: lighter"> booleans,</span><span style="font-weight: lighter"> enums,</span><span style="font-weight: lighter"> etc)</span>  <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                       <span style="color: #008080">(default:</span><span style="color: #008080"> 0)                                          </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./05_choices.py --string red</strong>
    Args(string='red', number=0)
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./05_choices.py --string blue</strong>
    <span style="color: #800000">╭</span><span style="color: #800000">─</span> <span style="font-weight: bold; color: #800000">Invalid</span><span style="font-weight: bold; color: #800000"> choice</span> <span style="color: #800000">─────────────────────────────────────────────────────────────╮</span>
    <span style="color: #800000">│</span> invalid choice <span style="font-weight: bold; color: #e60000">'blue'</span> for argument <span style="font-weight: bold">'--string'</span>. Expected one of <span style="color: #008080">('red',      </span> <span style="color: #800000">│</span>
    <span style="color: #800000">│</span> <span style="color: #008080">'green')</span>.                                                                    <span style="color: #800000">│</span>
    <span style="color: #800000">│</span> <span style="color: #800000">────────────────────────────────────────────────────────────────────────────</span> <span style="color: #800000">│</span>
    <span style="color: #800000">│</span> For full helptext, run <span style="font-weight: bold">./05_choices.py</span><span style="font-weight: bold"> --help                               </span> <span style="color: #800000">│</span>
    <span style="color: #800000">╰</span><span style="color: #800000">──────────────────────────────────────────────────────────────────────────────</span><span style="color: #800000">╯</span>
    </pre>
.. _example-06_enums:

Enums
-----

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


.. code-block:: python
    :linenos:

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




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./06_enums.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./06_enums.py [-h] [--color <span style="font-weight: bold">{RED,BLUE}</span>] [--opacity <span style="font-weight: bold">FLOAT</span>]
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help          <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --color <span style="font-weight: bold">{RED,BLUE}  </span><span style="font-weight: lighter">Color</span><span style="font-weight: lighter"> argument.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> RED)  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --opacity <span style="font-weight: bold">FLOAT     </span><span style="font-weight: lighter">Opacity</span><span style="font-weight: lighter"> argument.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 0.5)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./06_enums.py --color RED</strong>
    Config(color=&lt;Color.RED: 1&gt;, opacity=0.5)
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./06_enums.py --color BLUE --opacity 0.75</strong>
    Config(color=&lt;Color.BLUE: 2&gt;, opacity=0.75)
    </pre>
.. _example-07_unions:

Unions
------

:code:`X | Y` or :py:data:`typing.Union` can be used to expand inputs to
multiple types.


.. code-block:: python
    :linenos:

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




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./07_unions.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./07_unions.py [-h] [OPTIONS]
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help                                                                   <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>       <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                                       </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --union-over-types <span style="font-weight: bold">INT|STR                                                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>       <span style="font-weight: lighter">Unions</span><span style="font-weight: lighter"> can</span><span style="font-weight: lighter"> be</span><span style="font-weight: lighter"> used</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> specify</span><span style="font-weight: lighter"> multiple</span><span style="font-weight: lighter"> allowable</span><span style="font-weight: lighter"> types.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 0)  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --string-or-enum <span style="font-weight: bold">{red,green,RED,GREEN,BLUE}                                 </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>       <span style="font-weight: lighter">Unions</span><span style="font-weight: lighter"> can</span><span style="font-weight: lighter"> be</span><span style="font-weight: lighter"> used</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> specify</span><span style="font-weight: lighter"> multiple</span><span style="font-weight: lighter"> allowable</span><span style="font-weight: lighter"> types.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> red)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --union-over-tuples <span style="font-weight: bold">{INT</span><span style="font-weight: bold"> INT}|STR                                           </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>       <span style="font-weight: lighter">Unions</span><span style="font-weight: lighter"> also</span><span style="font-weight: lighter"> work</span><span style="font-weight: lighter"> over</span><span style="font-weight: lighter"> more</span><span style="font-weight: lighter"> complex</span><span style="font-weight: lighter"> nested</span><span style="font-weight: lighter"> types.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 1)         </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --tuple-of-string-or-enum <span style="font-weight: bold">[{red,green,RED,GREEN,BLUE}</span><span style="font-weight: bold"> [{red,</span><span style="font-weight: bold">green,</span><span style="font-weight: bold">RED,</span><span style="font-weight: bold">GREEN,</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> <span style="font-weight: bold">BLUE}</span><span style="font-weight: bold"> ...]]                                                                 </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>       <span style="font-weight: lighter">And</span><span style="font-weight: lighter"> can</span><span style="font-weight: lighter"> be</span><span style="font-weight: lighter"> nested</span><span style="font-weight: lighter"> in</span><span style="font-weight: lighter"> other</span><span style="font-weight: lighter"> types.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> red</span><span style="color: #008080"> RED)                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --integer <span style="font-weight: bold">{None,0,1,2,3}                                                    </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>       <span style="font-weight: lighter">Optional[T]</span><span style="font-weight: lighter"> is</span><span style="font-weight: lighter"> equivalent</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> `T</span><span style="font-weight: lighter"> |</span><span style="font-weight: lighter"> None`.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> None)              </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./07_unions.py --union-over-types 3</strong>
    Args(union_over_types=3,
         string_or_enum='red',
         union_over_tuples=('1',),
         tuple_of_string_or_enum=('red', &lt;Color.RED: 1&gt;),
         integer=None)
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./07_unions.py --union-over-types three</strong>
    Args(union_over_types='three',
         string_or_enum='red',
         union_over_tuples=('1',),
         tuple_of_string_or_enum=('red', &lt;Color.RED: 1&gt;),
         integer=None)
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./07_unions.py --integer None</strong>
    Args(union_over_types=0,
         string_or_enum='red',
         union_over_tuples=('1',),
         tuple_of_string_or_enum=('red', &lt;Color.RED: 1&gt;),
         integer=None)
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./07_unions.py --integer 0</strong>
    Args(union_over_types=0,
         string_or_enum='red',
         union_over_tuples=('1',),
         tuple_of_string_or_enum=('red', &lt;Color.RED: 1&gt;),
         integer=0)
    </pre>
.. _example-08_positional:

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 :class:`tyro.conf.Positional`.


.. code-block:: python
    :linenos:

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




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python 08_positional.py --help</strong>
    <span style="font-weight: bold">usage:</span> 08_positional.py [-h] <span style="font-weight: bold">PATH</span> <span style="font-weight: bold">PATH</span> [--verbose | --no-verbose]
    
    Command-line interface defined using a function signature. This docstring is parsed to generate helptext.
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">positional</span><span style="font-weight: lighter; color: #808080"> arguments</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> PATH                     <span style="font-weight: lighter">Source</span><span style="font-weight: lighter"> path.</span> <span style="color: #e60000">(required)                     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> PATH                     <span style="font-weight: lighter">Destination</span><span style="font-weight: lighter"> path.</span> <span style="color: #e60000">(required)                </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">───────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">─────────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help               <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit             </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --verbose, --no-verbose  <span style="font-weight: lighter">Explain</span><span style="font-weight: lighter"> what</span><span style="font-weight: lighter"> is</span><span style="font-weight: lighter"> being</span><span style="font-weight: lighter"> done.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> False)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">───────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python 08_positional.py ./a ./b</strong>
    source=PosixPath('a')
    dest=PosixPath('b')
    verbose=False
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python 08_positional.py ./test1 ./test2 --verbose</strong>
    source=PosixPath('test1')
    dest=PosixPath('test2')
    verbose=True
    </pre>
.. _example-09_conf:

Configuration via typing.Annotated[]
------------------------------------

The :mod:`tyro.conf` module contains utilities that can be used in conjunction
with :py:data:`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
:func:`tyro.cli`.

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


.. code-block:: python
    :linenos:

    # 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,)))




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./09_conf.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./09_conf.py [-h] [OPTIONS]
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">positional</span><span style="font-weight: lighter; color: #808080"> arguments</span> <span style="font-weight: lighter; color: #808080">───────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> INT                      <span style="font-weight: lighter">A</span><span style="font-weight: lighter"> numeric</span><span style="font-weight: lighter"> field</span><span style="font-weight: lighter"> parsed</span><span style="font-weight: lighter"> as</span><span style="font-weight: lighter"> a</span><span style="font-weight: lighter"> positional</span><span style="font-weight: lighter"> argument.</span>    <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                          <span style="color: #e60000">(required)                                         </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help               <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                    </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --boolean <span style="font-weight: bold">{True,False}   </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> boolean</span><span style="font-weight: lighter"> field.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> False)                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --fixed <span style="font-weight: bold; color: #e60000">{fixed}          </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> numeric</span><span style="font-weight: lighter"> field</span><span style="font-weight: lighter"> that</span><span style="font-weight: lighter"> can't</span><span style="font-weight: lighter"> be</span><span style="font-weight: lighter"> changed</span><span style="font-weight: lighter"> via</span><span style="font-weight: lighter"> the</span><span style="font-weight: lighter"> CLI.</span>  <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                          <span style="color: #008080">(fixed</span><span style="color: #008080"> to:</span><span style="color: #008080"> 5)                                      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --tuple-arg <span style="font-weight: bold">(INT,FLOAT)  </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> tuple</span><span style="font-weight: lighter"> field</span><span style="font-weight: lighter"> parsed</span><span style="font-weight: lighter"> as</span><span style="font-weight: lighter"> a</span><span style="font-weight: lighter"> single</span><span style="font-weight: lighter"> argument.</span>          <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                          <span style="color: #008080">(default:</span><span style="color: #008080"> '(1,</span><span style="color: #008080"> 2.0)')                              </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --renamed <span style="font-weight: bold">STRING         </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> field</span><span style="font-weight: lighter"> with</span><span style="font-weight: lighter"> manually</span><span style="font-weight: lighter"> overridden</span><span style="font-weight: lighter"> properties!</span>        <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                          <span style="color: #008080">(default:</span><span style="color: #008080"> Hello)                                   </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./09_conf.py 5 --boolean True</strong>
    Args(positional=5, boolean=True, fixed=5, tuple_arg=(1, 2.0), manual='Hello')
    </pre>
.. _example-10_aliases:

Argument aliases
----------------

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


.. code-block:: python
    :linenos:

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




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./10_aliases.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./10_aliases.py [-h] -b <span style="font-weight: bold">STR</span>
    
    Check out a branch.
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">─────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help            <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> -b <span style="font-weight: bold">STR</span>, --branch <span style="font-weight: bold">STR  </span><span style="color: #e60000">(required)                     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">───────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./10_aliases.py --branch main</strong>
    branch='main'
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./10_aliases.py -b main</strong>
    branch='main'
    </pre>
.. _example-11_type_aliases_py312:

Type aliases (3.12+)
--------------------

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


.. code-block:: python
    :linenos:

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




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./11_type_aliases_py312.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./11_type_aliases_py312.py [-h] [--field2 <span style="font-weight: bold">INT</span>] --field1.a <span style="font-weight: bold">INT</span> --field1.b <span style="font-weight: bold">STR</span>
    
    Description. This should show up in the helptext!
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">───────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help      <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                    </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --field2 <span style="font-weight: bold">INT    </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> numeric</span><span style="font-weight: lighter"> field,</span><span style="font-weight: lighter"> with</span><span style="font-weight: lighter"> a</span><span style="font-weight: lighter"> default</span><span style="font-weight: lighter"> value.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 3)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">─────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">field1</span><span style="font-weight: lighter; color: #808080"> options</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> A field.                                                            <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> <span style="font-weight: lighter; color: #808080">───────────────────────────────────────────────────────────────────</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --field1.a <span style="font-weight: bold">INT  </span><span style="color: #e60000">(required)                                         </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --field1.b <span style="font-weight: bold">STR  </span><span style="color: #e60000">(required)                                         </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">─────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>
.. _example-12_counters:

Counters
--------

Repeatable 'counter' arguments can be specified via :data:`tyro.conf.UseCounterAction`.


.. code-block:: python
    :linenos:

    # 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,))




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./12_counters.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./12_counters.py [-h] [--verbosity] [-v]
    
    Example showing how to use counter actions.
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help               <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                    </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --verbosity              <span style="font-weight: lighter">Verbosity</span><span style="font-weight: lighter"> level.</span> <span style="color: #008080">(repeatable)                      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> -v, --aliased-verbosity  <span style="font-weight: lighter">Same</span><span style="font-weight: lighter"> as</span><span style="font-weight: lighter"> above,</span><span style="font-weight: lighter"> but</span><span style="font-weight: lighter"> can</span><span style="font-weight: lighter"> also</span><span style="font-weight: lighter"> be</span><span style="font-weight: lighter"> specified</span><span style="font-weight: lighter"> with</span><span style="font-weight: lighter"> -v,  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                          <span style="font-weight: lighter">-vv,</span><span style="font-weight: lighter"> -vvv,</span><span style="font-weight: lighter"> etc.</span> <span style="color: #008080">(repeatable)                       </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./12_counters.py --verbosity</strong>
    Verbosity level: 1
    Verbosity level (aliased): 0
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./12_counters.py --verbosity --verbosity</strong>
    Verbosity level: 2
    Verbosity level (aliased): 0
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./12_counters.py -vvv</strong>
    Verbosity level: 0
    Verbosity level (aliased): 3
    </pre>
.. _example-13_classes:

Instantiating classes
---------------------

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


.. code-block:: python
    :linenos:

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




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./13_classes.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./13_classes.py [-h] --field1 <span style="font-weight: bold">STR</span> --field2 <span style="font-weight: bold">INT</span> [--flag | --no-flag]
    
    Arguments.
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">───────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help         <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --field1 <span style="font-weight: bold">STR       </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> string</span><span style="font-weight: lighter"> field.</span> <span style="color: #e60000">(required)      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --field2 <span style="font-weight: bold">INT       </span><span style="font-weight: lighter">A</span><span style="font-weight: lighter"> numeric</span><span style="font-weight: lighter"> field.</span> <span style="color: #e60000">(required)     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --flag, --no-flag  <span style="font-weight: lighter">A</span><span style="font-weight: lighter"> boolean</span><span style="font-weight: lighter"> flag.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> False)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">─────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./13_classes.py --field1 hello --field2 7</strong>
    ['hello', 7, False]
    </pre>
.. _example-14_mutex:

Mutually exclusive groups
-------------------------

:func:`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.


.. code-block:: python
    :linenos:

    # 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),
        )




.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./14_mutex.py</strong>
    <span style="color: #800000">╭</span><span style="color: #800000">─</span> <span style="font-weight: bold; color: #800000">Required</span><span style="font-weight: bold; color: #800000"> mutex</span><span style="font-weight: bold; color: #800000"> group</span> <span style="color: #800000">──────────────────────╮</span>
    <span style="color: #800000">│</span> Missing required argument group:            <span style="color: #800000">│</span>
    <span style="color: #800000">│</span>   • --target-stream, --target-file          <span style="color: #800000">│</span>
    <span style="color: #800000">│</span> <span style="color: #800000">───────────────────────────────────────────</span> <span style="color: #800000">│</span>
    <span style="color: #800000">│</span> For full helptext, run <span style="font-weight: bold">./14_mutex.py</span><span style="font-weight: bold"> --help</span> <span style="color: #800000">│</span>
    <span style="color: #800000">╰</span><span style="color: #800000">─────────────────────────────────────────────</span><span style="color: #800000">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./14_mutex.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./14_mutex.py [-h] [OPTIONS]
    
    Demonstrate mutually exclusive argument groups.
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">──────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help      <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit   </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">output</span><span style="font-weight: lighter; color: #808080"> target</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> Exactly one argument must be passed in. <span style="color: #e60000">(required)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> <span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --target-stream <span style="font-weight: bold">{stdout,stderr}                   </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                 <span style="color: #008080">(default:</span><span style="color: #008080"> None)                   </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --target-file <span style="font-weight: bold">PATH                                </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                 <span style="color: #008080">(default:</span><span style="color: #008080"> None)                   </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">verbosity</span><span style="font-weight: lighter; color: #808080"> level</span> <span style="font-weight: lighter; color: #808080">──────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> At most one argument can be overridden.            <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> <span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --verbose       <span style="color: #008080">(default:</span><span style="color: #008080"> False)                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --very-verbose  <span style="color: #008080">(default:</span><span style="color: #008080"> False)                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./14_mutex.py --target-stream stdout</strong>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./14_mutex.py --target-file /tmp/output.txt</strong>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./14_mutex.py --target-stream stdout --verbose</strong>
    target_stream='stdout' target_file=None
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./14_mutex.py --target-file /tmp/output.txt --very-verbose</strong>
    target_stream=None target_file=PosixPath('/tmp/output.txt')
    target_stream=None target_file=PosixPath('/tmp/output.txt')
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./14_mutex.py --target-stream stdout --target-file /tmp/output.txt</strong>
    <span style="color: #800000">╭</span><span style="color: #800000">─</span> <span style="font-weight: bold; color: #800000">Mutually</span><span style="font-weight: bold; color: #800000"> exclusive</span><span style="font-weight: bold; color: #800000"> arguments</span> <span style="color: #800000">────────────────────────────────────────╮</span>
    <span style="color: #800000">│</span> Arguments --target-stream and --target-file are not allowed together! <span style="color: #800000">│</span>
    <span style="color: #800000">│</span> <span style="color: #800000">─────────────────────────────────────────────────────────────────────</span> <span style="color: #800000">│</span>
    <span style="color: #800000">│</span> For full helptext, run <span style="font-weight: bold">./14_mutex.py</span><span style="font-weight: bold"> --help                          </span> <span style="color: #800000">│</span>
    <span style="color: #800000">╰</span><span style="color: #800000">───────────────────────────────────────────────────────────────────────</span><span style="color: #800000">╯</span>
    </pre>



.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./14_mutex.py --target-stream stdout --verbose --very-verbose</strong>
    <span style="color: #800000">╭</span><span style="color: #800000">─</span> <span style="font-weight: bold; color: #800000">Mutually</span><span style="font-weight: bold; color: #800000"> exclusive</span><span style="font-weight: bold; color: #800000"> arguments</span> <span style="color: #800000">───────────────────────────────────╮</span>
    <span style="color: #800000">│</span> Arguments --verbose and --very-verbose are not allowed together! <span style="color: #800000">│</span>
    <span style="color: #800000">│</span> <span style="color: #800000">────────────────────────────────────────────────────────────────</span> <span style="color: #800000">│</span>
    <span style="color: #800000">│</span> For full helptext, run <span style="font-weight: bold">./14_mutex.py</span><span style="font-weight: bold"> --help                     </span> <span style="color: #800000">│</span>
    <span style="color: #800000">╰</span><span style="color: #800000">──────────────────────────────────────────────────────────────────</span><span style="color: #800000">╯</span>
    </pre>
.. _example-15_compact_help:

Compact help
------------

When a configuration has many fields, the help text can become verbose and
difficult to scan. The ``compact_help`` parameter in :func:`tyro.cli()` enables
a more succinct format that omits field descriptions.

In compact mode, users can still access full descriptions via ``--help-verbose``.


.. code-block:: python
    :linenos:

    # 15_compact_help.py
    from dataclasses import dataclass
    from typing import Literal

    import tyro

    @dataclass
    class ServerConfig:
        """Configuration for a web server."""

        # Network settings.
        host: str = "0.0.0.0"
        """Hostname to bind the server to."""

        port: int = 8000
        """Port number to listen on."""

        workers: int = 4
        """Number of worker processes."""

        timeout: int = 30
        """Request timeout in seconds."""

        # Security settings.
        ssl_enabled: bool = False
        """Enable SSL/TLS encryption."""

        ssl_cert_path: str = "/etc/ssl/cert.pem"
        """Path to SSL certificate file."""

        ssl_key_path: str = "/etc/ssl/key.pem"
        """Path to SSL private key file."""

        # Application settings.
        max_request_size: int = 10485760
        """Maximum request size in bytes."""

        cors_origins: str = "*"
        """Allowed CORS origins (comma-separated)."""

        log_level: Literal["debug", "info", "warning", "error"] = "info"
        """Logging level for the application."""

        log_file: str = "/var/log/server.log"
        """Path to log file."""

        # Performance settings.
        cache_enabled: bool = True
        """Enable response caching."""

        cache_size: int = 1000
        """Maximum number of cached responses."""

        compression_enabled: bool = True
        """Enable response compression."""

        keepalive_timeout: int = 5
        """Keep-alive connection timeout in seconds."""

        # Database settings.
        db_host: str = "localhost"
        """Database server hostname."""

        db_port: int = 5432
        """Database server port."""

        db_name: str = "appdb"
        """Database name."""

    if __name__ == "__main__":
        # Parse with compact_help=True to enable compact mode.
        config = tyro.cli(ServerConfig, compact_help=True)
        print(f"Starting server with config:\n{config}")


Compact mode (default with compact_help=True):

.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./15_compact_help.py --help</strong>
    <span style="font-weight: bold">usage:</span> ./15_compact_help.py [-h] [OPTIONS]
    
    Configuration for a web server.
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">───────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> -H, --help-verbose <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> verbose</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> with</span><span style="font-weight: lighter"> full</span><span style="font-weight: lighter"> descriptions    </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --host <span style="font-weight: bold">STR</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 0.0.0.0)                                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --port <span style="font-weight: bold">INT</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 8000)                                     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --workers <span style="font-weight: bold">INT</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 4)                                     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --timeout <span style="font-weight: bold">INT</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 30)                                    </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --ssl-enabled, --no-ssl-enabled <span style="color: #008080">(default:</span><span style="color: #008080"> False)               </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --ssl-cert-path <span style="font-weight: bold">STR</span> <span style="color: #008080">(default:</span><span style="color: #008080"> /etc/ssl/cert.pem)               </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --ssl-key-path <span style="font-weight: bold">STR</span> <span style="color: #008080">(default:</span><span style="color: #008080"> /etc/ssl/key.pem)                 </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --max-request-size <span style="font-weight: bold">INT</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 10485760)                     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --cors-origins <span style="font-weight: bold">STR</span> <span style="color: #008080">(default:</span><span style="color: #008080"> '*')                              </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --log-level <span style="font-weight: bold">{debug,info,warning,error}</span> <span style="color: #008080">(default:</span><span style="color: #008080"> info)         </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --log-file <span style="font-weight: bold">STR</span> <span style="color: #008080">(default:</span><span style="color: #008080"> /var/log/server.log)                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --cache-enabled, --no-cache-enabled <span style="color: #008080">(default:</span><span style="color: #008080"> True)            </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --cache-size <span style="font-weight: bold">INT</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 1000)                               </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --compression-enabled, --no-compression-enabled <span style="color: #008080">(default:</span><span style="color: #008080"> True)</span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --keepalive-timeout <span style="font-weight: bold">INT</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 5)                           </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --db-host <span style="font-weight: bold">STR</span> <span style="color: #008080">(default:</span><span style="color: #008080"> localhost)                             </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --db-port <span style="font-weight: bold">INT</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 5432)                                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --db-name <span style="font-weight: bold">STR</span> <span style="color: #008080">(default:</span><span style="color: #008080"> appdb)                                 </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">─────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>

Verbose mode (access full descriptions):

.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./15_compact_help.py --help-verbose</strong>
    <span style="font-weight: bold">usage:</span> ./15_compact_help.py [-h] [OPTIONS]
    
    Configuration for a web server.
    
    <span style="font-weight: lighter; color: #808080">╭</span><span style="font-weight: lighter; color: #808080">─</span> <span style="font-weight: lighter; color: #808080">options</span> <span style="font-weight: lighter; color: #808080">────────────────────────────────────────────────────────────────────╮</span>
    <span style="font-weight: lighter; color: #808080">│</span> -h, --help           <span style="font-weight: lighter">show</span><span style="font-weight: lighter"> this</span><span style="font-weight: lighter"> help</span><span style="font-weight: lighter"> message</span><span style="font-weight: lighter"> and</span><span style="font-weight: lighter"> exit                        </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --host <span style="font-weight: bold">STR           </span><span style="font-weight: lighter">Hostname</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> bind</span><span style="font-weight: lighter"> the</span><span style="font-weight: lighter"> server</span><span style="font-weight: lighter"> to.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 0.0.0.0)     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --port <span style="font-weight: bold">INT           </span><span style="font-weight: lighter">Port</span><span style="font-weight: lighter"> number</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> listen</span><span style="font-weight: lighter"> on.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 8000)              </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --workers <span style="font-weight: bold">INT        </span><span style="font-weight: lighter">Number</span><span style="font-weight: lighter"> of</span><span style="font-weight: lighter"> worker</span><span style="font-weight: lighter"> processes.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 4)               </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --timeout <span style="font-weight: bold">INT        </span><span style="font-weight: lighter">Request</span><span style="font-weight: lighter"> timeout</span><span style="font-weight: lighter"> in</span><span style="font-weight: lighter"> seconds.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 30)              </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --ssl-enabled, --no-ssl-enabled                                              <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                      <span style="font-weight: lighter">Enable</span><span style="font-weight: lighter"> SSL/TLS</span><span style="font-weight: lighter"> encryption.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> False)            </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --ssl-cert-path <span style="font-weight: bold">STR  </span><span style="font-weight: lighter">Path</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> SSL</span><span style="font-weight: lighter"> certificate</span><span style="font-weight: lighter"> file.</span> <span style="color: #008080">(default:                </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                      <span style="color: #008080">/etc/ssl/cert.pem)                                     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --ssl-key-path <span style="font-weight: bold">STR   </span><span style="font-weight: lighter">Path</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> SSL</span><span style="font-weight: lighter"> private</span><span style="font-weight: lighter"> key</span><span style="font-weight: lighter"> file.</span> <span style="color: #008080">(default:                </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                      <span style="color: #008080">/etc/ssl/key.pem)                                      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --max-request-size <span style="font-weight: bold">INT                                                      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                      <span style="font-weight: lighter">Maximum</span><span style="font-weight: lighter"> request</span><span style="font-weight: lighter"> size</span><span style="font-weight: lighter"> in</span><span style="font-weight: lighter"> bytes.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 10485760)     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --cors-origins <span style="font-weight: bold">STR   </span><span style="font-weight: lighter">Allowed</span><span style="font-weight: lighter"> CORS</span><span style="font-weight: lighter"> origins</span><span style="font-weight: lighter"> (comma-separated).</span> <span style="color: #008080">(default:</span><span style="color: #008080"> '*') </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --log-level <span style="font-weight: bold">{debug,info,warning,error}                                      </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                      <span style="font-weight: lighter">Logging</span><span style="font-weight: lighter"> level</span><span style="font-weight: lighter"> for</span><span style="font-weight: lighter"> the</span><span style="font-weight: lighter"> application.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> info)     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --log-file <span style="font-weight: bold">STR       </span><span style="font-weight: lighter">Path</span><span style="font-weight: lighter"> to</span><span style="font-weight: lighter"> log</span><span style="font-weight: lighter"> file.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> /var/log/server.log)       </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --cache-enabled, --no-cache-enabled                                          <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                      <span style="font-weight: lighter">Enable</span><span style="font-weight: lighter"> response</span><span style="font-weight: lighter"> caching.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> True)               </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --cache-size <span style="font-weight: bold">INT     </span><span style="font-weight: lighter">Maximum</span><span style="font-weight: lighter"> number</span><span style="font-weight: lighter"> of</span><span style="font-weight: lighter"> cached</span><span style="font-weight: lighter"> responses.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 1000)    </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --compression-enabled, --no-compression-enabled                              <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                      <span style="font-weight: lighter">Enable</span><span style="font-weight: lighter"> response</span><span style="font-weight: lighter"> compression.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> True)           </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --keepalive-timeout <span style="font-weight: bold">INT                                                     </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span>                      <span style="font-weight: lighter">Keep-alive</span><span style="font-weight: lighter"> connection</span><span style="font-weight: lighter"> timeout</span><span style="font-weight: lighter"> in</span><span style="font-weight: lighter"> seconds.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 5) </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --db-host <span style="font-weight: bold">STR        </span><span style="font-weight: lighter">Database</span><span style="font-weight: lighter"> server</span><span style="font-weight: lighter"> hostname.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> localhost)         </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --db-port <span style="font-weight: bold">INT        </span><span style="font-weight: lighter">Database</span><span style="font-weight: lighter"> server</span><span style="font-weight: lighter"> port.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> 5432)                  </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">│</span> --db-name <span style="font-weight: bold">STR        </span><span style="font-weight: lighter">Database</span><span style="font-weight: lighter"> name.</span> <span style="color: #008080">(default:</span><span style="color: #008080"> appdb)                        </span> <span style="font-weight: lighter; color: #808080">│</span>
    <span style="font-weight: lighter; color: #808080">╰</span><span style="font-weight: lighter; color: #808080">──────────────────────────────────────────────────────────────────────────────</span><span style="font-weight: lighter; color: #808080">╯</span>
    </pre>

Actually run it:

.. raw:: html

    <pre class="highlight" style="padding: 1em; box-sizing: border-box; font-size: 0.85em; line-height: 1.2em;">
    <strong style="opacity: 0.7; padding-bottom: 0.5em; display: inline-block"><span style="user-select: none">$ </span>python ./15_compact_help.py --host localhost --port 8080</strong>
    Starting server with config:
    ServerConfig(host='localhost', port=8080, workers=4, timeout=30, ssl_enabled=False, ssl_cert_path='/etc/ssl/cert.pem', ssl_key_path='/etc/ssl/key.pem', max_request_size=10485760, cors_origins='*', log_level='info', log_file='/var/log/server.log', cache_enabled=True, cache_size=1000, compression_enabled=True, keepalive_timeout=5, db_host='localhost', db_port=5432, db_name='appdb')
    </pre>