paperless-ngx：通过 ppls 工具与 Paperless-NGX 文档管理系统进行交互交互

infrastructure · 2026-02-28 06:27:44 · 2 次点击 · 0 条评论

name: paperless
description: 通过 ppls CLI 与 Paperless-NGX 文档管理系统交互，实现文档的搜索、获取、上传与整理。
emoji: 📄
metadata: {"clawdbot":{"requires":{"bins":["ppls"],"env":["PPLS_HOSTNAME","PPLS_TOKEN"]},"install":[{"id":"node","kind":"node","package":"@nickchristensen/ppls","bins":["ppls"],"label":"安装 ppls CLI (npm/bun)"}]}}

Paperless-NGX CLI

使用 ppls 命令行工具搜索和管理 Paperless-NGX 中的文档。

环境配置

npm install -g @nickchristensen/ppls
ppls config set hostname http://你的-paperless-主机地址
ppls config set token 你的-API-令牌

文档搜索

# 按名称搜索
ppls documents list --name-contains "发票" --json

# 按日期范围搜索
ppls documents list --created-after 2024-01-01 --created-before 2024-12-31 --json

# 按标签搜索（OR 逻辑：包含任意一个标签）
ppls documents list --tag 5 --tag 12 --json

# 按标签搜索（AND 逻辑：必须包含所有标签）
ppls documents list --tag-all 5,12 --json

# 排除特定标签
ppls documents list --tag-not 3 --json

# 按通信方搜索
ppls documents list --correspondent 7 --json

# 按文档类型搜索
ppls documents list --document-type 2 --json

# 搜索缺失元数据的文档
ppls documents list --no-correspondent --json
ppls documents list --no-tag --json

# 搜索最近添加/修改的文档
ppls documents list --added-after 2024-06-01 --json
ppls documents list --modified-after 2024-06-01 --json

# 组合筛选条件
ppls documents list --correspondent 7 --created-after 2024-01-01 --tag 5 --json

查看与下载

# 获取文档完整详情（包含 OCR 内容）
ppls documents show 1234 --json

# 下载单个文档
ppls documents download 1234 --output ~/Downloads/doc.pdf

# 批量下载文档
ppls documents download 1234 5678 --output-dir ~/Downloads

# 下载原始（未经处理）版本
ppls documents download 1234 --original

上传文档

# 简单上传（由 Paperless 自动处理）
ppls documents add 扫描件.pdf

# 附带元数据上传
ppls documents add 收据.pdf \
  --title "商店收据" \
  --correspondent 5 \
  --document-type 2 \
  --tag 10

管理元数据

# 列出标签/通信方/文档类型
ppls tags list --json
ppls correspondents list --json
ppls document-types list --json

# 创建新项目
ppls tags add "2024税务" --color "#ff0000"
ppls correspondents add "新供应商"
ppls document-types add "合同"

# 更新文档元数据
ppls documents update 1234 --title "新标题" --correspondent 5 --tag 10

使用提示

始终使用 --json 参数：便于 AI 或自动化脚本解析，是最佳输出格式。
日期格式：使用 YYYY-MM-DD 或完整的 ISO 8601 格式。
ID 为数字：通过 list --json 命令查找对应的 ID。
筛选条件可重复：--tag 1 --tag 2 与 --tag 1,2 效果相同。
分页处理：对于大量结果，使用 --page 和 --page-size 参数。