Subcommands

Unions over nested types (classes or dataclasses) are populated using subcommands.

For configuring subcommands beyond what can be expressed with type annotations, see tyro.conf.subcommand().

from __future__ import annotations

import dataclasses

import tyro


@dataclasses.dataclass(frozen=True)
class Checkout:
    """Checkout a branch."""

    branch: str


@dataclasses.dataclass(frozen=True)
class Commit:
    """Commit changes."""

    message: str
    all: bool = False


def main(cmd: Checkout | Commit) -> None:
    print(cmd)


if __name__ == "__main__":
    # Note that we can also pass `Checkout | Command` directly into
    # `tyro.cli()`; this is understood by tyro and pyright, but unfortunately not by
    # mypy.
    tyro.cli(main)

---

python 02_nesting/02_subcommands.py --help

usage: 02_subcommands.py [-h] {cmd:checkout,cmd:commit}

╭─ options ─────────────────────────────────────────╮
│ -h, --help        show this help message and exit │
╰───────────────────────────────────────────────────╯
╭─ subcommands ─────────────────────────────────────╮
│ {cmd:checkout,cmd:commit}                         │
│     cmd:checkout  Checkout a branch.              │
│     cmd:commit    Commit changes.                 │
╰───────────────────────────────────────────────────╯

---

python 02_nesting/02_subcommands.py cmd:commit --help

usage: 02_subcommands.py cmd:commit [-h] --cmd.message STR
                                    [--cmd.all | --cmd.no-all]

Commit changes.

╭─ options ───────────────────────────────────────────────╮
│ -h, --help              show this help message and exit │
╰─────────────────────────────────────────────────────────╯
╭─ cmd options ───────────────────────────────────────────╮
│ --cmd.message STR       (required)                      │
│ --cmd.all, --cmd.no-all                                 │
│                         (default: False)                │
╰─────────────────────────────────────────────────────────╯

---

python 02_nesting/02_subcommands.py cmd:commit --cmd.message hello --cmd.all

Commit(message='hello', all=True)

---

python 02_nesting/02_subcommands.py cmd:checkout --help

usage: 02_subcommands.py cmd:checkout [-h] --cmd.branch STR

Checkout a branch.

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

---

python 02_nesting/02_subcommands.py cmd:checkout --cmd.branch main

Checkout(branch='main')