Zotero Cli

Rule of thumb: Use zot search for quick metadata lookups. Use zot workspace query for deep content search over a curated set of papers (indexes metadata + PDF fulltext).

zot — Zotero CLI (Core Tool)

Search & Browse

zot --json search "transformer attention"
zot --json search "BERT" --collection "NLP"
zot --json list --collection "Machine Learning" --limit 10
zot --json read ITEMKEY
zot --json relate ITEMKEY

Notes & Tags

zot --json note ITEMKEY
zot note ITEMKEY --add "Key finding: ..."
zot --json tag ITEMKEY
zot tag ITEMKEY --add "important"
zot tag ITEMKEY --remove "to-read"

Citation Export

zot export ITEMKEY                    # BibTeX
zot export ITEMKEY --format csl-json  # CSL-JSON
zot export ITEMKEY --format ris       # RIS
zot export ITEMKEY --format json      # Raw JSON

# Formatted citation (copies to clipboard)
zot cite ITEMKEY                      # APA (default)
zot cite ITEMKEY --style nature       # Nature
zot cite ITEMKEY --style vancouver    # Vancouver

Item Management (Write Ops)

zot add --doi "10.1038/s41586-023-06139-9"
zot add --url "https://arxiv.org/abs/2301.00001"
zot add --from-file dois.txt              # Batch import (one DOI/URL per line)
zot add --pdf paper.pdf                   # Add from local PDF (auto-extract DOI)
zot --no-interaction delete ITEMKEY
zot update ITEMKEY --title "New Title"
zot update ITEMKEY --field volume=42 --field pages=1-10
zot attach ITEMKEY --file supplement.pdf

Collections

zot --json collection list
zot --json collection items COLLECTIONKEY
zot collection create "New Project"
zot collection move ITEMKEY COLLECTIONKEY
zot collection rename COLLECTIONKEY "New Name"
zot collection delete COLLECTIONKEY

Preprint Status Check

zot update-status                          # Check all arXiv/bioRxiv preprints (dry-run)
zot update-status --apply                  # Actually update Zotero metadata
zot update-status ITEMKEY                  # Check a single item
zot update-status --collection "NLP" --limit 20

Duplicates, Recent & Trash

zot --json duplicates                # Find duplicates (DOI + title matching)
zot --json duplicates --by title     # Title-only matching
zot --json recent --days 7           # Recently added items
zot --json recent --sort dateModified
zot --json trash list                # View trashed items
zot trash restore ITEMKEY            # Restore from trash

PDF & Summarization

zot --json pdf ITEMKEY
zot pdf ITEMKEY --pages 1-5
zot pdf ITEMKEY --annotations        # Extract PDF annotations
zot --json summarize ITEMKEY
zot summarize-all

Utilities

zot --json stats                     # Library statistics
zot open ITEMKEY                     # Open PDF in system viewer
zot open --url ITEMKEY               # Open URL/DOI in browser

Group Library

zot --library group:12345 search "query"    # Search in group library
zot --library group:12345 list              # List group library items

Workspaces (Topic-Based Paper Organization + RAG)

Workspaces are local collections of paper references for organizing research by topic. Each workspace stores item keys in a TOML file (~/.config/zot/workspaces/<name>.toml) — no Zotero API needed.

# Create and manage workspaces
zot workspace new llm-safety --description "LLM alignment and safety papers"
zot workspace add llm-safety KEY1 KEY2 KEY3
zot workspace remove llm-safety KEY1
zot workspace list                         # List all workspaces
zot --json workspace list                  # JSON output
zot workspace show llm-safety              # Show items with full metadata
zot workspace delete llm-safety --yes

# Bulk import from collection, tag, or search
zot workspace import llm-safety --collection "Alignment"
zot workspace import llm-safety --tag "safety"
zot workspace import llm-safety --search "RLHF"

# Search within workspace (metadata substring match)
zot workspace search "reward" --workspace llm-safety
zot --json workspace search "attention" --workspace llm-safety

# Export for AI consumption
zot workspace export llm-safety                       # Markdown (default)
zot workspace export llm-safety --format json         # JSON
zot workspace export llm-safety --format bibtex       # BibTeX

# Build RAG index (BM25 over metadata + PDF text)
zot workspace index llm-safety             # Incremental index
zot workspace index llm-safety --force     # Full rebuild

# Query workspace with natural language
zot workspace query "reward hacking" --workspace llm-safety
zot workspace query "RLHF methods" --workspace llm-safety --top-k 10
zot --json workspace query "attention" --workspace llm-safety

# Retrieval modes (auto selects hybrid if embeddings available)
zot workspace query "query" --workspace name --mode bm25      # Keyword only
zot workspace query "query" --workspace name --mode semantic   # Embeddings only
zot workspace query "query" --workspace name --mode hybrid     # BM25 + semantic fusion

Optional semantic search — configure an embedding endpoint (Jina AI default, 10M free tokens):

export ZOT_EMBEDDING_URL="https://api.jina.ai/v1/embeddings"
export ZOT_EMBEDDING_KEY="your-jina-api-key"
# Then re-index to generate embeddings:
zot workspace index llm-safety --force

Configuration

zot config init
zot config profile list
zot config profile set lab
zot config cache stats
zot config cache clear

Global Flags

Workflow Patterns

Pattern 1: Find and Read a Paper

# Step 1: Search
zot --json search "single cell RNA sequencing"

# Step 2: Read details
zot --json read K853PGUG

# Step 3: Full PDF text if needed
zot --json pdf K853PGUG

Pattern 2: Deep Content Search via Workspace RAG

# Step 1: Create workspace and add papers
zot workspace new drug-resistance --description "Cancer drug resistance mechanisms"
zot --json search "drug resistance cancer" --limit 20
zot workspace add drug-resistance KEY1 KEY2 KEY3

# Step 2: Build index (metadata + PDF fulltext)
zot workspace index drug-resistance

# Step 3: Query with natural language
zot --json workspace query "mechanisms of acquired resistance" --workspace drug-resistance --top-k 5

Pattern 3: AI-Powered Library Reorganization

# Step 1: Export all abstracts
zot --json summarize-all > abstracts.json

# Step 2: AI analyzes and generates classification plan
# Step 3: Create collections and move items
zot collection create "Category A"
zot collection move ITEMKEY COLLECTIONKEY

Pattern 4: Workspace RAG for Claude Code

# Step 1: Create a topic workspace
zot workspace new protein-folding --description "Protein structure prediction papers"

# Step 2: Add relevant papers
zot --json search "protein folding" --limit 20
zot workspace add protein-folding KEY1 KEY2 KEY3 KEY4

# Step 3: Build RAG index
zot workspace index protein-folding

# Step 4: Query and feed results to Claude Code
zot --json workspace query "AlphaFold architecture" --workspace protein-folding --top-k 5
# Paste JSON output into Claude Code conversation as context

Important Notes

• zot read operations work offline with zero config
• zot write operations need API credentials via zot config init
• zot update-status uses Semantic Scholar API; set S2_API_KEY env var for faster rate limits
• PDF cache — zot caches PDF extractions automatically
• Item keys are 8-character alphanumeric strings like K853PGUG
• Group libraries — use --library group:<id> with any command
• Workspaces — pure local TOML files, no API needed for basic operations; workspace index reads PDFs from Zotero storage
• Workspace RAG — BM25 always available (zero new deps); optional semantic search via embedding endpoint (ZOT_EMBEDDING_URL + ZOT_EMBEDDING_KEY, Jina AI default with 10M free tokens)