Introduction

Asinus is a TUI application for exploring, previewing, and comparing terminal color themes.

Key Features

• Preview themes with built-in samples or your own text, and compare them side by side.
• Search by name, appearance, background color, brightness, and text contrast.
• Inspect color values and credits, mark favorites, and save search conditions.

Themes are bundled from VHS, so browsing works offline.

Built with Rust and Ratatui. Asinus is available on GitHub under the MIT License.

The bundled theme data retains VHS's MIT license.

Getting Started

Use a True Color terminal with at least 60 columns and 22 rows. See Compatibility for platform and clipboard requirements.

Installation

Cargo

Install from crates.io with Rust 1.89 or later:

cargo install --locked asinus

Homebrew (macOS)

brew install lusingander/tap/asinus

The formula is maintained in lusingander/homebrew-tap.

Release Binaries

Download an archive from GitHub Releases, extract it, and place the asinus executable on your PATH.

First Steps

Start Asinus:

asinus

1. Use ↑ / ↓ to select a theme.
2. Press p to pin it, then select another theme and press c to compare them.
3. Use [ / ] to switch preview samples, or / to search.
4. Press F1 for help and Ctrl-C to quit.

Continue with Explore & Compare or try your own preview sample. See Keybindings for all controls.

Run asinus --help for command line help and asinus --version to check the installed version.

Explore & Compare

Explore shows the selected theme, called Current. Pin a theme to keep it as a reference while browsing other candidates, then use Compare to view Pin and Current side by side or stacked vertically.

The pin stays available when you change search conditions. You can hide the theme list to give previews more room.

Preview Samples

Compare shows the same portion of the selected sample for both themes. Content extending beyond the preview is clipped.

Previews show theme colors within Asinus. Use Theme Details to inspect colors and find source links.

Built-in Samples

These samples show how the theme's colors work together. Applications may use different color assignments.

The preview selector offers Auto, Small, Medium, and Large content sizes. Auto chooses a size for the available area. Fixed sizes keep the same content when resizing.

Custom Samples

Use -p, --preview <FILE> to load a file as the Custom sample for the current run. Use - as the file argument to read from stdin.

asinus --preview sample.txt
git diff --color=always | asinus -p -

Input must be nonempty UTF-8 text, up to 1 MiB. When reading from stdin, Asinus waits for EOF before opening the TUI. The TUI requires an interactive terminal.

The preview supports ANSI colors and text attributes such as bold and underline. Color indices 0–15 use the selected theme's palette. Indices 16–255 and explicit RGB colors retain their specified values.

Operations

In Explore / Compare:

In the preview selector:

See Keybindings for all controls.

Search & Filters

Search accepts theme names and filter expressions. Filters provides fields for the same conditions. All terms and conditions are combined with AND.

Name Search

Name terms match substrings. Lowercase terms ignore case; a term containing an uppercase letter is case-sensitive. Multiple terms can appear in any order in the theme name.

Use double quotes to match a phrase or a literal term containing :. Inside quotes, use \" for a quote and \\ for a backslash.

catpp mocha
"Solarized Dark"
catpp type:dark bg:blue contrast:medium

Results stay in case-sensitive theme-name order, with no relevance ranking.

Conditions

Filter keys and values are lowercase. Each key can appear once in a query. Omitting a key removes that restriction, except that ignored themes are hidden by default.

The remaining fields classify the background and foreground colors. Appearance uses theme metadata and is independent of background brightness.

Background Brightness

Background brightness uses OKLCH lightness, scaled to L = 0–100.

Background Color

Background color uses OKLCH chroma C and hue h in degrees. Gray includes backgrounds with a slight tint. The other groups require C > 0.015.

Text Contrast

Text contrast uses the WCAG contrast ratio R between the normal foreground and background. These groups are for exploration, not accessibility ratings or an overall readability score.

Background metrics are calculated from sRGB using Oklab. Contrast uses sRGB relative luminance. Classification uses unrounded values; Theme info shows the metrics for each theme.

Operations

From Explore / Compare:

While editing:

See Keybindings for text editing and cancellation, and Favorites & Saved Filters to reuse conditions.

Theme Details

Use Theme info to inspect a theme's background and source, Color details to examine individual colors, and Copy to take its name or colors to another application.

Theme Info

Overview shows the theme name, registered appearance, foreground and background colors, background metrics, and text contrast. In Compare it shows Pin and Current together. See Search & Filters for the metrics and classification ranges.

Credits lists the theme's supplied source links. A credit may refer to a person or another source. Select a link to open it in your default browser.

Color Details

Color details lists foreground, background, the 16 ANSI colors, and optional cursor and selection colors, with color swatches and HEX values.

In Compare, Same and Diff indicate whether both RGB values match; Missing means at least one theme has no value for that role. Optional colors are left unspecified when absent from the theme.

Foreground and ANSI roles include a text sample on the theme's background and a contrast ratio. Background, cursor, and selection roles show their registered values without a contrast ratio. Actual cursor and selection rendering depends on your terminal.

Copy

Choose Current or Pin and one of two formats:

JSON contains foreground, background, black through white, brightBlack through brightWhite, and optional cursor and selection values. Unspecified colors are omitted. This is a color export, not a terminal-specific configuration file.

