cli-anything-zotero 0.3.0

CLI for Zotero 7/8 — let AI manage your library. 40+ commands for search, import, PDF, BibTeX export, and more.

cli-anything-zotero

Let AI manage your Zotero library.

中文文档 | English | WeChat Group 👇

---

For Non-Programmers: You Don't Need to Read This Whole Page

This tool is designed to be used by AI, not memorized by you. After a simple install (takes ~3 minutes), you just talk to your AI assistant in plain language:

"Help me find papers about diabetes and kidney disease in my Zotero library"

"Import this DOI into my CKM collection: 10.1038/s41586-024-07871-6"

"Export all papers in my thesis collection as BibTeX"

"Find PDFs for all items in my review collection that are missing them"

"Summarize the key findings of this paper: ITEM_KEY"

The AI reads the command reference automatically -- you never need to. Just install it and start asking.

All you need to do:

1. Follow the Installation steps below (Python + one Zotero plugin)
2. Tell your AI assistant (Claude Code, Cursor, etc.) what you need
3. That's it

---

对非程序员朋友的说明

这个工具不需要你记住任何命令，安装完之后直接用中文告诉 AI 你想做什么就行：

"帮我在 Zotero 里搜一下关于糖尿病和肾病的文献"

"把这个 DOI 导入到我的 CKM 合集里：10.1038/s41586-024-07871-6"

"把毕业论文合集里的文献全部导出成 BibTeX"

"帮我找一下综述合集里缺 PDF 的文献，自动下载"

"总结一下这篇文章的主要发现"

你只需要：

1. 按照下面的安装步骤装好（Python + 一个 Zotero 插件，3 分钟）
2. 打开你的 AI 工具（Claude Code、Cursor 等），用自然语言说你想做什么
3. 没了

---

Built on CLI-Anything by HKUDS. Designed for AI agents (Claude Code, Cursor, Codex, etc.) and power users.

Why This Tool?

Zotero's built-in HTTP server was designed for browser extensions, not for AI agents or CLI workflows. It has no API for attaching PDFs, updating metadata, triggering sync, or running full-text search.

This CLI fills those gaps through a JS Bridge -- a lightweight Zotero plugin that exposes a privileged JavaScript endpoint. Zero UI popup, millisecond response.

---

Installation

Prerequisites: Python 3.10+, Zotero 7/8 (running). No other system tools needed.

1. Install the CLI

pip install cli-anything-zotero

Or install from source:

git clone https://github.com/PiaoyangGuohai1/cli-anything-zotero.git
cd cli-anything-zotero && pip install -e .

2. Install the JS Bridge Plugin (one-time)

cli-anything-zotero app install-plugin

First install requires manual steps in Zotero:

1. The command generates a .xpi file and prints its path
2. In Zotero: Tools -> Plugins -> gear icon -> Install Plugin From File...
3. Select the .xpi file, then restart Zotero

After the first install, future upgrades via app install-plugin are automatic.

3. Verify

cli-anything-zotero app plugin-status --json
# Should show: "plugin_installed": true, "endpoint_active": true

cli-anything-zotero app ping
cli-anything-zotero js "return Zotero.version"

Troubleshooting

Problem	Solution
Cannot resolve Zotero profile directory	Launch Zotero at least once first
Plugin not appearing	Restart Zotero after installing the .xpi
endpoint_active: false	Plugin failed to load -- reinstall via Zotero UI
Windows: pip not recognized	Close and reopen PowerShell after installing Python

---

Core Features

Everything below works out of the box after installation. No extra services needed.

Search & Browse

cli-anything-zotero item find "machine learning"      # keyword search
cli-anything-zotero item search-fulltext "CRISPR"      # search inside PDFs
cli-anything-zotero collection tree                     # browse collection hierarchy

Import

cli-anything-zotero import doi "10.1038/s41586-024-07871-6" --tag "review"
cli-anything-zotero import pmid "37821702" --collection FMTCPUWN
cli-anything-zotero import file ./refs.ris

Read & Export

cli-anything-zotero item get ITEM_KEY                   # full metadata
cli-anything-zotero item export ITEM_KEY --format bibtex
cli-anything-zotero item citation ITEM_KEY               # formatted citation
cli-anything-zotero item context ITEM_KEY                # LLM-ready context

Write & Manage

cli-anything-zotero item update KEY --field title="New Title"
cli-anything-zotero item tag KEY --add "important"
cli-anything-zotero item attach KEY ./paper.pdf
cli-anything-zotero item find-pdf KEY                    # auto-find PDF online
cli-anything-zotero note add KEY --text "My note"
cli-anything-zotero sync

Advanced

cli-anything-zotero item search-annotations "risk"       # search all highlights
cli-anything-zotero item annotations KEY                  # view PDF annotations
cli-anything-zotero item metrics KEY                      # NIH citation metrics
cli-anything-zotero collection stats COLLECTION_KEY       # collection statistics
cli-anything-zotero js "return await Zotero.Items.getAll(1).then(i => i.length)"

---

Optional Features

These require extra services. Everything else works without them.

Semantic Search -- requires an embedding API

Any OpenAI-compatible /v1/embeddings endpoint (Ollama, LM Studio, OpenAI, etc.).

# 1. Build the vector index (one-time)
cli-anything-zotero item build-index

# 2. Search
cli-anything-zotero item semantic-search "cardiovascular risk prediction"
cli-anything-zotero item similar ITEM_KEY

Variable	Default	Description
ZOTERO_EMBED_API	http://127.0.0.1:8080/v1/embeddings	Embedding API endpoint
ZOTERO_EMBED_MODEL	nomic-embed-text	Model name
ZOTERO_EMBED_KEY	(empty)	API key (if needed)

