Crate clap_tui 

clap-tui turns a clap CLI into an interactive terminal UI while preserving the original command-line interface.

You can keep clap as the source of truth, collect input in the TUI, and then hand the selected command value back to your normal application dispatch.

It reduces trial-and-error for complex CLIs by making commands, flags, and values easier to explore before execution. It also improves discoverability without changing the CLI behavior your existing scripts and docs already rely on.

This crate was heavily inspired by Trogon. clap-tui is a community crate and is not an official clap project.

Quick Start

Add a Tui subcommand and delegate to Tui::run.

The recommended integration model is to define a normal tui subcommand in your own CLI and run Tui from that dispatch branch:

use clap::Parser;
use clap_tui::Tui;

#[derive(Debug, Parser, PartialEq, Eq)]
#[command(name = "tool")]
enum Command {
    Tui,
    Hello {
        #[arg(long, default_value = "world")]
        name: String,
    },
}

fn dispatch(command: Command) {
    match command {
        Command::Tui => {}
        Command::Hello { name } => println!("Hello, {name}!"),
    }
}

fn main() -> Result<(), clap_tui::TuiError> {
    match Command::parse() {
        Command::Tui => {
            if let Some(command) = Tui::<Command>::new().hide_entrypoint("tui")?.run()? {
                dispatch(command);
            }
        }
        command => dispatch(command),
    }

    Ok(())
}

Choosing An Entry Point

Use Tui (recommended).

• Use Tui::<T>::run() when you want typed results from a derive-based parser.
• Use TuiApp when you are working directly with a hand-built clap::Command or need a lower-level integration surface.

Typed Outcomes

You can also use Tui with a single struct instead of an enum:

use clap::Parser;
use clap_tui::Tui;

#[derive(Debug, Parser, PartialEq, Eq)]
#[command(name = "tool")]
struct Cli {
    #[arg(long)]
    name: String,
}

fn main() -> Result<(), clap_tui::TuiError> {
    if let Some(cli) = Tui::<Cli>::new().run()? {
        println!("Hello, {}!", cli.name);
    }
    Ok(())
}

Tui::run returns:

• Some(T) when the user submits a valid command
• None when the user cancels before submission
• Err(TuiError) for runtime failures or clap-driven flows such as help and version handling

See TuiError for the detailed error taxonomy.

Feature Flags

• The default mouse feature enables mouse capture and mouse-driven controls.

Runtime Expectations

• The default CrosstermRuntime requires a terminal supporting raw mode and an alternate screen.

Customization

• TuiConfig controls theme, layout, key bindings, and initial command selection.
• Theme and ThemePreset help you start from a built-in look and adjust from there.
• Runtime plus the exported runtime event types support custom event loops or embedding into existing runtimes.

Examples

The crate ships with four public examples:

• simple for minimal Command::Tui setup
• showcase for a realistic, compact command tree
• subcommands for typed dispatch across command trees
• clap_features for the full TuiApp compatibility fixture

Structs

AppKeyEvent

Runtime customization surface for advanced integrations. Keyboard event used by custom Runtime implementations.

AppKeyModifiers

Runtime customization surface for advanced integrations. Key modifiers used by keyboard and mouse events.

AppMouseEvent

Runtime customization surface for advanced integrations. Mouse event used by custom Runtime implementations.

CrosstermRuntime

Runtime customization surface for advanced integrations. Default runtime backed by crossterm and arboard.

Keymap

Public configuration and theming types. Key bindings for main actions.

LayoutConfig

Public configuration and theming types. Layout configuration.

Theme

Public configuration and theming types. UI colors used across the TUI.

Tui

TUI application entry points. Direct typed TUI execution for a derive-based clap parser.

TuiApp

TUI application entry points. Build and run a TUI from a hand-built clap::Command.

TuiConfig

Public configuration and theming types. Top-level configuration for crate::Tui and crate::TuiApp.

Enums

AppEvent

Runtime customization surface for advanced integrations. Input event emitted by a custom Runtime implementation.

AppKeyCode

Runtime customization surface for advanced integrations. Key code used by AppKeyEvent.

AppMouseButton

Runtime customization surface for advanced integrations. Mouse button used by AppMouseEventKind.

AppMouseEventKind

Runtime customization surface for advanced integrations. Mouse event kind used by AppMouseEvent.

ThemePreset

Public configuration and theming types. Built-in theme presets.

TuiError

Error type returned by public clap-tui operations. Errors returned by clap-tui.

Traits

Runtime

Runtime customization surface for advanced integrations. Runtime services required by TuiApp.