zotero-cli

A full-featured command-line interface for your Zotero library — built for researchers, developers, and AI agents.

Search, write, export, import, and read PDFs from the terminal. Every command outputs clean JSON, making zotero-cli a natural tool for AI agents platforms (Claude Code, Codex, OpenClaw, etc.) to manage your reference library programmatically.

Built on pyzotero, the official Python client for the Zotero Web API, using the CLI-Anything plugin.

→ For AI agents: copy SKILL.md to your coding agent's skills directory to give it native Zotero support.

---

Features

• 📖 Full read/write access — create, update, trash, and delete items, collections, and tags via the Zotero Web API
• 🔌 Offline-first local mode — read metadata and extract PDF text directly from ~/Zotero/zotero.sqlite, no internet or API key required
• 🤖 AI agent-friendly — every command supports --json for structured, machine-readable output; designed to be called by Claude, Codex, and other coding agents
• 📥 BibTeX import/export — import .bib files into any collection; export to BibTeX, RIS, CSL-JSON, CSV, and more
• 💾 Collection backup — snapshot a collection (or its entire sub-collection tree) to local files in one command
• ↩️ Undo/redo — reversible operations with a persistent session stack
• 💬 Interactive REPL — run without arguments to enter a guided interactive session

---

Installation

Requires Python 3.10+

# Recommended: uv (fastest)
uv tool install git+https://github.com/yourname/zotero-cli

# Or: pip from source
git clone https://github.com/yourname/zotero-cli
cd zotero-cli
pip install -e .

Verify:

zotero --version

---

Configuration

Get your credentials from zotero.org/settings/keys:

• Create a new API key with Allow library access + Allow write access
• Your numeric user ID is shown at the top of the same page

zotero config setup    # enter API key and user ID
zotero config test     # verify connection

Offline commands (zotero local *) require no API key — they read directly from ~/Zotero/zotero.sqlite.

---

Quick Start

# Search your library
zotero search query "transformer attention"

# List recent items
zotero items list --limit 10

# Get full metadata
zotero items get ABCD1234

# Create a new reference
zotero items create -t journalArticle \
  --title "Attention Is All You Need" \
  --author "Vaswani, Ashish" --year 2017

# Export a collection to BibTeX
zotero export items -f bibtex -c COLL_KEY -o refs.bib

# Import a .bib file into a collection
zotero import bib refs.bib -c COLL_KEY

# Backup a collection and all sub-collections
zotero backup collection COLL_KEY -r

# Undo the last write operation
zotero session undo

---

Offline / Local Commands

No API key, no network, no Zotero running:

zotero local list                        # list items from SQLite
zotero local get ABCD1234                # full metadata + attachments
zotero local collections                 # list collections
zotero local count                       # total item count
zotero local pdf ABCD1234                # extract full PDF text
zotero local pdf ABCD1234 --pages 3      # first 3 pages only
zotero local pdf ABCD1234 --text-only    # plain text output
zotero local attachments ABCD1234        # list attachments with resolved paths

---

All Command Groups

Group	Commands
config	setup, show, test
items	list, get, children, create, update, trash, restore, delete, trash-list, template, types, fields, count
collections	list, get, create, update, delete, add-item, remove-item, count
tags	list, add, remove, delete
search	query, by-tag, in-collection
export	items, formats
import	bib
backup	collection
session	undo, redo, history, status, clear
local	list, get, collections, count, pdf, attachments

Use -h on any command for details: zotero items create -h

---

JSON Output

All commands support --json (pass before the subcommand):

zotero --json items list --limit 5
zotero --json local get ABCD1234
zotero --json import bib refs.bib --dry-run
zotero --json backup collection COLL_KEY

---

Dependencies

Package	Purpose
pyzotero	Zotero Web API client
click	CLI framework
prompt-toolkit	Interactive REPL
httpx	HTTP client (direct API calls)
bibtexparser	BibTeX parsing for import
pypdf	PDF text extraction

---

AI Agent Setup

SKILL.md tells coding agents (Claude Code, Codex, Cursor, etc.) when and how to invoke zotero-cli. Copy it to your agent's skills directory:

Claude Code

mkdir -p ~/.claude/skills/zotero
cp SKILL.md ~/.claude/skills/zotero/SKILL.md

Cursor / Windsurf / other agents — place SKILL.md in the .cursor/skills/ or equivalent directory your agent loads at startup. Refer to your agent's documentation for the exact path.

Once installed, the agent will automatically invoke zotero commands whenever you ask about your reference library, PDF content, BibTeX export, or citation management. See SKILL.md for the full command reference.