TUIview [tv]

A TUI for every CLI

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

TUIview [tv]

Command-line (CLI) apps offer convenient capability right in your terminal. No bloated browser, no nonsense. What could be better?

Well, when I'm learning a new tool -- or revisiting a familiar friend (looking at you, rsync) -- I'm combing through pages of CLI help text... 😩

TUIview provides a pleasant alternative by displaying an interactive Textual UI (TUI) of your favorite CLI tools, including git, rsync, fdfind, and ripgrep.


Install from PyPi using pipx:

$ pipx install tuiview

Or using plain ol' pip:

$ pip install tuiview


Prefix your command with tv to invoke the TUI for the given CLI app:

tv git

You can even specify subcommands and arguments, which will filter and pre-populate the TUI form.

tv git commit -m 'Hello' -m 'World'

How does it work?

  • TUIview contains a collection of pre-defined, curated TUI interfaces for each supported CLI application.

  • These curated TUI interfaces -- termed "TV Programs" -- are Python modules that use Python's Argparse to model the CLI interface of another app.

  • argparse-tui is the Python package that enables this capability. Using argparse-tui, Python's Argparse can serve as a declarative DSL for generating a TUI form.

  • So, TUIview is really just a simple command-line tool that reads the command line arguments that follow it (tv ...) and points argparse-tui to the appropriate TUI definition.

Which CLI apps are supported?

Call TUIview (tv) without arguments to view all supported apps:

$ tv

Helpful Parameters:
  --help, -h  Show this help message.



TV Programs

Within the context of TUIview, a TV Program is a Python file that defines an Argparse ArgumentParser that models the CLI interface of another tool.

For example, to define a TV Program for the echo command:

import argparse
parser = argparse.ArgumentParser(prog="echo", description="Print text.")
parser.add_argument("message", nargs="+")
parser.add_argument("-n", action="store_true", help="no trailing newline")

Execute the program file with tv:

$ tv -n Hello World

Import & Edit a TV Program

TUIview can import a program file so that it can be invoked globally, just like a native program.

$ tv --import

The file now exists at ~/.tuiview/ and can be invoked from anywhere, just like a native TV program:

$ tv echo Hello World

To edit a program file, pass the command name (not the file name) to tv:

$ tv --edit echo

You also edit native TV programs. When you do this, the program file is copied to the TV program directory and opened for editing.


TUIview is simply a program for running and managing these TV Program files; Python Argparse implementations of various CLI tools.

The real work -- the real value -- is in the quantity and quality of the program files. If you want to help make TUIview better by contributing and correcting TV Programs, please send PRs!

Pro tip: Given a the help text output from your CLI app of choice, ChatGPT is decent at providing an Argparse implementation of it.

Related Projects


Brought to you by...

![bg contain right:33%](