yurijmikhalevich/rclip

rclip – grep for images

What it is – rclip is a command‑line tool that lets you search the contents of image files on your own computer using natural language, an example picture, or a combination of both. It builds a local CLIP‑based embedding index of the images in a folder and then ranks results for a query, all without sending any data to the cloud.

Key capabilities

• Text‑only search – e.g. rclip "two parrots on a branch"
• Reverse‑image search – supply a local path or URL and get visually similar pictures.
• Mixed/arithmetic queries – combine or subtract text and image terms, optionally weighting them (2:golden retriever + ./pool.jpg - fruit).
• Incremental indexing – only new or changed files are processed on subsequent runs, making repeated searches fast.
• Interactive terminal UI – a thumbnail grid that works in terminals supporting Kitty graphics (Kitty, Ghostty, iTerm2, Konsole). Keyboard shortcuts let you browse, copy, download, or open images without leaving the shell.
• Wide format support – JPEG/PNG/WebP/TIFF/GIF and native HEIC on macOS/Windows; experimental RAW (arw, cr2, dng) via a flag.
• Cross‑platform – packaged as a Snap, AppImage, Homebrew formula, MSI installer, and a pip wheel; runs on Linux, macOS (Apple Silicon only), and Windows.

How it works

• Uses the OpenCLIP ViT‑B/32 model (the same architecture as OpenAI’s CLIP) to turn both images and text into 512‑dimensional embeddings.
• Embeddings are stored locally in a simple index per folder; queries are answered by computing the cosine similarity between the query embedding(s) and the stored image embeddings.
• All computation happens on the CPU (or GPU if the underlying PyTorch build picks it up), so the tool works offline and keeps your photos private.

Typical workflow

# First run – builds the index for the current folder
cd ~/Photos && rclip "sunset over lake"

# Subsequent runs are fast (only new files are indexed)
cd ~/Photos && rclip "two cats"

# Interactive UI with inline previews
rclip --interactive

# Image‑to‑image search
rclip ./example.jpg

The tool can also output plain file paths (-f) for piping into other commands (e.g., xargs cp, feh, or custom scripts).

Installation

• Linux – sudo snap install rclip (or download the AppImage, or pip install rclip with the PyTorch CPU wheel).
• macOS – brew install yurijmikhalevich/tap/rclip (Apple Silicon) or pip install rclip.
• Windows – download the MSI installer from the latest release, or pip install rclip.

License – MIT.

Where to learn more – Blog post, YouTube demos, and a short paper are linked from the README; discussions and contributions are welcomed via the GitHub Discussions page.