Install & Compatibility
Where this runs
tested against v0.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.846s · 38.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.768s · 39MB
38MB installed
● package 38MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tui
✓ from trogon import tui
✗ from trogon.cli import tui
The `tui` decorator is directly available from the top-level `trogon` package. Older examples or common misconceptions might lead to importing from a non-existent `cli` submodule.
init_tui
✓ from trogon.typer import init_tui
Used for integrating Trogon with Typer applications, introduced in v0.6.0. This import is specific to Typer CLIs.
This quickstart demonstrates how to add a Trogon TUI to a basic Click CLI. By adding the `@tui()` decorator to your Click group or command, Trogon automatically generates a TUI accessible via a new `tui` subcommand. Users can then run `python your_cli_file.py tui` to launch the interactive interface.
import click
from trogon import tui
@tui()
@click.group()
def cli():
"""A simple CLI with Trogon."""
pass
@cli.command()
@click.option("--name", default="World", help="The name to greet.")
def hello(name):
"""Greets a name."""
click.echo(f"Hello {name}!")
@cli.command()
@click.argument("num1", type=int)
@click.argument("num2", type=int)
def add(num1, num2):
"""Adds two numbers."""
click.echo(f"The sum is: {num1 + num2}")
if __name__ == "__main__":
# To run the TUI: python your_cli_file.py tui
# To run the CLI: python your_cli_file.py hello --name Alice
cli()
trogon --version
Debug
Known issues
breakingOlder versions of Trogon (pre-0.6.0) may experience layout issues or incompatibilities with Textual versions 0.54 and newer.fixUpgrade Trogon to version 0.6.0 or later to ensure compatibility with Textual 0.54+. Ensure your Textual dependency is also up-to-date.
affects: <0.6.0
gotchaUsing interactive prompts (e.g., `click.prompt()` or `rich.Prompt.ask()`) within a Click command wrapped by Trogon can lead to visual glitches and input issues, where the system command prompt interweaves with the TUI.fixAvoid using interactive prompts directly within Trogon-wrapped Click commands. Instead, leverage Trogon's generated input fields for arguments and options, or provide all necessary arguments directly when launching the command from within the TUI.
affects: All versions
gotchaTrogon has known issues with handling `click.option` of `type=bool` and can pass boolean values as strings instead of native Python booleans to the underlying Click command.fixAs of now, this is an open bug. A potential workaround might involve explicitly converting the string representation of boolean options (e.g., 'True', 'False') to actual `bool` types within your Click command function, or waiting for an official fix in future Trogon releases.
affects: All versions up to 0.6.0 (as of last check)
deprecatedThere is an open issue regarding `click.BaseCommand` deprecation warnings when using Trogon.fixMonitor Trogon's GitHub issues for updates and official fixes. Ensure your Click library is also up to date, as newer Click versions might handle deprecations differently.
affects: All versions (depending on Click version)
Errors
Common errors & fixes
TypeError: 'NoneType' object is not subscriptable (often traced to detect_run_string.py on Windows)
Trogon's internal mechanism for detecting the run string, specifically `Py_GetArgcArgv` from `ctypes`, can fail on certain Windows environments, particularly with Python 3.8.10.
fixUpgrade Python to a newer 3.x version (e.g., 3.9+) or use a Linux/WSL environment. This issue is less prevalent in later Python versions or non-Windows OS.
Trogon with standalone_mode of click is not working (e.g., when calling cli(standalone_mode=False))
Trogon expects Click applications to run in their default `standalone_mode=True`. Explicitly setting `standalone_mode=False` when invoking the Click command can interfere with Trogon's introspection and execution.
fixDo not explicitly set `standalone_mode=False` when Trogon is wrapping your Click application. Allow Click to run in its default `standalone_mode` when `trogon` is the entry point.
ImportError: cannot import name 'tui' from 'trogon.cli'
Attempting to import the `tui` decorator from an incorrect submodule path, possibly based on outdated examples or assumptions.
fixThe correct import path for the `tui` decorator is directly from the `trogon` package: `from trogon import tui`.
Upgrade
Version history
0.6.0latest on PyPI · released Oct 2, 2024
Audit
Dependencies
clickrequiredCore dependency for CLI application introspection and TUI generation.
textualrequiredPowers the Textual User Interface (TUI) rendering.
typeroptionalOptional dependency for building TUIs for Typer CLIs.