zoterios

A CLI tool to interact with your local Zotero library.

Prerequisites

• Python 3.13+
• Zotero 7+ running locally (default port 23119)

Installation

# with uv (recommended)
uv tool install zoterios

# or with pip
pip install zoterios

Quick Start

# Check connection
zoterios ping

# List recent papers
zoterios papers list

# Search papers
zoterios papers list --query "transformer" --tag "ML" --limit 10

# Get paper details
zoterios papers get ABCD1234

# Open a paper's PDF
zoterios papers pdf ABCD1234 --open

# Read a paper as markdown
zoterios papers markdown ABCD1234

Commands

ping

Test connection to the local Zotero instance.

papers

import-pdf options:

--title TEXT        Paper title (required)
-a, --author TEXT   Author name (repeatable)
--year TEXT         Publication year
--type TEXT         Item type: document (default), journalArticle,
                    conferencePaper, preprint, book, thesis, report
--journal TEXT      Journal / publication name
--abstract TEXT     Abstract
--doi TEXT          DOI
--url TEXT          URL
-t, --tag TEXT      Tag (repeatable)

Example:

zoterios papers import-pdf paper.pdf \
  --title "Attention Is All You Need" \
  -a "Ashish Vaswani" -a "Noam Shazeer" \
  --year 2017 --type conferencePaper \
  --journal "NeurIPS" -t "transformer"

arxiv

Example:

zoterios arxiv fetch 1706.03762
zoterios arxiv save 1706.03762

markdownit

Convert any supported file to markdown (PDF, DOCX, PPTX, HTML, etc.):

zoterios markdownit report.pdf
zoterios markdownit slides.pptx

Global Options

--base-url TEXT   Zotero API URL (default: http://localhost:23119)
--cache-dir TEXT  Cache directory (default: ~/.cache/zoterios)
--json            Output JSON for all commands

Configuration

Settings can be configured via environment variables (prefix ZOTERIOS_) or a .env file:

CLI flags (--base-url, --cache-dir) take priority over env vars.

License

MIT