zotero-cli
bahayonghang/zotero-cli
Agent-first Rust Zotero CLI with bundled skills for Claude Code and other agents to search libraries, extract PDF evidence, build semantic workspaces, and perform safe Web API writes.
Instalação
npx convez-ai bahayonghang/zotero-cli1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
zot
An agent-first Zotero skill runtime for querying, reading, and safely updating library content.
Turn an existing Zotero library into a dependable content surface for AI workflows: find items, read PDF evidence, extract annotations and notes, build topic workspaces, and perform gated Zotero Web API writes.
English · 简体中文 · Docs (EN) · 文档(中文)
What this repo is really for
zot has two layers:
skills/zot/SKILL.mdis the main operator surface. Install it when you want Claude Code or a similar agent to handle Zotero work from plain-language requests.- The Rust
zotbinary is the execution layer behind that skill. Humans can run it directly for debugging, scripting, or local verification.
If the real goal is “use the papers, notes, tags, PDFs, annotations, or feeds already inside Zotero”, start from the skill. The CLI is the runtime, not the main mental model.
This matches the underlying products:
- Zotero stores library data in
zotero.sqliteplus attachment files understorage/. - Zotero items carry metadata, notes, tags, attachments, and other related data.
- Zotero annotations can be turned into notes with links back to the source PDF page.
- Zotero write operations go through the Web API with write-scoped credentials and version checks.
zot mirrors that structure for agents: read local content directly, route mutations through the Web API, and keep the workflow explicit.
What the skill can do with Zotero content
| What you want | What the zot skill can surface |
|---|---|
| Find the right source | Search by query, tag, creator, year, collection, citation key, library, or feed |
| Read the evidence | Return item metadata, child items, citations, PDF text, outline, notes, and annotations |
| Build a working set | Create a topic workspace, import matching papers, index it, and query it |
| Reuse full-library context | Build a library semantic index and run BM25 / semantic / hybrid retrieval |
| Update the library safely | Add notes, tags, collection membership, imports, duplicate merges, and status sync with explicit permission |
| Keep the agent honest | Run doctor, enforce dry-run gates, emit a stable JSON envelope, and never write to zotero.sqlite directly |
Recommended agent setup
Install the skill first. Then provide the runtime it calls.
1. Install the skill
npx skills add https://github.com/bahayonghang/zotero-cli --skill zot
This installs the bundled workflow contract from skills/zot/SKILL.md.
2. Install the runtime
cargo install --git https://github.com/bahayonghang/zotero-cli.git zot-cli --locked
3. Run one environment check
zot --json doctor
If you are working inside this repository and zot is not on PATH, use:
cargo run -q -p zot-cli -- --json doctor
Keep one invocation path for the whole session. Do not switch back and forth.
doctor reports write_credentials even in local-only setups. That field is optional for local reads and only matters for Zotero Web API writes.
If local PDF reads need Pdfium and no compatible library is already present, zot will auto-download a managed Pdfium binary on the first local PDF read on supported Windows, macOS, and glibc Linux targets.
4. Initialize config when you need writes or saved searches
If you plan to write notes, tags, collection membership, saved searches, or publication status:
zot config init --library-id <your library id> --api-key <your api key>
For a named profile:
zot config init --target-profile work --library-id <your library id> --api-key <your api key> --make-default
Ask for Zotero work in plain language
Once the skill is installed, the preferred interface is the user request, not the subcommand list.
- “Find papers tagged
transformerby Vaswani from 2017.” - “Pull the PDF annotations and child notes for
ATTN001.” - “Build me a workspace for LLM safety and import papers about reward hacking.”
- “Check whether this preprint has an official publication record now.”
- “Add a note and a
prioritytag to this item.”
Only after explicit permission for writes.
The skill routes these requests to the right library, item, collection, workspace, or sync workflow and decides when doctor is required first.
See the agent phrasing guide here:
- Agent Usage (EN): docs/en/skills/agent-usage.md
- Agent 用法(中文):docs/skills/agent-usage.md
Direct runtime reference
If you need to debug or drive the runtime manually, these are the usual starting points:
zot --json doctor
zot --json library search "reward hacking" --limit 10
zot --json library recent --count 10
zot --json item get ATTN001
zot --json item merge KEEP001 DUPE001
zot --json item annotation list --item-key ATTN001
zot --json workspace query llm-safety "What are the main failure modes?" --mode hybrid --limit 5
zot completions powershell
The runtime always returns the same top-level envelope:
{ "ok": true, "data": { "...": "..." }, "meta": { "...": "..." } }
{ "ok": false, "error": { "code": "...", "message": "...", "hint": "..." } }
Docs
The bilingual docs are organized around skill-first Zotero workflows, with CLI pages kept as reference:
- Skills overview (EN): docs/en/skills/overview.md
- Agent usage (EN): docs/en/skills/agent-usage.md
- Skill workflows (EN): docs/en/skills/workflows.md
- Getting started (EN): docs/en/guide/getting-started.md
- Migrating from ref\zotero-cli (EN): docs/en/guide/migrating-from-ref-zotero-cli.md
- CLI reference (EN): docs/en/cli/overview.md
- Skills 总览(中文):docs/skills/overview.md
- Agent 用法(中文):docs/skills/agent-usage.md
- 典型工作流(中文):docs/skills/workflows.md
- 快速开始(中文):docs/guide/getting-started.md
- 从 ref\zotero-cli 迁移(中文):docs/guide/migrating-from-ref-zotero-cli.md
- CLI 参考(中文):docs/cli/overview.md
Local preview:
just docs
Released docs are published to GitHub Pages via .github/workflows/deploy-docs.yml.
Current boundary
zot mcp serveis scaffolded and currently returnsmcp-not-implemented. For now, use the skill plus the runtime.- Local reads come from the Zotero data directory. Mutations go through the Zotero Web API only.
- Missing write credentials do not block local reads. They only block Zotero Web API writes.
- Annotation creation is PDF-first. It requires a local PDF, Pdfium support, and write credentials.
- Citation-key lookup prefers Better BibTeX support and falls back to compatible local parsing when possible.
- Legacy connector-style
search/fetchideas are intentionally mapped onto explicitlibrary,item,collection,workspace, andsyncworkflows.
If you need to override Pdfium resolution manually:
ZOT_PDFIUM_LIB_PATHorPDFIUM_LIB_PATHcan point to a compatible Pdfium library file or directory.ZOT_PDFIUM_CACHE_DIRcan override the base directory used for Zot-managed Pdfium downloads.
Verification
just ci
This runs cargo fmt --all --check, cargo check --workspace, cargo clippy --workspace --all-targets -- -D warnings, and cargo test --workspace.
Contributing
Issues, reproducible bug reports, and PRs are welcome. Read AGENTS.md first for the repo contract, then use the templates in .github/ISSUE_TEMPLATE and .github/PULL_REQUEST_TEMPLATE.md.
Before opening a PR:
- Run
just cilocally. - Update
docs/anddocs/en/if you change a user-facing workflow. - Keep
skills/zot/SKILL.mdaligned with the runtime behavior.
Acknowledgments
- Zotero — the open reference manager and data model this project builds on.
- Better BibTeX — citation-key workflows.
- Pdfium via
pdfium-render— PDF text and outline extraction. - Semantic Scholar, Scite, Unpaywall, Crossref, OA PMC — enrichment and open-access resolution.
License
MIT — research workflows should stay portable.