Copy uses the system clipboard. See Compatibility for required commands.

Theme Sources

The bundled catalog comes from VHS. Its MIT license is included with Asinus, and the supplied credits are available in Theme info.

Operations

In Explore / Compare and detail panels:

In Copy:

See Keybindings for all controls.

Favorites & Saved Filters

Favorites keep promising themes easy to find. Ignored themes are hidden from the default results. A theme can be either favorite or ignored; setting one replaces the other. Pin is a separate comparison reference.

Use the Favorite and Ignored fields in Filters, or search with favorite:true, ignore:all, or ignore:true to revisit marked themes.

Saved Filters

Save a set of conditions under a name to reuse it later. Saved filters store the query, so their results reflect your current favorites and ignored themes.

The built-in Initial entry restores the default conditions. Your own entries can be renamed or deleted. To replace a saved query, delete its entry and save the new conditions.

Favorites, ignored themes, and saved filters persist between runs. See Data Files for their storage locations.

Operations

In Explore / Compare, with theme selection focused:

In Explore / Compare or a detail panel:

In Saved filters:

See Keybindings for all controls.

Keybindings

Keys are case-sensitive: S means uppercase S. Press F1 for help with the actions available in the current screen.

Common

Navigation

In theme lists, detail panels, Saved filters, and Help:

Explore / Compare

These controls also work from detail panels. Pin, Favorite, and Ignored require theme selection focus.

Detail Panels

Navigation acts on the focused panel's overview, credits, or color roles.

Search / Filters

Text Editing

These keys apply to Search, the Name field in Filters, and Save / Rename dialogs. Character keys such as j, k, and q enter text in these fields.

Modified keys depend on terminal settings. See Compatibility.

Preview Selector

Saved Filters

Use the common navigation keys to select an entry.

In Save / Rename / Delete dialogs, Enter confirms the operation.

Copy

Configuration

Use config.toml to customize the Asinus UI.

Configuration File Location

Asinus selects the configuration file in this order.

1. The path set in ASINUS_CONFIG_FILE.
2. $XDG_CONFIG_HOME/asinus/config.toml if XDG_CONFIG_HOME is nonempty.
3. $HOME/.config/asinus/config.toml.

Asinus reads only the selected file. Relative paths are resolved from the current working directory. If the selected default file is missing, Asinus uses its built-in settings.

An empty ASINUS_CONFIG_FILE, a missing file specified by that variable, or an unreadable or invalid configuration file prevents startup. Unknown settings are reported as errors.

Create a Configuration

Save the following example as config.toml in your current directory. It sets the colors of selected items and turns off reverse video.

[ui.style.selection]
fg = "#1e1e2e"
bg = "#89b4fa"
modifiers = []

Run Asinus with this file.

ASINUS_CONFIG_FILE=./config.toml asinus

All settings are optional. Add only the values you want to change.

UI Style

[ui.style] controls the application UI. Preview samples and color swatches use the colors of the theme being inspected.

Each setting below is a table under [ui.style]. Use fg for the foreground color and bg for the background color. When omitted, bg inherits from base, and fg uses the listed color or inherits from base.

Color values are strings. Use "default" for the terminal's default color or "#RRGGBB" for an RGB color. ANSI color names are black, red, green, yellow, blue, magenta, cyan, and white, plus their bright_ forms such as bright_cyan.

Styles other than base also accept a modifiers array with "bold", "dim", "underline", and "reverse". An explicit array replaces the default attributes, and [] clears them. Omit the array to keep the default attributes.

For editor validation, see the configuration schema.

Data Files

Asinus saves application data in two TOML files. For the settings file you edit, see Configuration.

Locations

The default directory is $XDG_DATA_HOME/asinus when XDG_DATA_HOME is an absolute path. Otherwise, Asinus uses $HOME/.local/share/asinus. This applies on both macOS and Linux.

Set either path override to choose a different file. Relative overrides are resolved from the current working directory:

ASINUS_STATE_PATH=./marks.toml \
ASINUS_WORKSPACE_PATH=./workspace.toml \
asinus

Read-Only Mode

If either file is invalid or cannot be read or locked at startup, Asinus reports the reason and opens in read-only mode. You can browse and change conditions for that session, but favorites, ignored themes, saved filters, and session settings cannot be saved.

Check the reported file and directory permissions, or close another Asinus instance using the same files, then restart.

Compatibility

Asinus targets macOS and Linux. Windows is not currently supported.

Terminal

Use a terminal with True Color (24-bit RGB) support and at least 60 columns × 22 rows. Larger windows give previews more room. Some panels fill the screen at smaller sizes, and preview content may be clipped.

The surrounding UI uses your terminal's colors by default. Preview samples use the selected theme's RGB colors. Text attributes such as bold and dim depend on terminal settings. To customize the UI, see Configuration.

Clipboard

Copy requires the following command on PATH:

Linux clipboard access uses WAYLAND_DISPLAY and DISPLAY to select the available commands. In a remote session, these commands run on the machine hosting Asinus.

Keyboard Input

Your terminal must forward F1 and modified key combinations to Asinus. If a key opens a terminal shortcut instead, adjust the terminal's key settings. See Keybindings for available alternatives.