Lite SuiteLite Suite
← Back to Docs

LiteTUI

TUI + CLI generation framework with pre-built Textual components and themes

Overview

LiteTUI is a code-generation framework that scaffolds production-ready Textual TUI and Click CLI applications from a single command. Describe your software, and LiteTUI produces a complete Python package with a rich terminal interface, a typed CLI, shared business logic, themes, and AI agent integration.

Every generated project follows the shared-core architecture: business logic lives once in core/, and both the TUI and CLI import from it. Change the core, both interfaces stay in sync automatically.

Features

  • One command generates a full TUI + CLI project, pip-installable out of the box
  • 6 pre-built Textual components ready to drop into any TUI
  • 4 built-in themes (dark, light, high_contrast, brand with custom accent color)
  • Shared-core pattern: TUI and CLI never talk to each other, both import from core/
  • SoftwareBackend wraps external binaries with version detection and subprocess management
  • Session management with undo/redo history and action recording
  • ProjectManager for file CRUD and recent projects
  • SKILL.md and TUI-HARNESS.md generated for AI agent integration

Installation

LiteTUI is installed automatically by the Lite Suite installer. To install manually:

cd C:/Apps/LiteTUI
uv sync

Usage

Generate a Project

litetui generate --name myapp --output ./my-tui --description "A tool that does X"

This creates a complete project with:

my-tui/tui-anything-myapp/
  tui_anything/myapp/
    myapp_tui.py          # Textual TUI entry point
    myapp_cli.py          # Click CLI entry point
    core/
      backend.py          # SoftwareBackend (wraps external binaries)
      session.py          # Session with undo/redo
    themes/
      app.tcss            # Textual CSS theme
    skills/
      SKILL.md            # Claude Code skill definition

Run the Generated App

cd my-tui
pip install -e .
myapp-tui          # Launch the Textual TUI
myapp-cli --help   # Use the Click CLI

Customize the Theme

litetui generate --name myapp --accent "#ff6b35" --output ./my-tui

The --accent flag generates a brand theme with your chosen color applied to borders, highlights, and interactive elements.

Pre-Built Components

Six Textual widgets are available for any TUI:

| Component | Description | |-----------|-------------| | AppShell | Root layout with header, sidebar, tabs, and footer | | FeatureSidebar | Collapsible navigation with keyboard shortcuts | | StatusPanel | Live status indicators with color-coded progress bars | | StreamingLog | Auto-scrolling log viewer with level filtering and search | | DataExplorer | Sortable, filterable data table with detail pane | | CommandPalette | Fuzzy-search command launcher (Ctrl+P style) |

from litetui.components import AppShell, DataExplorer, StreamingLog

Themes

Four built-in Textual CSS themes:

| Theme | Description | |-------|-------------| | dark | Deep background, high contrast (default) | | light | Light background for daylight work | | high_contrast | Maximum contrast for accessibility | | brand | Custom accent color, generated at scaffolding time |

from litetui.themes import load_theme, AVAILABLE_THEMES
css = load_theme("dark")

Core Modules

Every generated project gets three core utilities:

SoftwareBackend

Wraps external software binaries (ffmpeg, ImageMagick, etc.) with PATH discovery, version detection, and subprocess execution.

Session

Application session state with linear undo/redo history, action recording, metadata storage, and save/load to disk.

ProjectManager

Project file management with create/load/save, recent projects registry, and auto-pruning of stale entries.

AI Agent Integration

Every generated project includes:

  • SKILL.md -- teaches AI agents how to use the CLI (commands, options, examples)
  • TUI-HARNESS.md -- structured documentation for AI agents to extend the project safely

LiteTUI itself also ships a Claude Code skill for generating projects from within a Claude session.

Requirements

  • Python 3.10 or later
  • Textual 8.1.1+ (TUI framework)
  • Click 8.3.1+ (CLI framework)
  • Jinja2 3.1.6+ (code generation templates)
  • Pillow 12.1.1+ (image handling)

Troubleshooting

Generated project won't install. Make sure you run pip install -e . from the directory containing setup.py, not from the parent.

Theme doesn't apply. Verify the .tcss file path in your Textual App's CSS_PATH. The default path is themes/app.tcss relative to the package root.

Components not found. LiteTUI's component library is a build-time dependency. If you moved the generated project to a machine without LiteTUI installed, copy the components you need into your project directly.