Matchmaker [](https://crates.io/crates/matchmaker-cli) [](https://github.com/squirreljetpack/matchmaker/blob/main/matchmaker-cli/LICENSE)

February 16, 2026 · View on GitHub

Matchmaker is fast, configurable and intuitive fuzzy searcher. It is useful for browsing and building workflows around any list or kind of data you can wrangle into a tabular format.

It takes inspiration from fzf in features and design, but reimagines the user experience. Built from the ground up in Rust, it brings a fully robust, modern and elegant search experience to the console.

screen1

Features

Matching with nucleo.
Fully configurable via a type-checked toml file. ¹
A minimal yet powerful syntax for overriding the configuration on the command line.
Interactive preview supports color, scrolling, wrapping, multiple layouts, and even maximizing.
Most of the familiar actions from fzf, as well as several new ones².
Mouse (location aware) scrolling! Drag to resize! Horizontal scrolling!
Grapheme-width correct input wrapping!
Nice text wrapping and width sizing.
Split input lines into multiple columns, that you can individually filter on (%col query³), hide, and highlight.⁴
Split input lines by regex capture groups.
Define Execute/Preview/Print/Accept actions with templates which safely inject the current item(s) (yes, columns are supported here too).
All the dynamic UI support you could hope for: preview offsets, styled status lines, responsive header tables, wrapped footers, active and inactive column colors, stacked columns, programmable status and header bars, multiple preview layouts⁵... even overlays! (in the library).
Bind keys to multiple actions, bind actions to mouse triggers, bind actions to event triggers, bind keys to rebind keys, bind keys to modify the configuration, bind keys to run a shell script and use its output to execute actions and bind more keys, bind keys to set the header, footer, status, input, bind semantic triggers to actions, bind keys to semantic triggers, bind keys to -- wait nope thats about it.
Comprehensive logging in case you need to debug applications.
oh yeah, and mm --last-key gives you the last key that was pressed in a previous run of the program.⁶
a panoply of amazing presets which manifest as dashing TUIs to boost your productivity.
Available as a rust library to use in your own code!

On the way:

Matching with frizbee, a faster, typo-resistant matching algorithm.

Installation

curl -fsSL https://raw.githubusercontent.com/Squirreljetpack/matchmaker/main/install.sh | sh

powershell -ExecutionPolicy Bypass -c "irm https://github.com/Squirreljetpack/matchmaker/releases/latest/download/matchmaker-cli-installer.ps1 | iex"

Homebrew

brew install Squirreljetpack/tap/matchmaker

AUR

yay -S matchmaker-bin

npm

npm install -g @squirreljetpack/matchmaker

Cargo

# requires cargo and does not come with certain features patched into dependencies, better to build from source with cargo build --release -F experimental.
cargo install matchmaker-cli

Pass it some items:

find . | mm

Tip

The default input and preview commands detect fd, bat and eza (otherwise falling back to ls and cat). Install them for a better experience!

Configuration

To start configuration, write the default configuration to a file:

matchmaker --dump-config

The default locations are in order:

~/.config/matchmaker/config.toml (If the folder exists already).
{PLATFORM_SPECIFIC_CONFIG_DIRECTORY}/matchmaker (Generally the same as above when on linux)

Matchmaker options are hierarchical, although most categories live at the top level:

[preview]
show = true
wrap = true
header_lines = 3 # sticky the top 3 lines

# Full specification of (the default values of) a single layout. Multiple layouts can be specified.
# Previews can also be adjusted on the fly (by dragging).
[[preview.layout]]
command = ""
side = "right"
percentage = 60
min = 30
max = 120

The structure of the config file is defined here⁷, and the full specification lives here⁸. You can also view your current config using mm --dump-config | cat or a quick reference using mm --doc options.

Options can be overridden on the command line, where abbreviations are supported:

mm p.l "cmd=echo {}|||p=50|||max=20" cmd "ls" o "{=}"

# 1. Start mm with the following overrides:
# 2. List the contents of the current directory by executing `ls`
# 3. Show the current item name in the preview pane
# 4. Set a preferred percentage of 50 and a max width of 20 for the preview pane
# 5. Output the result without single quotes

For quick reference, mm --doc provides fairly readable and comprehensive guides to various topics. The rendered markdown is also available here.

Keybindings

Actions can be defined in your config.toml or on the command line.

The list of currently supported actions can be found here and here or from mm --doc binds.

To get the names of keys, type mm --test-keys.

In addition to keys, actions can also be bound to Events and Crossterm events (check your default config for details).

Examples

Examples can be found here (toml files), and here (library use).

Currently, the first includes an example for interactively performing a full text search with ripgrep:

Toggle between ripgrep and mm with ctrl-r
The displayed preview autoscrolls to matched line: ? to toggle.
Enter opens the file in your editor (or when piped, prints file:line:col).
Previous queries in each mode are stashed and restored upon switching.
ctrl-. to cycle between columns.

ripgrep

# Try it yourself
mkdir -p ~/.config/matchmaker/presets
curl -L https://raw.githubusercontent.com/Squirreljetpack/matchmaker/main/matchmaker-cli/assets/presets/rg.toml -o ~/.config/matchmaker/presets/rg.toml
mm --config ~/.config/matchmaker/presets/rg.toml

Presets

Matchmaker is really good for creating workflows. It's like a swiss army knife for building and sharing great TUIs -- check out the collection!⁹

# download a preset (collection)
mm --download=git

# invoke a preset (browse/restore by ref)
mm -o git/restore

# You can also run the first example this way:
mm --download=rg.toml
mm -o rg

git-restore git-help procs docker-containers

Comparison with fzf

To users of fzf, getting started with mm should be conceptually straightforward because the two tools are almost fully feature-compatible. You can continue using familiar actions, like execute, and they will function the same way.¹⁰

For example, opening a selected file in your editor:

In fzf:

fzf --bind "ctrl-o:execute($EDITOR {+})"

In mm:

mm b.ctrl-o="Execute($EDITOR {+})"

Note

Note that templates can be named in matchmaker, but they only replace valid keys.

Here is a second demonstration, taken from zoxide.

In fzf:

fzf \
  --bind=ctrl-z:ignore,btab:up,tab:down \
  --exact \
  --no-sort \
  --cycle \
  --keep-right \
  --border=sharp \
  --height=45% \
  --info=inline \
  --layout=reverse \
  --tabstop=1 \
  --exit-0

In mm:

mm \
  binds.Shift-BackTab=Up \
  binds.BackTab=Up \
  binds.Tab=Down \
  matcher.sort_threshold=0 \
  results.scroll_wrap=true \
  results.wrap=false \
  results.autoscroll.end=true \
  results.autoscroll.context=0 \
  ui.border.type=Plain \
  tui.percentage=45 \
  results.reverse=true \
  exit.abort_empty=true

# Notes:
# - matcher.sort_threshold is not available on the cargo version and requires the installer.
# - results.autoscroll.context=0 is a setting which does not appear in fzf but which is 4 by default in mm.

In mm using aliases (and omitting defaults):

mm m.sort=0 ui.b.type=Plain tui.p=45 \
r.r= r.w=false r.a.e= r.a.c=0 \
b.Shift-BackTab=Up b.BackTab=Up b.Tab=Down

Matchmaker aims to achieve feature-parity with fzf (though not necessarily by the same means). If there's any specific feature that you'd like to see, open an issue!

Library

Matchmaker can also be used as a library.

cargo add matchmaker-lib

Example

Here is how to use Matchmaker to select from a list of strings.

use matchmaker::nucleo::{Indexed, Worker};
use matchmaker::{MatchError, Matchmaker, Result, Selector};

#[tokio::main]
async fn main() -> Result<()> {
    let items = vec!["item1", "item2", "item3"];

    let worker = Worker::new_single_column();
    worker.append(items);
    let selector = Selector::new(Indexed::identifier);
    let mm = Matchmaker::new(worker, selector);

    match mm.pick_default().await {
        Ok(v) => {
            println!("{}", v[0]);
        }
        Err(err) => match err {
            MatchError::Abort(1) => {
                eprintln!("cancelled");
            }
            _ => {
                eprintln!("Error: {err}");
            }
        },
    }

    Ok(())
}

For more information, check out the examples and Architecture.md