zotio

zotio is a command-line tool and MCP server positioned as a trust-and-automation layer for Zotero reference libraries. It targets users who need to operate on a library at scale rather than through the desktop GUI: finding missing PDFs, catching duplicate citation keys before submission, exporting annotations, syncing a notes vault, or supplying bounded context to AI agents. Architecture and data access Reads are local: zotio talks to the running Zotero desktop API on localhost and a synced SQLite mirror, requiring no API key and working offline against a synced copy. Writes are split by intent. Creating a new item with attachments prefers the local desktop connector (the same channel used by the browser "Save to Zotero" button), while field edits, deletes, enrichment, tag operations, moves, and collection create/update route to the Zotero Web API and need a configured key. The connector path is described as a preference, not a guarantee: automatic routing uses it only for a personal library with the desktop running, falling back to the Web API otherwise, and group libraries always go to the cloud. External services referenced for enrichment and import include CrossRef, OpenAlex, Semantic Scholar, Unpaywall, and OpenCitations. A doctor command reports connectivity, cache freshness, and whether write-back is available. Write safety All write commands share one mutation envelope. Preview is the default; --yes applies and --dry-run always wins. Agent mode sets JSON and non-interactive defaults but does not auto-apply writes. Gates cap blast radius: --max-changes defaults to 500 (50 under agent mode), and irreversible operations such as merge, permanent delete, and empty-trash require an explicit --allow-destructive flag. Applied writes are replayed into the local mirror so a follow-up read sees the change without another sync. Every applied run is recorded in an append-only journal, and journal undo reverses reversible operations (tag renames, collection membership, creates) while refusing merges, deletions, and field overwrites. Library health and CI The flagship library health command composes existing checks (citekey conflicts, duplicates, missing metadata, tag drift, broken attachments) into one ranked, finding-typed report. A --for flag selects a preset: quick, citation, systematic-review, vault, or all. Findings carry a recommended_action naming the command that fixes them. The command supports CI gating with --fail-on, exiting 11 when the bar is not met, and --require-fresh, exiting 12 on a stale mirror. Checks that need the desktop app become loud skips with remedies rather than silently disappearing, and a gate-relevant skip exits 9. A --badge option renders a shields.io endpoint JSON artifact. A companion GitHub Action packages install, sync, gate, and baseline diffing. Other capabilities Retraction checking validates DOIs against Crossref's Retraction Watch data, covering retractions, expressions of concern, and corrections. Collection gap analysis ranks frequently cited papers missing from a library. Bibliography checking parses LaTeX or pandoc citations and flags unknown or ambiguous keys. Tag auditing groups case and variant duplicates with ready-to-run merge commands. Library statistics, item audits, duplicate detection, and citekey conflict detection are included. Reading and synthesis features include bounded summarize bundles for LLM handoff (zotio itself does not call a model), annotation export and search, a reading-list lifecycle, note templates, deep links, and a year-in-review with shareable SVG cards. Enrichment fills missing DOIs, abstracts, and citation fields from external providers and attaches open-access PDFs, recording provenance in the Extra field. Preprint checking upgrades arXiv records to published journal DOIs. Export options include CSL-JSON, BibTeX, BibLaTeX, RIS, and a resumable JSONL snapshot with a content lockfile. Sync, watch, and tail keep the mirror fresh, and schema drift detects changes after Zotero upgrades. Import and vault workflows Bulk import runs through scan, resolve, and apply stages with an editable JSON manifest as the human review checkpoint. Vault sync keeps an Obsidian or Logseq vault in step with Zotero in both directions, using a managed region and a user prose region, with fast-forward-only write-back and reviewable conflict artifacts instead of silent merges. Agent integration An --agent flag provides JSON, compact, non-interactive output. A capabilities command exposes a registry of commands tagged with operation, data sources, write target, destructiveness, and preconditions. An agent-context command describes the CLI, a which command resolves natural-language queries to commands, and envelopes and exit codes are documented as stable contracts. An MCP server binary is distributed alongside the CLI. Distribution Installation is available via Homebrew on macOS and Linux, GitHub release packages for deb, rpm, and apk, and WinGet or Scoop on Windows. The CLI, an agent skill, and the MCP server can be installed independently. The project is MIT licensed and written in Go.