Subcommands

In these examples, we show how tyro.cli() can be used to create CLI interfaces with subcommands.

Subcommands are Unions

All of tyro’s subcommand features are built using unions over struct types (typically dataclasses). Subcommands are used to choose between types in the union; arguments are then populated from the chosen type.

Note

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

# 01_subcommands.py
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

if __name__ == "__main__":
    cmd = tyro.cli(Checkout | Commit)
    print(cmd)

Print the helptext. This will show the available subcommands:

$ python ./01_subcommands.py --help
usage: 01_subcommands.py [-h] {checkout,commit}

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

The commit subcommand:

$ python ./01_subcommands.py commit --help
usage: 01_subcommands.py commit [-h] --message STR

Commit changes.

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

$ python ./01_subcommands.py commit --message hello
Commit(message='hello')

The checkout subcommand:

$ python ./01_subcommands.py checkout --help
usage: 01_subcommands.py checkout [-h] --branch STR

Checkout a branch.

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

$ python ./01_subcommands.py checkout --branch main
Checkout(branch='main')

Subcommands as Function Arguments

A subcommand will be created for each input annotated with a union over struct types.

Note

To prevent tyro.cli() from converting a Union type into a subcommand, use tyro.conf.AvoidSubcommands.

Note

Argument ordering for subcommands can be tricky. In the example below, --shared-arg must always come before the subcommand. As an option for alleviating this, see tyro.conf.ConsolidateSubcommandArgs.

# 02_subcommands_in_func.py
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

def main(
    shared_arg: int,
    cmd: Checkout | Commit = Checkout(branch="default"),
):
    print(f"{shared_arg=}")
    print(cmd)

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

Print the helptext. This will show the available subcommands:

$ python ./02_subcommands_in_func.py --help
usage: 02_subcommands_in_func.py [-h] --shared-arg INT
                                 [{cmd:checkout,cmd:commit}]

╭─ options ───────────────────────────────────────────────╮
│ -h, --help              show this help message and exit │
│ --shared-arg INT        (required)                      │
╰─────────────────────────────────────────────────────────╯
╭─ optional subcommands ──────────────────────────────────╮
│ (default: cmd:checkout)                                 │
│ ──────────────────────────────────────────              │
│ [{cmd:checkout,cmd:commit}]                             │
│     cmd:checkout        Checkout a branch.              │
│     cmd:commit          Commit changes.                 │
╰─────────────────────────────────────────────────────────╯

Using the default subcommand:

$ python ./02_subcommands_in_func.py --shared-arg 100
shared_arg=100
Checkout(branch='default')

Choosing a different subcommand:

$ python ./02_subcommands_in_func.py --shared-arg 100 cmd:commit --cmd.message 'Hello!'
shared_arg=100
Commit(message='Hello!')

Sequenced Subcommands

Multiple unions over struct types are populated using a series of subcommands.

# 03_multiple_subcommands.py
from __future__ import annotations

import dataclasses
from typing import Literal

import tyro

# Possible dataset configurations.

@dataclasses.dataclass
class Mnist:
    binary: bool = False
    """Set to load binary version of MNIST dataset."""

@dataclasses.dataclass
class ImageNet:
    subset: Literal[50, 100, 1000]
    """Choose between ImageNet-50, ImageNet-100, ImageNet-1000, etc."""

# Possible optimizer configurations.

@dataclasses.dataclass
class Adam:
    learning_rate: float = 1e-3
    betas: tuple[float, float] = (0.9, 0.999)

@dataclasses.dataclass
class Sgd:
    learning_rate: float = 3e-4

# Train script.

def train(
    dataset: Mnist | ImageNet = Mnist(),
    optimizer: Adam | Sgd = Adam(),
) -> None:
    """Example training script.

    Args:
        dataset: Dataset to train on.
        optimizer: Optimizer to train with.

    Returns:
        None:
    """
    print(dataset)
    print(optimizer)

if __name__ == "__main__":
    tyro.cli(train, config=(tyro.conf.ConsolidateSubcommandArgs,))

We apply the tyro.conf.ConsolidateSubcommandArgs flag. This pushes all arguments to the end of the command:

$ python ./03_multiple_subcommands.py --help
usage: 03_multiple_subcommands.py [-h] {dataset:mnist,dataset:image-net}

Example training script.

╭─ options ─────────────────────────────────────────╮
│ -h, --help        show this help message and exit │
╰───────────────────────────────────────────────────╯
╭─ subcommands ─────────────────────────────────────╮
│ Dataset to train on.                              │
│ ─────────────────────────────────                 │
│ {dataset:mnist,dataset:image-net}                 │
│     dataset:mnist                                 │
│     dataset:image-net                             │
╰───────────────────────────────────────────────────╯

$ python ./03_multiple_subcommands.py dataset:mnist --help
usage: 03_multiple_subcommands.py dataset:mnist [-h]
                                                {optimizer:adam,optimizer:sgd}

