zotero-cli
Skill9 starsChanged 53 days agoMITView on GitHub
Zotero 文献管理 CLI(zot)v2。使用资源+动作命令检索、查看、导出和安全修改 Zotero 文献库,读取 PDF/标注、构建引用与全文索引,并支持 web/local/hybrid/remote。
2 other projects use a version of this.
Adopted by
Most recently taken up by
- WeiXu94/skillstheir own version, first seen Nov 15, 2026
- huang-sh/PiXtheir own version, first seen Nov 13, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- huang-sh/PiX★ 240same name
- WeiXu94/skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Files
Zotero CLI v2
Zotero 10 本地写入
local/hybrid 通用写入默认使用 Zotero 10 本地 API;--write-backend web 可保留云端写入。用 config local --json 探测、config local --authorize 授权,本地与云端版本号不可混用。
附件管理支持 file list/add/move/detach;添加复制存储附件,保留源文件。优先 --dry-run,上传失败按明确附件 KEY 使用 --resume,不要重复创建空附件。详见 docs/user/local-writes.md。
Library taste(文献管理偏好)
涉及标签、收藏夹、分类层级、命名、合并或其他需要判断用户文献管理偏好的任务时,必须先运行:
.\zot.exe lib taste --json当 data.exists=true 时,完整读取 data.content,并按“当前用户指令 > taste.md > 工具默认行为”的优先级执行。文件不存在时,提示用户运行 .\zot.exe lib taste --init,但不要阻塞其他安全操作。
优先调用仓库中的 zot/zot.exe,源码验证时使用 go run .\cmd\zot。不要自行重写 Zotero API 调用。
执行原则
- 在仓库根目录工作。
- Agent 默认加
--json,JSON 的command是 canonical path,例如item find。帮助页与completion是纯文本产物,不要附加--json;config init --json不会交互,必须传齐当前模式所需参数。 - 首次使用先运行
zot config check --json。 - 不确定参数时运行
zot <resource> <action> --help;help 不加载配置或网络。 - 写入前确认用户意图,并检查
ZOT_ALLOW_WRITE/ZOT_ALLOW_DELETE。 - 只生成 canonical 命令;除正式快捷入口
find/show/export外,不尝试旧命令或旧参数。
Canonical 命令树
lib show|stats|taste|log
item list|find|show|new|edit|delete|tag|untag|supp|export|import
coll list|show|new|edit|delete|add|remove
note list|show|find|new|edit|delete
tag list|replace|apply|clean
search list|show|new|edit|delete
group list
file path|show|check
pdf text|figs|open
ann list|new|delete
ref show|find|related|cited|ctx|links|entities|profile|build|resolve|status
index build|status
schema list|show
config init|show|check
serve
sync
completion
versionfind、show、export 是正式高频快捷入口,分别进入 item find/show/export,没有独立实现。
推荐入口
zot lib show --json
zot lib stats --json
zot item find "query" --in metadata --limit 20 --json
zot item show ITEMKEY --json
zot item export ITEMKEY --as bibtex --json
zot item export KEY1 KEY2 --as bibliography --style nature
zot ref show ITEMKEY --json
zot index status --json最近入库使用 dateAdded:
zot item find --sort dateAdded --order desc --limit 10 --json
zot item find --all --added-since 7d --sort dateAdded --order desc --json统一分页参数为 --limit、--offset、--sort、--order asc|desc。
item find 未显式指定 --limit 时,轻量结果默认限制 100 条,--snippet 或 --full 默认限制 20 条。--all 仅取消结果上限,并与 --limit 互斥;metadata 范围可省略 QUERY。JSON meta 提供 returned、limit、offset、has_more 和可选的 next_offset。
默认 find/show --json 使用轻量结构:creator_summary 是字符串,collection_names 是名称数组。完整 Item 必须显式使用 --full,其中 creators / collections 是对象数组。find --snippet 与 --full 互斥,只返回轻量元数据和以真实命中为中心、最多约 1200 字符的 matched_chunk 证据。
Item type 归一化
CLI 输入接受短 alias,但应用层和 JSON 始终使用 Zotero 官方值:
| CLI alias | canonical value |
article | journalArticle |
chapter | bookSection |
conf | conferencePaper |
web | webpage |
blog | blogPost |
例如:
zot item find "CRISPR" --type article --json
zot schema list fields article --json全文决策顺序
不要把整篇提取当作全文检索的默认入口:
- 检索正文证据:
item find QUERY --in fulltext --snippet --json - 单篇轻量预览:
item show ITEMKEY --snippet --json - 明确需要整篇:
pdf text ITEMKEY --json
zot item find 'methods OR procedure*' --in fulltext --snippet --limit 20 --json
zot item show ITEMKEY --snippet --json
zot pdf text ITEMKEY --pages 3-8 --grep methods --max-chars 12000 --json
zot pdf text ITEM1 ITEM2 --grep "gene\s+flow|introgression" --json
zot pdf text --collection "研究/植物/栗属" --grep "gene\s+flow|introgression" --jsonpdf text 会优先命中 .zotero_cli/fulltext 缓存;只有 cache miss 才重新提取。PDF 路径、大小或高精度修改时间变化时缓存自动失效,FTS 检索也不会返回已过期正文。local/hybrid 下无过滤条件的请求返回 content_path 和可选的 chunks_path,Agent 直接读取 content_path,不要期待 JSON 内嵌整篇正文。这些是提取文本缓存,不是 PDF 二进制副本;源附件用 file path 查询。只有 --grep、--pages 或 --max-chars 返回文本子集。--grep 默认是不区分大小写的 Go 正则;多关键词直接使用 |,特殊字符按正则规则转义。--collection 接受收藏夹 key、唯一名称或完整层级路径。有分页缓存时,JSON 按附件和命中页返回 match_count、页码与上下文;检索不会自动创建标注。只有显式 --output-dir 才导出 Markdown且不会复制源 PDF;remote 模式仍返回正文。
PDF、附件与标注
zot item supp ITEMKEY --json
zot item import ./paper.pdf --collection "研究/植物/栗属" --json
zot file path ATTACHKEY --json
zot file path --item ITEMKEY --json
zot file show ATTACHKEY --json
zot file check ATTACHKEY --json
zot pdf figs ITEMKEY --output-dir .\figures --json
zot pdf open ITEMKEY --page 5
zot ann list ITEMKEY --type highlight --page 3 --json
zot ann list ITEMKEY --attachment ATTACHMENT_KEY --json
zot ann new ITEMKEY --attachment ATTACHMENT_KEY --text "target phrase" --color yellow --json
zot ann delete ITEMKEY --source zotero --type highlight --dry-run --json
zot ann delete ITEMKEY --source zotero --type highlight --yes --json
zot ann delete ITEMKEY --source pdf --attachment ATTACHMENT_KEY --type highlight --yes --jsonitem import --collection 接受收藏夹 key、唯一名称或完整层级路径;名称有歧义时会列出带 key 的完整路径候选,不会自动猜测。导入依赖 Zotero 桌面端 Connector,并在识别完成后为最终保留的附件建立增量全文索引。item import --dry-run 不要求写权限,只校验 PDF、Connector 和收藏夹,不上传文件或创建条目。file path 只返回真实本地路径;file check 返回路径和附件健康状态;表格预览参数只属于 file show。pdf open 使用系统默认程序并返回路径,--page 只是可能被忽略的提示。
读取、创建、删除分别使用 ann list/new/delete。多 PDF 条目默认选择第一个 PDF,应优先使用 --attachment ATTACHMENT_KEY 精确选择。ann new 在临时副本中写入并验证后替换,非 dry-run 零匹配会失败且保留原 PDF。删除必须显式选择 --source zotero|pdf,并优先用 --dry-run 查看精确候选;不要生成 annotations --clear 或 annotate --clear,也不要直接修改 itemAnnotations。
Reference
zot ref show ITEMKEY --json
zot ref find 'genome AND assembl*' --in metadata --field mesh --json
zot ref related ITEMKEY --limit 20 --json
zot ref cited ITEMKEY --external --json
zot ref ctx ITEMKEY --json
zot ref links ITEMKEY --json
zot ref entities ITEMKEY --json
zot ref profile ITEMKEY --json
zot ref build --workers 3 --json
zot ref build --scope failed --workers 2 --json
zot ref build --scope contexts --workers 3 --json
zot ref resolve --workers 8 --json
zot ref status --json
zot ref status --view failed --json
zot ref status --view unsupported --jsonPMC JATS 优先;没有 PMC 时使用 PubMed,并以 Europe PMC 增强。Europe PMC 失败不得阻断 NCBI 核心结果。GROBID 仅在显式 --scope grobid 时启用。
安全写入
zot item new --set itemType=article --set title="Example" --dry-run --json
zot item edit ITEMKEY --set title="New" --if-version 42 --json
zot item tag KEY1 KEY2 --tag review --json
zot coll new --name "Reviews" --json
zot note new --parent ITEMKEY --text "Reading note" --json写入输入统一为:
--set FIELD=VALUE(可重复)--data JSON--from PATH,--from -表示 stdin
安全参数统一为 --dry-run、--yes/-y、--if-version。
破坏性操作包括 item/coll/note/search delete 和 ann delete。执行前复述目标 key,确认无歧义,并遵守门控和确认要求。
配置与运行时
zot config init
zot config show --json
zot config check --json
zot serve
zot sync
zot completion powershellconfig check 会报告 zotero_desktop_connector_available 和 Connector 地址。Connector 不可用不会使整个配置检查失败,但执行 item import 前必须启动 Zotero 桌面端;导入失败时应优先展示 CLI 给出的启动提示。
模式:
web:Zotero Web APIlocal:本地 SQLite + storagehybrid:本地优先,仅在语义可保持时回退 Webremote:通过zot serve访问远端数据
pure remote 下 ann list/new/delete 可由服务端执行;其余 Web 写操作仍需 API key。
已退出稳定 CLI 的入口
旧 alias、旧参数翻译和 redirect-only adapter 已全部移除。setup、abstract、key-info、select、relate 等旧入口会返回 unknown command;不要生成或尝试执行它们。
仅 find、show、export 是受支持的正式快捷入口,且只接受对应 item find/show/export 的 canonical 参数。
详细参数、模式矩阵、兼容清单和 JSON 示例见 reference.md、find-output.md 与 show-output.md。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

