fzfx
fzfx is an offline, fast, and semantic CLI command finder designed to instantly discover previously executed terminal commands using vector search rather than rigid exact or fuzzy substring matching.
Features
- Local Semantic Search: Uses ONNX-powered local embeddings (
AllMiniLML6V2) via FastEmbed. - Instant Cache: Smart hit/miss disk caching. Repeated commands bypass model execution entirely.
- Direct Execution (
-x/--exec): Automatically runs your chosen command in a subshell once selected. - Clipboard Copy (
-c/--copy): Copies the selected command directly to your system clipboard. - Script & Agent Friendly (
-r/--raw): Outputs only the top match string without interactive terminal UI or extra logs. - Clear Cache: Use
--clear-cacheor-Cto clear embeddings cache, and--clear-allto clear both model and embedding cache files.
Installation
Quick Install (Shell Script)
curl -fsSL https://raw.githubusercontent.com/aether-flux/fzfx/main/install.sh | shcargo Install
cargo install fzfxManual Build
# Clone the repo
git clone https://github.com/aether-flux/fzfx
cd fzfx
# Run the CLI
cargo run # with additional flags and argumentsUsage
Basic Interactive Search
Pipe any command list or history file into fzfx:
# Search through bash history
cat ~/.bash_history | fzfx -q "check disk space"
# Search through your terminal's history
history | fzfx -q "list disk partitions"
# Search active process list
ps aux | fzfx -q "kill web server"If no query (-q or --query) is supplied, fzfx prompts for input interactively:
fzfx -f ~/.bash_historyFlags and Options
| Flag | Long Flag | Description |
|---|---|---|
-q | --query <TEXT> | Initial search query |
-f | --data-file <PATH> | Path to candidate file (one entry per line) |
-x | --exec | Automatically execute selected command |
-c | --copy | Copy selected command to clipboard |
-r | --raw | Print top match only (non-interactive, for scripts/AI agents) |
-k | --top-k <NUM> | Specify number of results to show (default = 10) |
-C | --clear-cache | Remove cache files for command embedding |
| NA | --clear-all | Remove both model and embedding cache files |
Examples
Search and Copy Command
fzfx -f ~/.bash_history -q "list docker containers" -cSearch and Execute Immediately
history | fzfx -q "find large files" -xNon-Interactive Script Integration
CMD=$(fzfx -f commands.txt -q "restart nginx" -r)
eval "$CMD"Clear all cache files
fzfx --clear-allShell Integration
Add a convenient shortcut to your ~/.zshrc or ~/.bashrc to invoke fzfx directly over your command history:
fz() {
local cmd
cmd=$(cat ~/.bash_history | fzfx -q "$*" -c)
}Benchmarks
fzfx is benchmarked using Criterion.rs across multiple execution paths to evaluate model cold starts, embedding latencies, and persistent cache hit speeds.
| Execution State | Latency | Description |
|---|---|---|
| Fully Cold | ~10.3s | Initial runtime setup, model weight loading, and initial downloads. |
| Warm model, Cold cache | ~36.1ms | Model cached on-disk, batch computing ~10 missing embeddings via fastembed. |
| Warm model, Warm cache | ~729.5ns | Instant lookup hit against cached embeddings serialized into hashmap (ahash). |
| Hybrid Rerank only | ~2.5µs | Combined fuzzy distance search and cosine vector similarity to calculate final score. |
NOTE
Note on Cold Starts: Benchmark 01 reflects isolated test runs that re-instantiate the ONNX environment on every iteration. In real-world CLI usage, warm-cache lookups execute sub-millisecond (< 1 µs), making fzfx feel instant in the terminal.
Cache and Storage
fzfx respects standard OS cache paths:
- Linux:
~/.cache/fzfx/ - macOS:
~/Library/Caches/fzfx/ - Windows:
%LOCALAPPDATA%\fzfx\cache\
Model weights are cached under their specific directories and precomputed line vectors are serialized into embeddings.bin. To reset your search index cache, simply delete embeddings.bin.
