skim

Skim (sk) is a terminal fuzzy-finder that operates using four concurrent activities to process data from input to output:

1. Reader: Pulls raw text from stdin or a shell command, converts it into Arc<dyn SkimItem> batches, and deposits them into the ItemPool.
2. ItemPool: A shared storage (Arc<...>) that holds batched items.
3. Matcher: A parallel worker that picks items from the ItemPool, evaluates them against the current query string using a configured engine, and produces ranked MatchedItem results.
4. TUI (Terminal User Interface): A crossterm-based event loop that renders composable widgets (Input, ItemList, Preview, Header) and converts user keystrokes into Action values to drive the application state machine.

The final result is emitted as SkimOutput.

stdin / command
      │
      ▼
 ┌──────────┐   batched items   ┌──────────────┐
 │  Reader  │──────────────────▶│  ItemPool    │
 └──────────┘                   │  (Arc<…>)    │
                                └──────┬───────┘
                                       │ take()
                                       ▼
                                ┌──────────────┐
                                │   Matcher    │◀── query string
                                │  (parallel)  │
                                └──────┬───────┘
                                       │ ProcessedItems
                                       ▼
                   ┌──────────────────────────────────┐
                   │              TUI                  │
                   │  ┌────────┐  ┌────────┐           │
                   │  │ Input  │  │Preview │           │
                   │  ├────────┤  ├────────┤           │
                   │  │ItemList│  │ Header │           │
                   │  └────────┘  └────────┘           │
                   └──────────────────────────────────┘
                                       │
                                       ▼
                                  SkimOutput

To install skim on Debian or Ubuntu systems using the official APT repository:

1. Import the signing key using wget:

   sudo mkdir -p /etc/apt/keyrings
   sudo wget -O /etc/apt/keyrings/skim.asc https://skim-rs.github.io/skim/apt/skim-archive-keyring.asc

   Or using curl:

   sudo mkdir -p /etc/apt/keyrings
   curl -fsSL https://skim-rs.github.io/skim/apt/skim-archive-keyring.asc | sudo tee /etc/apt/keyrings/skim.asc > /dev/null

2. Add the repository:

   echo 'deb [signed-by=/etc/apt/keyrings/skim.asc] https://skim-rs.github.io/skim/apt ./' | sudo tee /etc/apt/sources.list.d/skim.list
   sudo apt-get update

3. Install:

   sudo apt-get install skim

Alternatively, you can download .deb packages from the releases page and install them using sudo dpkg -i skim_*_amd64.deb.

Skim supports executing commands (like editors or interactive TUIs) in the foreground. When a command is triggered via execute, Skim performs the following to ensure a smooth transition:

1. Stops the TUI reader: It cancels the background event-pump task and blocks until the EventStream is dropped. This prevents Skim from competing with the child process for keystrokes.
2. Handles Stdin: The child process is spawned with its own stdin opened from the controlling terminal (/dev/tty or CONIN$ on Windows). This allows interactive commands to work even when Skim's own stdin is a pipe (e.g., find | sk).
3. Restores Terminal: Skim leaves the alternate screen/raw mode, runs the command, waits for it to finish, restores terminal modes, and then restarts the TUI reader.

Note: execute-silent(cmd) spawns the command directly without needing a terminal, sending its stdout/stderr to /dev/null.

You can integrate skim directly into your Rust projects. Add skim to your Cargo.toml. Note that the cli feature is required for the standalone CLI tool but should not be needed when using it as a library.

To use it, you can use SkimOptionsBuilder to configure the interface and Skim::run_with to execute the fuzzy finder with a stream of items.

[dependencies]
skim = { version = "<version>", default-features = false, features = [..] }

extern crate skim;
use skim::prelude::*;
use std::io::Cursor;

pub fn main() {
    let options = SkimOptionsBuilder::default()
        .height("50%")
        .multi(true)
        .build()
        .unwrap();

    let input = "aaaaa\nbbbb\nccc".to_string();

    // `SkimItemReader` is a helper to turn any `BufRead` into a stream of `SkimItem`
    // `SkimItem` was implemented for `AsRef<str>` by default
    let item_reader = SkimItemReader::default();
    let items = item_reader.of_bufread(Cursor::new(input));

    // `run_with` would read and show items from the stream
    let selected_items = Skim::run_with(&options, Some(items))
        .map(|out| out.selected_items)
        .unwrap_or_else(|| Vec::new());

    for item in selected_items.iter() {
        println!("{}", item.output());
    }
}