repository·main·Indexed 25 days ago
https://github.com/textualize/trogonA tool to automatically generate Textual-based terminal user interfaces (TUIs) for Click and Typer CLI applications. Trogon inspects the CLI schema to build an interactive UI that helps users discover and run commands. It provides a @tui decorator for Click and an init_tui function for Typer, along with utilities for introspecting CLI structures into CommandSchema, OptionSchema, and ArgumentSchema objects.
init_tui from trogon.typer and pass your Typer instance into the init_tui function.tui from trogon and apply the @tui() decorator to your Click group or command.You can install Trogon using PyPI.
pip install trogonBy default, Trogon adds a command named tui with the help text Open Textual TUI.. You can override these using the command and help parameters in the @tui decorator.
@tui(command="ui", help="Open terminal UI")
@click.group()
def cli():
...You can automatically generate a Textual-based TUI for your click application by using the @tui decorator. This adds a new command to your CLI that, when run, launches the Trogon interactive interface.
If your application is a click.Group, the decorator adds the TUI command to that group. If your application is a single click.Command, the decorator wraps it in a new group to host the TUI command.
introspect_click_app to convert a click.BaseCommand (such as a Click Group or Command) into a structured dictionary of CommandSchema objects. This process recursively captures all commands, subcommands, options, arguments, docstrings, and function references, making the CLI structure programmatically accessible.trogon package provides the Trogon class for creating interactive terminal user interfaces (TUIs) for CLI applications, and a tui function to wrap these interfaces for use with frameworks like Typer or Click.You can convert a UserCommandData instance back into a CLI invocation using the following methods:
to_cli_args(include_root_command: bool = False) -> list[str]: Returns a list of strings suitable for passing to subprocess.run. If include_root_command is False, the first element (the command name) is omitted.to_cli_string(include_root_command: bool = False) -> Text: Returns a rich.text.Text object representing the command as it would be typed in a terminal, with arguments properly quoted using shlex.If you need more control than the decorator provides, you can instantiate the Trogon class directly. This class manages the lifecycle of the TUI and the execution of the command once the user exits the interface.
cli: The click.Group or click.Command instance to introspect.app_name (optional): The name of the application to display in the TUI. If not provided, it attempts to detect it from the run string.command_name (optional): The name of the command that launches the TUI (defaults to "tui").click_context (optional): The current click.Context.run(*args, **kwargs): Starts the Textual application. If the user selects a command and exits, Trogon will execute that command in the system shell using os.execvp.To add a Textual-based TUI to an existing typer.Typer application, use the init_tui function. This function injects a new command named tui into your Typer application. When the tui command is executed via the CLI, it launches the Trogon interactive interface.
Note: This requires the trogon[typer] extra to be installed.
While using the Trogon TUI, you can use the following keyboard shortcuts to navigate and interact with the interface:
| Key | Action | Description |
|---|---|---|
ctrl+r | close_and_run | Close the TUI and execute the currently selected command in the shell |
ctrl+t | app.focus_command_tree | Focus the command tree sidebar |
ctrl+o | app.show_command_info | Show detailed information about the selected command |
ctrl+s | app.focus('search') | Focus the search input |
f1 | about | Show the About dialog |