rclip：终端里的本地图片搜索工具

项目简介

rclip 是一个给命令行用的本地图片搜索工具，可以理解为「图片版的 grep」。用自然语言描述、示例图片或两者组合，搜索任意文件夹里的照片，无需打标签、上传或导入到图片库。它在本机离线运行，可在 SSH 中使用，也能和 Unix 工具通过管道配合。

主要功能

• 自然语言搜索：按图片内容描述查找，例如 rclip "two parrots on a branch"。
• 以图搜图：传入本地图片路径或图片 URL，返回最相似的图片。相对路径必须以 ./ 开头。
• 组合与加权查询：文本和图片查询可以相加、相减，例如 rclip "2:golden retriever" + "./pool.jpg" - fruit。
• 本地与隐私：完全离线工作，照片不会离开你的电脑。
• 格式支持：jpg、jpeg、png、webp、tiff、tif、bmp、gif、jp2、pnm、pbm、pgm、ppm；macOS / Windows 支持 HEIC；通过 --experimental-raw-support 支持 RAW。
• 增量索引：再次运行时只处理新增和变化的图片，并从索引中移除已删除的图片。
• 交互式终端 UI：rclip -i，在终端里用缩略图网格浏览和搜索。
• 终端内预览：-p 在支持 Kitty graphics 的终端里直接显示结果。
• 可脚本化：-f / -0 输出文件路径，--json 输出 JSON 数组，便于脚本和 AI agent 调用。
• 跨平台：Linux、macOS（Apple Silicon）、Windows。

安装与使用

Linux：

sudo snap install rclip

macOS（仅支持 Apple Silicon）：

brew install yurijmikhalevich/tap/rclip

Windows：从 latest release 下载 *.msi 后运行安装程序。

也可以用 pip 安装：

pip install rclip

基本用法：

cd photos && rclip "an orange cat"

首次在某个目录运行时，rclip 会提取图片特征建立索引，耗时取决于 CPU 和图片数量。之后可用 -n 跳过索引直接搜索。

交互式界面：

rclip --interactive

以图搜图：

rclip ./cat.jpg

管道到其他工具，例如用 feh 预览前 5 个结果：

rclip -f -t 5 kitty | feh -f - -t

注意事项

• 交互式 UI 依赖 Kitty graphics 与 Unicode 占位符支持，需要 Kitty、Ghostty 或最新 iTerm2；预览（-p）在 Konsole 中也可用。搜索与脚本用法在任何终端都能工作。
• HEIC 在 macOS 通过 Image I/O、Windows 通过 WIC 支持，需要系统已安装 HEIF/HEVC 编解码器；Linux 发行版目前不支持 HEIC。
• RAW 格式需要显式加 --experimental-raw-support；开启后，同名目录下存在已处理的 JPEG 等图片时会跳过 RAW 原图。
• 索引时间与图片数量和 CPU 性能强相关，大规模图库首次运行可能耗时较长。

---

本作品整理自 GitHub 开源项目 yurijmikhalevich/rclip，原作者 @yurijmikhalevich，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。