AI Analysis -- requires OpenAI API key

export OPENAI_API_KEY=sk-...
cli-anything-zotero item analyze ITEM_KEY --question "What are the main findings?"

---

Full Command Reference

40+ commands across 12 groups. See docs/COMMANDS.md for the complete reference.

---

Comparison with Other Tools

Feature	cli-anything-zotero	zotero-cli-cc	pyzotero-cli	zotero-mcp
JS Bridge (privileged ops)	Yes	No	No	No
Write without API Key	Yes (local)	No (Web API)	No (Web API)	No (Web API)
Trigger Zotero Sync	Yes	No	No	No
Execute arbitrary Zotero JS	Yes	No	No	No
Auto-find PDF online	Yes	No	No	No
Search PDF annotations	Yes	No	No	No
Direct SQLite Read	Yes	Yes	Partial	No
Full-text Search (inside PDFs)	Yes (JS Bridge)	Yes (SQLite index)	No	Yes
Import by DOI/PMID	Yes	Yes	No	Yes
BibTeX/CSL-JSON Export	Yes	Yes	Yes	No
Semantic Search (embeddings)	Yes	Yes (workspace RAG)	No	Yes
AI Analysis	Yes	Yes	No	No
Terminal CLI	Yes	Yes	Yes	No
MCP Protocol	Planned	Yes	No	Yes
JSON Output	Yes	Yes	Yes	N/A
REPL Mode	Yes	No	No	No
Session State	Yes	No	No	No
Offline Read	Partial	Yes	No	No
License	Apache 2.0	CC BY-NC 4.0	MIT	MIT

Why cli-anything-zotero?

• JS Bridge -- the only tool that can execute privileged Zotero operations locally. Attach PDFs, trigger sync, search annotations, find PDFs online -- all without an API key or internet connection for writes.
• Apache 2.0 -- free for commercial use. The main CLI competitor uses CC BY-NC 4.0 which prohibits commercial use.
• AI-agent native -- built on the CLI-Anything framework, designed from the ground up for AI coding assistants.

---

License

Apache 2.0 -- same as CLI-Anything.

---

中文文档

让 AI 帮你管理 Zotero 文献库。

基于 CLI-Anything 框架。专为 AI Agent 和高级用户设计。

为什么需要这个工具？

Zotero 内置 HTTP 服务只为浏览器扩展设计，无法添加 PDF、更新元数据、触发同步或全文搜索。本工具通过 JS 桥填补这些空缺 -- 零弹窗、毫秒级响应。

安装

前提： Python 3.10+，Zotero 7/8（运行中）。无需其他系统工具。

第一步：安装 CLI

pip install cli-anything-zotero

第二步：安装 JS 桥插件（一次性操作）

cli-anything-zotero app install-plugin

首次安装需要在 Zotero 中手动导入：

1. 上面的命令会生成一个 .xpi 文件并显示路径
2. 在 Zotero 中：工具 -> 插件 -> 齿轮图标 -> Install Plugin From File...
3. 选择 .xpi 文件，重启 Zotero

装好后以后升级都是自动的。

第三步：验证

cli-anything-zotero app plugin-status --json
cli-anything-zotero app ping

核心功能

安装完成后开箱即用，无需额外服务。

# 搜索
cli-anything-zotero item find "机器学习"
cli-anything-zotero item search-fulltext "CRISPR"
cli-anything-zotero collection tree

# 导入
cli-anything-zotero import doi "10.1038/s41586-024-07871-6" --tag "综述"
cli-anything-zotero import pmid "37821702"

# 读取与导出
cli-anything-zotero item get ITEM_KEY
cli-anything-zotero item export ITEM_KEY --format bibtex
cli-anything-zotero item context ITEM_KEY            # LLM 友好格式

# 写入与管理
cli-anything-zotero item update KEY --field title="新标题"
cli-anything-zotero item attach KEY ./论文.pdf
cli-anything-zotero note add KEY --text "我的笔记"
cli-anything-zotero sync

可选功能

功能	需要	命令
语义搜索	嵌入 API（Ollama/LM Studio 等）	item semantic-search, item similar, item build-index
AI 分析	OPENAI_API_KEY	item analyze

完整命令参考

40+ 命令，12 个分组。详见 docs/COMMANDS.md。

与其他工具对比

特性	cli-anything-zotero	zotero-cli-cc	pyzotero-cli	zotero-mcp
JS ��（特权操作）	有	无	无	无
写入无需 API Key	有（本地）	无（Web API）	无（Web API）	无（Web API）
触发 Zotero 同步	有	无	无	无
执行任意 Zotero JS	有	无	无	无
自动在线找 PDF	有	无	无	无
搜索 PDF 标注	有	无	无	无
SQLite 直接读取	有	有	部分	无
全文搜索（PDF 内容）	有（JS 桥）	有（SQLite 索引）	无	有
DOI/PMID 导入	有	有	无	有
BibTeX/CSL-JSON 导出	有	有	有	无
语义搜索（向量）	有	有	无	有
终端 CLI	有	有	有	无
许可证	Apache 2.0	CC BY-NC 4.0	MIT	MIT

为什么选 cli-anything-zotero？

• JS 桥 -- 唯一能在本地执行 Zotero 特权操作的工具。附加 PDF、触发同步、搜索标注、在线找 PDF，写入无需 API Key 或联网。
• Apache 2.0 -- 可商用。主要竞品使用 CC BY-NC 4.0 禁止商用。
• AI Agent 原生 -- 基于 CLI-Anything 框架，为 AI 编程助手设计。

许可证

Apache 2.0