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-cache or -C to clear embeddings cache, and --clear-all to clear both model and embedding cache files.

---

Installation

Quick Install (Shell Script)

curl -fsSL https://raw.githubusercontent.com/aether-flux/fzfx/main/install.sh | sh

Cargo Install

cargo install fzfx

Manual Build

# Clone the repo
git clone https://github.com/aether-flux/fzfx
cd fzfx

# Run the CLI
cargo run    # with additional flags and arguments

---

Usage

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_history

---

Flags 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" -c

Search and Execute Immediately

history | fzfx -q "find large files" -x

Non-Interactive Script Integration

CMD=$(fzfx -f commands.txt -q "restart nginx" -r)
eval "$CMD"

Clear all cache files

fzfx --clear-all

---

Shell 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.

[!INFO] 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.

---

License

MIT