rclip: offline semantic image search from the terminal

What rclip solves, and who it is actually for

Most photo tools make you import first. rclip does not. It runs against a directory in place, builds an index next to nothing else, and answers queries like "two parrots on a branch" from the shell. The README frames it as "grep for images", and that framing is accurate about the workflow: you cd into a folder, ask a question, and get a ranked list of file paths with scores.

The intended user is someone with a large local photo archive and a terminal habit. The README's own numbers point at that scale: 84,725 photos on a NAS, 50,000 images on a laptop, 1.28 million images on a MacBook. It also works over SSH, which matters because the alternative for most people is uploading a library to a hosted service. Nothing leaves the machine here.

It is a poor fit for casual users who want a GUI photo manager with albums, faces and edits. rclip returns paths and, optionally, a terminal thumbnail grid. That is the whole product surface.

CLIP embeddings, an index, and cosine-style ranking

The mechanism is standard image retrieval built on a CLIP model. On the first run in a directory, rclip extracts features from every supported image and stores them as a search index. Later runs reprocess only new and changed files, which the README calls fast incremental indexing. Queries are encoded into the same vector space and ranked against the stored vectors, so the output is a score and a filepath.

The interesting part is that text and image queries share that space. That is why `rclip horse + stripes` works as arithmetic rather than as a filter chain: the README describes combined and arithmetic queries where text and image terms can be mixed and weighted. The README example `rclip "2:golden retriever" + "./pool.jpg" - fruit` shows a weight prefix, addition and subtraction in one expression. Vector arithmetic on CLIP embeddings is a known technique, but exposing it as shell syntax is the design choice that separates rclip from a plain keyword search.

The index is the cost center. Feature extraction runs on CPU according to the README's hardware figures, and there is no described GPU path. That makes the first run a batch job you schedule, not an interactive step.

Installing rclip and running a first search

On Linux the README's primary path is Snap. The alternative options are an AppImage for x86_64 and pip.

sudo snap install rclip

On macOS the README gives Homebrew, with a note that only Apple Silicon (arm64) is supported. On Windows you download the .msi from the latest release and run the installer. The pip route exists on all three platforms; on Linux the README pins the CPU wheel index explicitly.

pip install --extra-index-url https://download.pytorch.org/whl/cpu rclip

Once installed, change into a photo directory and ask a question. The first invocation builds the index, so expect a long wait before you see anything on a large folder.

cd ~/Photos
rclip "two parrots on a branch"

The README's example output is a three-column table of score and filepath, with quoted absolute paths and scores in the 0.27 to 0.30 range for the sample query.

score  filepath
0.297  "/photos/sunrise-beach.jpg"
0.286  "/photos/dawn-walk.png"
0.274  "/photos/morning-hike.heic"

Image queries work the same way, but a relative local path must be prefixed with `./` or rclip will not treat it as an image.

cd photos && rclip ./cat.jpg

For the thumbnail grid, start the interactive UI and type into its search input. Note the README's constraint: the UI needs Kitty graphics with Unicode-placeholder support, and text queries are available there while image queries stay in the non-interactive CLI.

rclip --interactive

Where rclip breaks down or is the wrong tool

The first-run cost is the honest limitation. The README reports 15 hours to process 84,725 photos on a NAS with an old Intel Celeron J3455. That is a real overnight-plus job, and on a low-power NAS it is closer to a weekend. Anyone expecting to point rclip at a 100,000-image library and search five minutes later will be disappointed.

The interactive UI has hard terminal requirements. It needs Kitty graphics with Unicode-placeholder support, and image copying needs Kitty 0.27 or newer plus a discoverable `kitten` executable. The README does not document a fallback rendering path for terminals without that support, so on a stock terminal you are limited to the non-interactive output.

Query syntax has sharp edges. A relative image path without `./` is not treated as an image. In the interactive UI, image queries are unavailable by design. And the README does not document how to invalidate or rebuild the index when the underlying model changes, or how to inspect what the index contains. If you need to know why a particular photo ranked where it did, the score column is all you get.

Finally, rclip is not a photo manager. There is no tagging, no album model, no editing, no duplicate detection described in the README. If your problem is organization rather than retrieval, this is the wrong layer.

How rclip differs from hosted photo search and from plain filename tools

The closest thing to a direct comparison in the README is the hosted photo-library category. Products in that space typically require uploading or importing your library into their store, and then let you search. rclip inverts that: the library stays where it is, and the only artifact is a local index. The trade-off is that you own the compute cost and the disk usage instead of renting them.

Against filename and metadata tools, the difference is the query unit. A filename search needs you to have named the file well. rclip ranks by visual content, so a file called `IMG_4821.HEIC` is findable if you can describe what is in it. The README's format list matters here: `jpg`, `png`, `webp`, `tiff`, `gif`, plus native HEIC on macOS and Windows and experimental RAW (`arw`, `cr2`, `dng`). RAW support is labeled experimental, so treat it as such.

Against writing your own CLIP script, rclip's contribution is the packaging around the model: incremental indexing, the arithmetic query syntax, the terminal UI, and installers for three platforms. The model itself is not the novel part.

Maintenance, packaging and licence position

The repository's last push was on 2026-09-15, and the most recent release listed is v3.3.0 from 2026-08-02. The project is not archived. It ships through several channels that each carry maintenance weight: a Snap package with its own `snap/snapcraft.yaml`, a Homebrew tap, an AppImage build script, and a Windows MSI built with PyInstaller. The Makefile shows a release flow that bumps the version with `uv version`, rewrites the Snap version string, commits, tags, and pushes, with CI handling the Homebrew release.

That packaging surface is the upgrade cost. The Python requirement is `>=3.12,<3.14`, so a Python 3.14 environment is outside the supported range, and the dependency list pins several packages tightly, including `textual-image==0.12.0` with a comment that newer versions omit their package code. Tight pins reduce surprise but make dependency upgrades a deliberate act.

On licensing: the project is MIT, declared in `pyproject.toml` with `license-files` pointing at the project LICENSE plus model repository notices, including an OpenAI CLIP MIT notice and a third-party notices file. The practical point is that the model weights ship under their own terms, and the repository keeps those notices next to the project licence rather than folding them together. If you redistribute rclip, read `compliance/model_repository/` rather than assuming the MIT header covers everything. This is not legal advice.

Editorial conclusion

Adopt rclip if your photos already live on a disk you control, you are comfortable in a shell, and you accept one long first indexing run: the README records 15 hours for 84,725 photos on a Celeron J3455 NAS. Skip it if you need Apple Intel support, a documented way to rebuild the index after a model change, or a query language richer than text plus image arithmetic. Before committing a large library, verify two things on a small folder: that your target machine meets the Python 3.12 to 3.13 range or has a Snap, Homebrew or MSI package for your platform, and that the interactive UI renders on your terminal, since it requires Kitty graphics with Unicode-placeholder support rather than plain ANSI.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. yurijmikhalevich/rclip on GitHub