Build a TUI with Python's Argparse

GitHub tag (with filter) GitHub last commit (branch) GitHub Repo stars License



argparse-tui is a fork of Trogon, powered by the Textual TUI framework, that drops support for Click in favor of Argparse, and introduces several notable features.

Pictured: A quetzal, the closest relative of the trogon, who share common ancestry and have similar physical and behavioral characteristics.

Features: Argparse Support

argparse-tui works with Python's native Argparse CLI framework.

It enables two ways of using argparse to build a TUI app:

  1. Use argparse as a declarative DSL for building TUI apps.
>>> invoke_tui(parser)
  1. Add an argument to an existing argparse ArgumentParser.
>>> add_tui_argument(parser)
# OR,
>>> add_tui_command(parser)


From PyPi:

$ pip install argparse-tui

Example: invoke_tui()

Using invoke_tui(), argparse serves as a declarative, domain-specific language (DSL) for building TUI forms for any CLI application.

import argparse
from argparse_tui import invoke_tui

parser = argparse.ArgumentParser(prog="echo")
parser.add_argument("message", nargs="*")

$ python hello world

Example: add_tui_argument()

import argparse
from argparse_tui import add_tui_argument

parser = argparse.ArgumentParser()
add_tui_argument(parser, option_strings=["--tui"])

$ python --tui

Example: add_tui_command()

import argparse
from argparse_tui import add_tui_command

parser = argparse.ArgumentParser()
add_tui_command(parser, command="tui")

$ python tui

Features: Vim-friendly Nav

  • Move down / up using j / k.
  • / to focus search.
  • Enter to focus the selected command.
  • Escape to focus the command-tree.
  • Ctrl+y to copy the command.

Features: Redaction

Redact sensitive values in the TUI by including the term <secret> in the argument's help text.

>>> parser.add_argument("-p", "--password", help="<secret>")

Features: Pre-populating TUI

Command-line args are used to filter and pre-populate the TUI form.

$ awesome-app hello world --tui

Related Projects

  • Textualize/Trogon provides the foundations of the argparse-tui fork.

  • Fresh2dev/TUIview uses argparse-tui to offer TUI forms for a suite of popular command-line tools, including git, fdfind, and ripgrep.

  • Fresh2dev/Yapx is the next generation of argparse that leverages type-hints to simplify building Python tools. Yapx directly integrates argparse-tui.

  • Fresh2dev/Myke is a simple task runner, a la GNU Make, built on Yapx, so it provides a CLI and TUI for your suite of tasks.


See more examples in the reference docs.

Brought to you by...