zotio

The trust-and-automation layer for Zotero

Docs: Get started · Commands · MCP server · Safe writes · Workflows

zotio gives humans, scripts, and MCP agents local-first search and auditing, preview-first writes, and bounded, provenance-tagged context for Zotero libraries.

Fast proof: check a bundled library before trying zotio on your own data.

brew install orgmentem/tap/zotio        # or grab a signed binary from Releases

zotio demo # bundled library: 34 classic papers, one genuinely retracted ZOTIO_DEMO=1 zotio --data-source local items retract-check # check every DOI against Retraction Watch data

KEY         STATUS      TYPE        NOTICE DOI                     DATE        SOURCE            TITLE

WAKE2235 correction correction 10.1016/s0140-6736(04)15715-2 2004-03-06 retraction-watch Ileal-Lymphoid-Nodular Hyperplasia, Non-Speci... WAKE2235 retracted retraction 10.1016/s0140-6736(10)60175-4 2010-02-06 retraction-watch Ileal-Lymphoid-Nodular Hyperplasia, Non-Speci... FAIR222U correction addendum 10.1038/s41597-019-0009-6 2019-03-19 publisher The FAIR Guiding Principles for Scientific Da... Checked 21 DOI-bearing items; 3 update notices flagged; 2 DOI(s) not registered with CrossRef.

That is the bundled library catching the retracted Wakefield 1998 MMR paper, with no Zotero install and no API key (the check queries Crossref live). zotio demo --reset deletes and re-seeds the demo library, restoring it to its original state. To remove it, delete demo.db and its -wal and -shm siblings at the path the demo prints (db_path in JSON output).

Zotero itself red-flags a retracted item when you open it, from the same Retraction Watch data. zotio adds what the desktop app does not: corrections and expressions of concern, a report across a whole library that scripts can consume, and an exit code CI can fail on.

Point it at your real library:

zotio init                                         # guided setup: detect Zotero, key, first sync, health check

zotio items retract-check # the same check, against your real library zotio library health --for citation --fail-on high # fit to cite? (exit 11 if not) zotio items bibcheck thesis.tex --fail-on-unknown # every \cite{} resolves? (exit 11 if not)

---

Why zotio

Zotero's GUI is great for reading and citing. It is painful the moment you need to *operate* on a library at scale: find every article missing a PDF, catch duplicate \cite{} keys before a submission, export a week of highlights, keep an Obsidian vault in sync, or hand an AI agent trustworthy context. Existing CLIs and pyzotero give you raw API access — then you write the glue, and you own the risk.

zotio provides that glue with these properties:

• Most reads are local. Point zotio at your running desktop app for keyless reads, or use a synced mirror offline. Web-only reads such as every items bibliography format need a Web API key.
• Writes are preview-first. Every mutation shows a plan before it touches anything. Gates cap blast radius; irreversible ops require an explicit opt-in; an append-only journal lets you undo the reversible ones.
• Context is bounded and provenance-tagged. Every result says where it came from and how fresh it is, so a human or an agent knows whether to trust it. zotio never calls an LLM; it assembles and budgets the context, then hands it to the model.

It is the tool you reach for when the GUI gets too manual: find the problems that bite downstream, fix them safely, ingest with review, and give agents a surface they can trust.

---

How it works

Most reads stay on your machine; Web-only reads such as items bibliography need a Web API key. Writes split by intent: creating a new item (with its attachments/PDFs) prefers the local desktop connector (localhost:23119, no key — the same channel the browser "Save to Zotero" button uses), while field edits, deletes, enrichment, tag ops, moves, and `collections` create/update route to the Zotero Web API and need a configured key. items new always needs a key to fetch its Web-only template, even on the connector route. The connector path is a preference: --via auto uses it only on a personal library with the desktop running, and falls back to the Web API otherwise (group libraries always go to the cloud). For attachments add on an existing item, --via connector is an explicit desktop route that still needs a Web API key to move the file to its target. Writes are preview-first; item update reads its version from the Web write target at apply time. Supported applied changes update an existing local mirror so a follow-up read can see them without another sync.

Run zotio doctor any time to see connectivity, cache freshness, and a writes: line telling you whether write-back is available or read-only.

---

The flagship: library health

One command that answers a real question — *"is this library fit for the next thing I'm going to do with it?"* — in place of six separate audits.

library health composes the checks that already exist (citekey conflicts, duplicates, missing metadata, tag drift, broken attachments) into one ranked, finding-typed report. You pick what "ready" means with --for:

$ zotio library health --for quick

Health: needs attention Scope: library · 846 top-level items (2103 mirrored rows) · source local · synced 1d ago · preset quick

High (13) [duplicate_candidates] doi="10.1002/bdm.2118" (2 items) [duplicate_candidates] title="Social psychology" (3 items) ... 11 more

Skipped (precondition unmet) broken_attachment_file — live check (needs Zotero desktop running); off by default. Fix: zotio library health --for quick --verify-files

Remediation plan (preview-first) duplicate_candidates — zotio items duplicates resolve --doi (preview first; add --yes after review)

Three properties make it suitable for gating:

• It gates CI. --fail-on critical|high|info|any|none exits `11` when the bar isn't met — drop it in a pre-submission hook. --require-fresh 24h exits `12` if your local mirror is stale.
• It reports what it could not check. A check that needs the desktop app (broken attachments) becomes a loud skip with a remedy. If that skip is gate-relevant, the run exits `9` (setup required) instead of passing.
• It points at the real fixer. Findings carry a recommended_action naming the exact existing command (items enrich, items duplicates resolve, tags audit fix). library health reports problems; the named commands fix them.

CI for your bibliography

--badge renders any health run as a shields.io endpoint JSON artifact — healthy green, findings yellow, gate-failure red, setup required orange:

# .github/workflows/bibliography.yml (excerpt)

• run: zotio sync
• run: zotio library health --for citation --fail-on high --badge > badge.json

exit 11 fails the job when the bar isn't met; badge.json says why

publish badge.json anywhere shields can reach (gh-pages, gist, artifact host), then:

https://img.shields.io/endpoint?url=https:// .github.io/ /badge.json

Your thesis or review repo gets a live bibliography | healthy badge — and a failing build the moment a citekey conflict or duplicate slips in. Add --check-retractions to extend the gate to retracted papers (Crossref's Retraction Watch data), and gate the manuscript itself with zotio items bibcheck paper.tex --fail-on-unknown. The zotio-action packages this — install, sync, gate, and diff against a baseline so it fails only on *new* problems (guide).

See it running for real: zotio's own docs deploy publishes a live badge off the maintainer's real Zotero library (workflow, guide).

---

Safe by default: the write engine

Mutation-envelope writes — items enrich, tags audit fix, items duplicates resolve, `items preprint-c