Zotero Skill

Interact with Zotero personal or group libraries via the REST API v3.

Setup

Requires two environment variables:

ZOTERO_API_KEY   — Create at https://www.zotero.org/settings/keys/new
ZOTERO_USER_ID   — Found on the same page (numeric, not username)

For group libraries, set

ZOTERO_GROUP_ID

instead of

ZOTERO_USER_ID

Optional env var for CrossRef/Unpaywall polite pool (improves DOI lookup success rate):

CROSSREF_EMAIL   — Your email (optional; uses fallback if unset)

If credentials are missing, tell the user what's needed and link them to the key creation page.

CLI Script

All operations use

scripts/zotero.py

(Python 3, zero external dependencies).

python3 scripts/zotero.py <command> [options]

Commands

Command	Description	Example
`items`	List top-level items	`zotero.py items --limit 50`
`search`	Search by query	`zotero.py search "cognitive load"`
`get`	Full item details + attachments	`zotero.py get ITEMKEY`
`collections`	List all collections	`zotero.py collections`
`tags`	List all tags	`zotero.py tags`
`children`	List attachments/notes for item	`zotero.py children ITEMKEY`
`add-doi`	Add item by DOI (dedup enabled)	`zotero.py add-doi 10.1234/example`
`add-isbn`	Add item by ISBN (dedup enabled)	`zotero.py add-isbn 978-0-123456-78-9`
`add-pmid`	Add item by PubMed ID	`zotero.py add-pmid 12345678`
`delete`	Move items to trash (recoverable by default)	`zotero.py delete KEY1 KEY2 --yes`
`update`	Modify item metadata/tags	`zotero.py update KEY --add-tags "new"`
`export`	Export as BibTeX/RIS/CSL-JSON	`zotero.py export --format bibtex`
`batch-add`	Add multiple items from file	`zotero.py batch-add dois.txt --type doi`
`check-pdfs`	Report which items have/lack PDFs	`zotero.py check-pdfs`
`crossref`	Match citations vs library	`zotero.py crossref bibliography.txt`
`find-dois`	Find & add missing DOIs via CrossRef	`zotero.py find-dois --limit 10`
`fetch-pdfs`	Fetch open-access PDFs for items	`zotero.py fetch-pdfs --dry-run`

Global Flags

```
--json
```
— JSON output instead of human-readable (works with items, search, get)

Common Options

```
--limit N
```
— Max items to return (default 25)
```
--sort FIELD
```
— Sort by dateModified, title, creator, date
```
--direction asc|desc
```
— Sort direction
```
--collection KEY
```
— Filter by or add to collection
```
--type TYPE
```
— Filter by item type (journalArticle, book, conferencePaper, etc.)
```
--tags "tag1,tag2"
```
— Add tags when creating items
```
--force
```
— Skip duplicate detection on add commands

Workflows

Add a paper by DOI

python3 zotero.py add-doi "10.1093/jamia/ocaa037" --tags "review"
# Warns if already in library. Use --force to override.

Duplicate detection: translates DOI to metadata, searches library by first author, compares DOI fields.

Bulk add from a file

# One identifier per line, # for comments
python3 zotero.py batch-add dois.txt --type doi --tags "imported"

Skips duplicates. Reports summary: added/skipped/failed.

Export bibliography

python3 zotero.py export --format bibtex --output refs.bib
python3 zotero.py export --format csljson --collection COLLKEY

Update tags/metadata

python3 zotero.py update ITEMKEY --add-tags "important" --remove-tags "unread"
python3 zotero.py update ITEMKEY --title "Corrected Title" --date "2024"
python3 zotero.py update ITEMKEY --doi "10.1234/example"
python3 zotero.py update ITEMKEY --url "https://example.com/paper"
python3 zotero.py update ITEMKEY --add-collection COLLKEY

Delete items

python3 zotero.py delete KEY1 KEY2 --yes           # Trash (recoverable, default)
python3 zotero.py delete KEY1 --permanent --yes    # Permanent delete

Cross-reference citations

python3 zotero.py crossref my-paper.txt

Extracts

Author (Year)

patterns from text and matches against library.

Find missing DOIs

# Dry run (default) — show matches without writing anything
python3 zotero.py find-dois --limit 20
Actually write DOIs to Zotero
python3 zotero.py find-dois --apply
Filter by collection

python3 zotero.py find-dois --collection COLLKEY --apply

Scans journalArticle and conferencePaper items missing DOIs, queries CrossRef, and matches by title similarity (>85%), exact year, and first author last name. Dry run by default — use

--apply

to write. Only patches the DOI field; never touches other metadata. 1s delay between CrossRef requests (polite pool with mailto).

Fetch open-access PDFs

# Dry run — show which PDFs are available and from where
python3 zotero.py fetch-pdfs --dry-run --limit 10
Fetch and attach as linked URLs (no storage quota used)
python3 zotero.py fetch-pdfs --limit 20
Also save PDFs locally
python3 zotero.py fetch-pdfs --download-dir ./pdfs
Upload to Zotero storage instead of linked URL
python3 zotero.py fetch-pdfs --upload --limit 10
Only try specific sources

python3 zotero.py fetch-pdfs --sources unpaywall,semanticscholar

Tries three legal OA sources in order: Unpaywall → Semantic Scholar → DOI content negotiation. By default creates linked URL attachments (no Zotero storage quota needed). Use

--upload

for full S3 upload to Zotero storage. Use

--download-dir

to also save PDFs locally.

Sources:

unpaywall

semanticscholar

doi

(default: all three)

Rate limits: 1s between Unpaywall/Semantic Scholar requests, 2s between DOI requests.

Scripting with JSON

python3 zotero.py --json items --limit 100 | jq '.items[].DOI'
python3 zotero.py --json get ITEMKEY | jq '.title'

Notes

Zero dependencies — Python 3 stdlib only (urllib, json, argparse)
Write operations require an API key with write permissions
If Zotero translation server is down (503), DOI lookups fall back to CrossRef
Input validation: DOIs must be
```
10.xxxx/...
```
format. Item keys are 8-char alphanumeric (e.g.,
```
VNPN6FHT
```
). ISBNs must be valid checksums.
```
check-pdfs
```
fetches all items; for large libraries (500+), this may be slow
```
fetch-pdfs
```
also processes all items — use
```
--collection
```
to scope for large libraries
Rate limits are generous; batch-add includes 1s delay between items
For common errors and troubleshooting, see references/troubleshooting.md

Zotero

AI Skill Market Insights

Be Part of the 0+ Developer Community

Zotero Skill

Setup

CLI Script

Commands

Global Flags

Common Options

Workflows

Add a paper by DOI

Bulk add from a file

Export bibliography

Update tags/metadata

Delete items

Cross-reference citations

Find missing DOIs

Actually write DOIs to Zotero

Filter by collection

Fetch open-access PDFs

Fetch and attach as linked URLs (no storage quota used)

Also save PDFs locally

Upload to Zotero storage instead of linked URL

Only try specific sources

Scripting with JSON

Notes

Quick Start

Manual Installation

TEAR & SHARE

Tags

writing-plans

executing-plans

plan-ceo-review

Office Automation

Todo Manager

Channels

Learn

Compare

Company