╭─ options ─────────────────────────────────────────╮
│ -h, --help        show this help message and exit │
╰───────────────────────────────────────────────────╯
╭─ subcommands ─────────────────────────────────────╮
│ Optimizer to train with.                          │
│ ──────────────────────────────                    │
│ {optimizer:adam,optimizer:sgd}                    │
│     optimizer:adam                                │
│     optimizer:sgd                                 │
╰───────────────────────────────────────────────────╯

$ python ./03_multiple_subcommands.py dataset:mnist optimizer:adam --help
usage: 03_multiple_subcommands.py dataset:mnist optimizer:adam
       [-h] [--optimizer.learning-rate FLOAT] [--optimizer.betas FLOAT FLOAT]
       [--dataset.binary | --dataset.no-binary]

╭─ options ─────────────────────────────────────────────────────────╮
│ -h, --help                                                        │
│     show this help message and exit                               │
╰───────────────────────────────────────────────────────────────────╯
╭─ optimizer options ───────────────────────────────────────────────╮
│ --optimizer.learning-rate FLOAT                                   │
│     (default: 0.001)                                              │
│ --optimizer.betas FLOAT FLOAT                                     │
│     (default: 0.9 0.999)                                          │
╰───────────────────────────────────────────────────────────────────╯
╭─ dataset options ─────────────────────────────────────────────────╮
│ --dataset.binary, --dataset.no-binary                             │
│     Set to load binary version of MNIST dataset. (default: False) │
╰───────────────────────────────────────────────────────────────────╯

$ python ./03_multiple_subcommands.py dataset:mnist optimizer:adam --optimizer.learning-rate 3e-4 --dataset.binary
Mnist(binary=True)
Adam(learning_rate=0.0003, betas=(0.9, 0.999))

Decorator-based Subcommands

tyro.extras.SubcommandApp() provides a decorator-based API for subcommands, which is inspired by click.

# 04_decorator_subcommands.py
from tyro.extras import SubcommandApp

app = SubcommandApp()

@app.command
def greet(name: str, loud: bool = False) -> None:
    """Greet someone."""
    greeting = f"Hello, {name}!"
    if loud:
        greeting = greeting.upper()
    print(greeting)

@app.command(name="addition")
def add(a: int, b: int) -> None:
    """Add two numbers."""
    print(f"{a} + {b} = {a + b}")

if __name__ == "__main__":
    app.cli()

$ python 04_decorator_subcommands.py --help
usage: 04_decorator_subcommands.py [-h] {greet,addition}

╭─ options ───────────────────────────────────────────────╮
│ -h, --help              show this help message and exit │
╰─────────────────────────────────────────────────────────╯
╭─ subcommands ───────────────────────────────────────────╮
│ {greet,addition}                                        │
│     greet               Greet someone.                  │
│     addition            Add two numbers.                │
╰─────────────────────────────────────────────────────────╯

$ python 04_decorator_subcommands.py greet --help
usage: 04_decorator_subcommands.py greet [-h] --name STR [--loud | --no-loud]

Greet someone.

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

$ python 04_decorator_subcommands.py greet --name Alice
Hello, Alice!

$ python 04_decorator_subcommands.py greet --name Bob --loud
HELLO, BOB!

$ python 04_decorator_subcommands.py addition --help
usage: 04_decorator_subcommands.py addition [-h] --a INT --b INT

Add two numbers.

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

$ python 04_decorator_subcommands.py addition --a 5 --b 3
5 + 3 = 8

Subcommands from Functions

We provide a shorthand for generating a subcommand CLI from a dictionary. This is a thin wrapper around tyro.cli()’s more verbose, type-based API. If more generality is needed, the internal working are explained in the docs for tyro.extras.subcommand_cli_from_dict().

# 05_subcommands_func.py
import tyro

def checkout(branch: str) -> None:
    """Check out a branch."""
    print(f"{branch=}")

def commit(message: str, all: bool = False) -> None:
    """Make a commit."""
    print(f"{message=} {all=}")

if __name__ == "__main__":
    tyro.extras.subcommand_cli_from_dict(
        {
            "checkout": checkout,
            "commit": commit,
        }
    )

$ python ./05_subcommands_func.py --help
usage: 05_subcommands_func.py [-h] {checkout,commit}

╭─ options ───────────────────────────────────────────────╮
│ -h, --help              show this help message and exit │
╰─────────────────────────────────────────────────────────╯
╭─ subcommands ───────────────────────────────────────────╮
│ {checkout,commit}                                       │
│     checkout            Check out a branch.             │
│     commit              Make a commit.                  │
╰─────────────────────────────────────────────────────────╯

$ python ./05_subcommands_func.py commit --help
usage: 05_subcommands_func.py commit [-h] --message STR [--all | --no-all]

Make a commit.

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

$ python ./05_subcommands_func.py commit --message hello --all
message='hello' all=True

$ python ./05_subcommands_func.py checkout --help
usage: 05_subcommands_func.py checkout [-h] --branch STR

Check out a branch.

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

$ python ./05_subcommands_func.py checkout --branch main
branch='main'