---
name: easy-clipboard
description: Easy Clipboard CLI:查询/取回/复制/导出 Windows 剪贴板历史(文本/富文本/图片/文件列表)。安装桌面版(≥0.2.0)后任意终端直接调用,无需其他依赖。
---

# Easy Clipboard CLI

Windows 剪贴板历史管理器:复制过的一切自动入库(文本 / 富文本 HTML / 图片 / 文件列表),随时搜索、取回、复用。**安装桌面版后,任意终端直接使用 `easy-clipboard` 命令**,单文件 exe、无需其他依赖。

## 安装

下载并安装桌面版安装包(**v0.2.0 及以上**含 CLI,默认装到 `C:\Program Files\Easy Clipboard`):

- 安装时把安装目录加入用户 PATH(新开的终端立即可用;安装前已开的终端需重开)
- 卸载时自动从 PATH 移除

数据全部存本机(`%APPDATA%\com.easyclipboard.app\`,SQLite + 图片文件),无任何网络请求;CLI 与常驻 GUI 共用同一数据库(WAL 模式),GUI 运行时可安全并发读取。

## 命令清单

### list — 列出历史条目(固定条目优先,其余按时间倒序)

```powershell
# 最近 20 条
easy-clipboard list

# 按关键词搜内容(子串匹配,大小写不敏感),最多 50 条
easy-clipboard list --search "token" --limit 50

# 只看图片/文件/富文本条目;--json 输出机器可读数组
easy-clipboard list --type image --json
```

`--json` 每条:`{"id":2,"clip_type":"text","preview":"前 300 字","source_app":"Code.exe","created_at":1788739260000,"pinned":true}`;人读输出为 `[id] *类型 时间 预览` 一行一条(`*` 表示已固定)。

### get — 取回条目内容

```powershell
# 文本/富文本条目:输出纯文本到 stdout(管道友好)
easy-clipboard get 12 | findstr token

# 图片条目:必须 --out 导出 PNG
easy-clipboard get 15 --out image.png

# 文件列表条目:逐行输出路径
easy-clipboard get 7

# 完整元数据(含 html、来源窗口标题、时间戳)
easy-clipboard get 12 --json
```

### copy — 把条目按原格式写回系统剪贴板

```powershell
easy-clipboard copy 12
```

文本写 CF_UNICODETEXT;富文本同时写 CF_HTML;文件条目写 CF_HDROP;图片写位图。写回后可直接 Ctrl+V 使用。

### export — 导出全部文本条目为 txt

```powershell
easy-clipboard export --out backup.txt
```

### stats — 统计信息

```powershell
easy-clipboard stats --json   # {total,day,week,top_apps,db_bytes,images_bytes}
easy-clipboard stats
```

## 注意事项

- **条目类型** `--type` 取值:`text`(纯文本)/ `rich`(富文本,`get` 输出其纯文本部分,`--json` 含 html)/ `image` / `files`
- **退出码**:0 成功;1 运行错误(条目不存在、图片文件丢失等);2 用法错误(未知命令/参数)
- 隐私:历史含密码管理器外的全部剪贴板内容,自动化读取时注意脱敏;KeePass 等密码管理器进程默认不记录
- 数据目录可用环境变量 `EASY_CLIPBOARD_DATA_DIR` 覆盖(测试/多实例场景)
- GUI 交互功能(热键唤起、快速粘贴、分组管理)不属于 CLI;自动化场景用上述命令等价完成查询与取回

## 从源码构建(开发者)

```powershell
git clone <easy_clipboard 仓库> && cd easy_clipboard
npm install
cd src-tauri && cargo build --release   # 产物 target/release/easy-clipboard.exe
```

前置:Node 18+、Rust(Windows GNU 工具链)、mingw64 在 PATH 最前。测试跑 `cargo test --release`(debug 测试二进制在本机 GNU 工具链下有加载问题,见 docs/ROADMAP.md)。