Yuru

A command-line fuzzy finder that can find CJK text by how it sounds.

Type Latin letters, match Japanese, Korean, and Chinese:

yuru --lang zh --filter bjdx      # finds 北京大学.txt   (pinyin initials)
yuru --lang ja --filter kamera    # finds カメラ.txt     (romaji)
yuru --lang ko --filter hangeul   # finds 한글.txt       (romanized Hangul)

If you use fzf, Yuru should feel familiar: the same key bindings, the same shell integration, and most of the same options.

The name is ゆるい - loose, relaxed. Your query can be a little loose and Yuru still finds what you meant.

Localized: 日本語 · 中文 · 한국어

Demo

https://github.com/user-attachments/assets/37f9643f-0ed1-4cca-8a15-c4a8bd78cf34

Install

Installs into your home directory. No sudo.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Ameyanagi/yuru/v0.2.2/install | sh -s -- --all --version v0.2.2

Windows (PowerShell)

$script = Invoke-RestMethod https://raw.githubusercontent.com/Ameyanagi/yuru/v0.2.2/install.ps1
Invoke-Expression "& { $script } -All -Version v0.2.2"

Cargo

cargo install yuru

--all also sets up shell integration and asks a few setup questions - default language, preview style, key bindings - writing your answers to ~/.config/yuru/config.toml. Press Enter to accept the defaults, or re-run the questions any time with yuru configure.

Drop --all to install just the binary. Building from source needs a C compiler for the Japanese dictionary; the released binaries do not.

For unattended installs, checksums, update, and uninstall, see install and uninstall.

Shell integration

Add to your shell config:

eval "$(yuru --bash)"      # bash
source <(yuru --zsh)       # zsh
yuru --fish | source       # fish

Invoke-Expression ((yuru --powershell) -join "`n")   # PowerShell

That gives you:

Same bindings as fzf, so muscle memory carries over.

Usage

Pipe anything in:

fd --hidden --exclude .git . | yuru --scheme path

The interface opens immediately and keeps filling while the input arrives, so it works on large inputs. Use --sync to wait for all input first, like fzf.

Use --filter for non-interactive use, in scripts:

printf "README.md\nsrc/lib.rs\n" | yuru --filter lib

Matching CJK text

Pick a language with --lang, or set one as your default during install:

printf "北京大学.txt\nnotes.txt\n" | yuru --lang zh --filter bjdx
printf "カメラ.txt\n"              | yuru --lang ja --filter kamera
printf "한글.txt\n"                | yuru --lang ko --filter hangeul

Korean also matches choseong initials (ㅎㄱ) and 2-set keyboard input (gksrmf). Use --lang all for mixed lists, or --lang auto to pick a backend from your locale and the input.

Not sure why something matched?

printf "北京大学.txt\n" | yuru --lang zh --filter bjdx --explain

Something not working? Start with yuru doctor.

More detail in language matching.

fzf compatibility

Yuru accepts fzf's option surface, so existing shell bindings and FZF_DEFAULT_OPTS keep working. Search and scripting options - --query, --filter, --nth, --with-nth, --scheme, --expect, --select-1, --print-query, --read0, --print0 and friends - are implemented.

--bind is partial, and unsupported actions warn rather than fail:

yuru --fzf-compat warn    # default
yuru --fzf-compat strict  # fail instead
yuru --fzf-compat ignore  # stay quiet

Full matrix, including preview and image support, in fzf compatibility.

Configuration

~/.config/yuru/config.toml, written for you by the guided install:

[defaults]
lang = "auto"        # plain | ja | ko | zh | all | auto
scheme = "path"      # default | path | history
case = "smart"       # smart | ignore | respect

[preview]
command = "auto"     # auto | none | any shell command

[shell]
bindings = "all"     # all | none | ctrl-t,ctrl-r,alt-c,completion

Every key, and how config interacts with FZF_DEFAULT_OPTS, is in configuration.

Documentation

Contributing

./scripts/install-hooks   # formatter, linter, tests, benches on commit
./scripts/check           # run the same gate manually

scripts/qa/ holds harnesses for questions the test suite cannot answer - comparing output against a previous release, benchmarking against a baseline binary, and driving the interface through a pty. See scripts/qa/README.md.

CONTRIBUTING.md and SECURITY.md have the policies. Release notes are in CHANGELOG.md.

About this project

Yuru is built with heavy AI assistance. Direction, feature choices, language behavior, testing, and releases are decided and reviewed by the maintainer - the code is treated as a maintained open-source project, not unreviewed AI output.

License

MIT or Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.