OrgMentem/zotio

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.
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 the demo.db file whose path the demo report prints as db_path.
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:**
---
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:
- **Reads are local and free.** Point zotio at your running desktop app: no API key and no cloud round-trip, and it works offline against a synced mirror.
- **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
Reads stay on your machine. 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. 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.
| Plane | Backend | Needs a key? |
|---|---|---|
| **Read** | Local Zotero API (localhost:23119) + synced SQLite mirror | No |
| **Write — new item** | Local desktop connector (localhost:23119) when personal + desktop up; else Web API. New items, attachments, PDFs. | No (connector path) |
| **Write — other items and vault notes** | Zotero Web API (api.zotero.org) — edits, deletes, enrich, tags, moves, collections create/update, vault write-back | Yes — configured once |
| **External** | CrossRef · OpenAlex · Semantic Scholar · Unpaywall · OpenCitations | No (feeds enrich/import) |
| **Local-only** | Files, desktop launch, vault file sync, introspection | No |
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:
| --for | Prepares for | Checks |
|---|---|---|
| quick *(default)* | anything obviously broken | citekey conflicts, duplicates, broken attachments |