TuiSage

A terminal UI for running mise tasks or other commands supporting --usage specs.

Features

• Execute commands — Runs in an embedded terminal so you can see the output, then return to the UI.
• Fuzzy filter — Press / to activate search mode, or start typing in a "select" box. Uses nucleo for fzf-style matching.
• Dynamic completions — Supports running a custom command to generate completion values. See the spec for the "complete" statement.
• Mouse support — Click to select, or mouse wheel to scroll up and down.
• Themes — Press "T" or click the name to open the theme selector. Uses ratatui-themes.

Installation

Binaries

Binary downloads are available from the releases.

They can also be fetched and installed with mise:

mise u github:mgood/tuisage

Building from source

Automatically build from crates.io:

cargo install tuisage

From a local clone:

cargo install --path .

Or build inside the clone:

cargo build --release
./target/release/tuisage

Usage

Mise Tasks

This is designed to work well with mise. Running mise tasks ls --usage prints the full usage spec the tasks, though you need to specify --cmd "mise run" as the command prefix to run the tasks:

tuisage --cmd "mise run" mise tasks ls --usage

For convenience, you can add it to your mise config file to run as mise tui:

[tasks.tui]
description = "TUI to run mise tasks"
run = 'tuisage --cmd "mise run" mise tasks ls --usage'

Native --usage support

For tools supporting --usage you can run them like:

tuisage mytool --usage

From a file

You can also provide your own --usage spec from a file:

tuisage --spec-file path/to/cli.usage.kdl

Other combinations

You can combine these as well:

tuisage --cmd "docker compose" --spec-file docker-compose.usage.kdl

CLI Reference

Provide either trailing arguments (spec command) or --spec-file (but not both).

Keyboard Shortcuts

Mouse

Left click to activate most elements. Mouse wheel scrolls selection up and down.

Compatibility

This has been mostly tested in ghostty, though I have also tried it with the Mac built-in Terminal.app, and the Zed and VSCode embedded terminals. Some seem to trouble aligning the box-drawing characters, but are otherwise functional.

Security Considerations

Only run this with trusted tools. Since it automatically runs custom commands provided by the usage spec, it could run an unintended command.

Testing

# Run all tests (180 tests: unit + rendering + snapshots)
cargo test

# Review snapshot changes interactively
cargo insta review

# Run with acceptance of new snapshots
cargo insta test --accept

Roadmap

Some features I would like to implement:

• History / favorites – revisit commands from the current session, save them for fast use in the future.
• Saving preferences – persist theme selection, or maybe other options.
• Filename and other completions – Recognize inputs for file paths to provide a file navigator, present a calendar picker for date fields, etc.

Documentation

This README presents the main documentation intended for users. Other documents are primarily designed to help building and maintaining the app with AI agents, but may provide insight into the development.

Dependencies

License

MIT