convez.ai
Skill
bahayonghang

zotero-cli

bahayonghang/zotero-cli

Ver no GitHub
InicialPluginScore · de 0 a 100

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-cli

1 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

Estrelas
4
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
1.0.0
Issues abertas
0
Contribuidores
1

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.

License: MIT Rust MSRV Platform Zotero Docs Agent-native PRs welcome

English · 简体中文 · Docs (EN) · 文档(中文)


What this repo is really for

zot has two layers:

  • skills/zot/SKILL.md is 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 zot binary 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.sqlite plus attachment files under storage/.
  • 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 wantWhat the zot skill can surface
Find the right sourceSearch by query, tag, creator, year, collection, citation key, library, or feed
Read the evidenceReturn item metadata, child items, citations, PDF text, outline, notes, and annotations
Build a working setCreate a topic workspace, import matching papers, index it, and query it
Reuse full-library contextBuild a library semantic index and run BM25 / semantic / hybrid retrieval
Update the library safelyAdd notes, tags, collection membership, imports, duplicate merges, and status sync with explicit permission
Keep the agent honestRun 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 transformer by 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 priority tag 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:


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:

Local preview:

just docs

Released docs are published to GitHub Pages via .github/workflows/deploy-docs.yml.


Current boundary

  • zot mcp serve is scaffolded and currently returns mcp-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 / fetch ideas are intentionally mapped onto explicit library, item, collection, workspace, and sync workflows.

If you need to override Pdfium resolution manually:

  • ZOT_PDFIUM_LIB_PATH or PDFIUM_LIB_PATH can point to a compatible Pdfium library file or directory.
  • ZOT_PDFIUM_CACHE_DIR can 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:

  1. Run just ci locally.
  2. Update docs/ and docs/en/ if you change a user-facing workflow.
  3. Keep skills/zot/SKILL.md aligned with the runtime behavior.

Acknowledgments


License

MIT — research workflows should stay portable.

Ver o original no GitHub

Bom para

Relacionados