Nested SubCommands¶

We'll now see how these same ideas can be extended for deeply nested commands.

Let's imagine that the same CLI program from the previous examples now needs to handle lands.

But a land could be a reign or town.

And each of those could have their own commands, like create and delete.

A CLI app for reigns¶

Let's start with a file reigns.py:

import typer

app = typer.Typer()


@app.command()
def conquer(name: str):
    print(f"Conquering reign: {name}")


@app.command()
def destroy(name: str):
    print(f"Destroying reign: {name}")


if __name__ == "__main__":
    app()

This is already a simple CLI program to manage reigns:

fast →💬 Check the helppython reigns.py --help
Usage: reigns.py [OPTIONS] COMMAND [ARGS]...

Options:
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the installation.
  --help                Show this message and exit.

Commands:
  conquer
  destroy

💬 Try itpython reigns.py conquer Cintra
Conquering reign: Cintra

python reigns.py destroy Mordor
Destroying reign: Mordor

restart ↻

A CLI app for towns¶

And now the equivalent for managing towns in towns.py:

Python 3.8+

import typer

app = typer.Typer()


@app.command()
def found(name: str):
    print(f"Founding town: {name}")


@app.command()
def burn(name: str):
    print(f"Burning town: {name}")


if __name__ == "__main__":
    app()

With it, you can manage towns:

fast →💬 Check the helppython towns.py --help
Usage: towns.py [OPTIONS] COMMAND [ARGS]...

Options:
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the installation.
  --help                Show this message and exit.

Commands:
  burn
  found

💬 Try itpython towns.py found "New Asgard"
Founding town: New Asgard

python towns.py burn Vizima
Burning town: Vizima

restart ↻

Manage the land in a CLI app¶

Now let's put the reigns and towns together in the same CLI program in lands.py:

Python 3.8+

import typer

import reigns
import towns

app = typer.Typer()
app.add_typer(reigns.app, name="reigns")
app.add_typer(towns.app, name="towns")

if __name__ == "__main__":
    app()

And now we have a single CLI program with a command (or command group) reigns that has its own commands. And another command towns with its own subcommands.

Check it:

fast →💬 Check the helppython lands.py --help
Usage: lands.py [OPTIONS] COMMAND [ARGS]...

Options:
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the installation.
  --help                Show this message and exit.

Commands:
  reigns
  towns

💬 We still have the help for reignspython lands.py reigns --help
Usage: lands.py reigns [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  conquer
  destroy

💬 And the help for townspython lands.py towns --help
Usage: lands.py towns [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  burn
  found

restart ↻

Now try it, manage the lands through the CLI:

fast →💬 Try the reigns commandpython lands.py reigns conquer Gondor
Conquering reign: Gondor

python lands.py reigns destroy Nilfgaard
Destroying reign: Nilfgaard

💬 Try the towns commandpython lands.py towns found Springfield
Founding town: Springfield

python lands.py towns burn Atlantis
Burning town: Atlantis

restart ↻

Deeply nested subcommands¶

Now let's say that all these commands in the lands.py CLI program should be part of the previous CLI program we built in the first example.

We want our CLI program to have these commands/command groups:

users:
- create
- delete
items:
- create
- delete
- sell
lands:
- reigns:
  - conquer
  - destroy
- towns:
  - found
  - burn

This already is a quite deeply nested "tree" of commands/command groups.

But to achieve that, we just have to add the lands Typer app to the same main.py file we already had:

Python 3.8+

import typer

import items
import lands
import users

app = typer.Typer()
app.add_typer(users.app, name="users")
app.add_typer(items.app, name="items")
app.add_typer(lands.app, name="lands")

if __name__ == "__main__":
    app()

And now we have everything in a single CLI program:

fast →💬 Check the main helppython main.py --help
Usage: main.py [OPTIONS] COMMAND [ARGS]...

Options:
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the installation.
  --help                Show this message and exit.

Commands:
  items
  lands
  users

💬 Try some users commandspython main.py users create Camila
Creating user: Camila

💬 Now try some items commandspython main.py items create Sword
Creating item: Sword

💬 And now some lands commands for reignspython main.py lands reigns conquer Gondor
Conquering reign: Gondor

💬 And for townspython main.py lands towns found Cartagena
Founding town: Cartagena

restart ↻

Review the files¶

Here are all the files if you want to review/copy them:

reigns.py:

Python 3.8+

import typer

app = typer.Typer()


@app.command()
def conquer(name: str):
    print(f"Conquering reign: {name}")


@app.command()
def destroy(name: str):
    print(f"Destroying reign: {name}")


if __name__ == "__main__":
    app()

towns.py:

Python 3.8+

import typer

app = typer.Typer()


@app.command()
def found(name: str):
    print(f"Founding town: {name}")


@app.command()
def burn(name: str):
    print(f"Burning town: {name}")


if __name__ == "__main__":
    app()

lands.py:

Python 3.8+

import typer

import reigns
import towns

app = typer.Typer()
app.add_typer(reigns.app, name="reigns")
app.add_typer(towns.app, name="towns")

if __name__ == "__main__":
    app()

users.py:

Python 3.8+

import typer

app = typer.Typer()


@app.command()
def create(user_name: str):
    print(f"Creating user: {user_name}")


@app.command()
def delete(user_name: str):
    print(f"Deleting user: {user_name}")


if __name__ == "__main__":
    app()

items.py:

Python 3.8+

import typer

app = typer.Typer()


@app.command()
def create(item: str):
    print(f"Creating item: {item}")


@app.command()
def delete(item: str):
    print(f"Deleting item: {item}")


@app.command()
def sell(item: str):
    print(f"Selling item: {item}")


if __name__ == "__main__":
    app()

main.py:

Python 3.8+

import typer

import items
import lands
import users

app = typer.Typer()
app.add_typer(users.app, name="users")
app.add_typer(items.app, name="items")
app.add_typer(lands.app, name="lands")

if __name__ == "__main__":
    app()

Tip

All these files have an if __name__ == "__main__" block just to demonstrate how each of them can also be an independent CLI app.

But for your final application, only main.py would need it.

Recap¶

That's it, you can just add Typer applications one inside another as much as you want and create complex CLI programs while writing simple code.

You can probably achieve a simpler CLI program design that's easier to use than the example here. But if your requirements are complex, Typer helps you build your CLI app easily.

Tip

Auto completion helps a lot, specially with complex programs.

Check the docs about adding auto completion to your CLI apps.