Skip to content
zotio

The trust-and-automation layer for Zotero

Local-first search and auditing, preview-first writes, and bounded, provenance-tagged context for humans, scripts, and MCP agents.

Get started Command reference

zotio is the trust-and-automation layer for Zotero: local-first search and auditing, preview-first Web API writes for safe change, and bounded, provenance-tagged context for humans, scripts, and MCP agents. Use it to prove a library is ready, fix it safely, ingest material with review, or give agents and vaults trustworthy context.

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. attachments add --via connector is an opt-in desktop route for an existing item; it still needs a key to re-parent the attachment through the Web API. Writes are preview-first. Item updates read their version precondition from the Web API at apply time, and supported applied changes update an existing local mirror.

zotio hybrid routing architecture Hero diagram showing zotio routing reads locally without an API key, writes to Zotero Web API with a key, external metadata providers, local-only desktop commands, local version reads before writes, and replay into the SQLite mirror. zotio hybrid routing Local-fast reads, key-gated cloud writes, and an immediately refreshed local mirror. READ WRITE EXTERNAL LOCAL-only Semantic colors are shared across README diagrams. READ plane Local-first Local Zotero API :23119 Zotero desktop running items list/get collections annotations fulltext Local SQLite mirror Synced cache for compound reads search items audit stats Desktop connector New-item create path create items · attachments · PDFs prefers local · else Web API ▸local reads/creates need no key · cloud writes do CLOUD write path Zotero Web API api.zotero.org Auto-routed mutation target items update/delete/move enrich · tags audit fix collections create/update vault push · journal undo LOCAL-only plane Files · desktop · introspection vault sync items open doctor capabilities EXTERNAL plane Metadata providers CrossRef · OpenAlex Semantic Scholar Unpaywall · OpenCitations zotio routing + safety layer one CLI surface reads new items writes replay → mirror enrich · import local ops
Plane Backend Needs a key?
Read Local Zotero API (localhost:23119) + synced SQLite mirror No
Write — new item Local desktop connector when personal + desktop up; else Web API No (connector path)
Write — everything else Zotero Web API (api.zotero.org) — edits, deletes, enrich, tags, moves Yes — configured once
External CrossRef · OpenAlex · Semantic Scholar · Unpaywall · OpenCitations No (feeds enrich/import)
Local-only Files, desktop launch, vault file sync, introspection No
Vault push / resolve --keep-vault Zotero Web API note write-back Yes — configured once
Vault pull / resolve --keep-remote Local vault file writes; Web API note reads Yes — configured once

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

Quickstart

zotio doctor                       # verify Zotero is running and reachable
zotio sync                         # mirror your library to local SQLite
zotio items retract-check          # check every DOI against Crossref's Retraction Watch data
zotio library health --for citation --fail-on high   # fit to cite? (exit 11 if not)
zotio items bibcheck paper.tex --fail-on-unknown     # every \cite{} resolves? (exit 11 if not)
zotio search 'automation trust' --data-source local --json

No Zotero yet? zotio demo seeds a bundled sample library — 34 classic papers, one genuinely retracted. Local checks (retract-check, library health, bibcheck, search) then run with no desktop app and no API key under ZOTIO_DEMO=1 and --data-source local; doctor and sync still need the real desktop. ZOTIO_DEMO=1 zotio --data-source local items retract-check catches the retracted paper on the spot:

zotio demo tour

New here? Install the CLI, then authenticate if you need writes.

Missing PDFs?

If your library has items without PDFs, papio finds and downloads validated, provenance-tracked PDFs from open access and your own institutional subscriptions through your normal browser, then hands them to zotio for preview-first import.

Where to go next