Terminal-light is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install terminal-light

It will make the terminal-light command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall terminal-light uninstalls.

Adding `terminal_light` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add terminal-light

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

terminal-light = "1.8.0"

The terminal_light library will be automatically available globally. Read the terminal_light library documentation.

Back to the crate overview.

Readme

terminal-light

This crate answers the question "Is the terminal dark or light?".

It provides

the background color, either as RGB or ANSI
the background color's luma, which varies from 0 (black) to 1 (white)

A use case in a TUI is to determine what set of colors would be most suitable depending on the terminal's background:

let should_use_light_skin = terminal_light::luma()
    .map_or(false, |luma| luma > 0.6);

If you have very specialized skins, you may choose a more precise switch:

match terminal_light::luma() {
    Ok(luma) if luma > 0.85 => {
        // Use a "light mode" skin.
    }
    Ok(luma) if luma < 0.2 => {
        // Use a "dark mode" skin.
    }
    _ => {
        // Either we couldn't determine the mode or it's kind of medium.
        // We should use an itermediate skin, or one defining the background.
    }
}

See the included example:

dark

light

Strategies

Here are the various strategies automatically used by terminal-light to answer the big question:

`$COLORFGBG` strategy

This environment variable is set by some terminals, like konsole or the rxvt family. It can also be set by users. Its value is like 15;0 where the second number is the ANSI code for the background color.

Upsides:

querying an env variable is a fast operation

Downsides:

this env variable isn't always immediately updated when you change the color of the terminal
the value isn't precise: 0 is "dark" and 15 is "light" but the real RGB color is uncertain as the low ANSI codes are often modified by the user

"Dynamic colors" OSC escape sequence strategy

Modern terminals implement this xterm extension: a query making it possible to know the background color as RGB.

Terminal-light sends the query on stdout, waits for the answer on stdin with a timeout of 20ms, then parses this answer.

Upsides:

this works well on all tested unix terminals, including on MacOs
the value is precise (RGB)
the value is up to date when it's available

Downsides:

waiting for stdin with a timeout isn't implemented on Windows in this crate (help welcome)
this isn't instant, a delay of 10 ms to get the answer isn't unusual
if a not compatible terminal doesn't answer at all, we're waiting for 20ms
it may fail on some terminal multiplexers

Global strategy used by Terminal-light

if we're on a unix-like platform, we try the escape sequence strategy
if it failed or we're not on unix, we try the $COLORFGBG strategy
without a solution, we return a TlError::Unsupported error

Installing the command-line executable

Adding terminal_light library as a dependency

Adding `terminal_light` library as a dependency