zotero

name

zotero

description

Manage a Zotero reference library using the `zotero` CLI. Use this skill whenever the user wants to interact with their Zotero library — searching references, adding or updating items, importing BibTeX, exporting citations, reading PDF content, managing collections or tags, or backing up references. Also use this skill when an agent needs to retrieve paper metadata or full text for downstream tasks like writing, literature review, or citation generation. Trigger on phrases like "my Zotero library", "find papers in Zotero", "add this to Zotero", "export BibTeX", "read this PDF from Zotero", "import references", "backup my collection", or any request involving reference management.

Zotero CLI Skill

This skill lets you manage a Zotero library through the zotero command-line tool. All commands output structured JSON when called with --json, making results easy to parse and pass to subsequent steps.

Before you start

Check the tool is available and configured:

which zotero && zotero config test

If config test fails, the user needs to run zotero config setup with their API key from zotero.org/settings/keys.

For offline/local commands (zotero local *) no API key is needed — they read directly from ~/Zotero/zotero.sqlite.

---

Core patterns

Search and retrieve

zotero --json search query "deep learning transformers" --limit 10
zotero --json items list --limit 25
zotero --json items list --type journalArticle --collection COLL_KEY
zotero --json items get ITEM_KEY

Read PDF text (offline, no API key)

# Extract full text
zotero local pdf ITEM_KEY --text-only

# First N pages only
zotero local pdf ITEM_KEY --pages 5 --text-only

# Full metadata + PDF in JSON
zotero --json local pdf ITEM_KEY

Add and update references

# Create a new item
zotero --json items create -t journalArticle \
  --title "Paper Title" --author "Last, First" \
  --year 2024 --doi 10.xxxx/xxxxx --journal "Nature"

# Supported types: journalArticle, book, bookSection, conferencePaper,
#                  thesis, report, webpage, patent, manuscript

# Update fields
zotero --json items update ITEM_KEY --title "New Title" --year 2025
zotero --json items update ITEM_KEY --fields-json '{"language":"en"}'

Import / export BibTeX

# Preview what would be imported (no upload)
zotero --json import bib refs.bib --dry-run

# Import into library (optionally into a collection)
zotero --json import bib refs.bib --collection COLL_KEY

# Export
zotero export items -f bibtex -c COLL_KEY -o refs.bib
zotero export items -f ris ITEM_KEY1 ITEM_KEY2

Collections and tags

zotero --json collections list
zotero --json collections list --all          # recursive
zotero --json collections create -n "Name"
zotero --json collections add-item COLL_KEY ITEM_KEY

zotero --json tags list
zotero tags add ITEM_KEY "tag1" "tag2"

Backup a collection

# Backup with sub-collections, default formats (bibtex + csljson)
zotero --json backup collection COLL_KEY --recursive

# Custom formats and output path
zotero --json backup collection COLL_KEY \
  --format bibtex --format ris --output ~/backups/zotero

Undo a write operation

zotero session undo
zotero --json session status

---

Key response shapes

Item list — array of Zotero item objects, each with key, version, data (title, creators, date, etc.)

Import result:

{ "parsed": 42, "imported": 42, "failed": 0, "keys": ["ABCD1234", ...], "errors": [] }

Backup result:

{ "path": "/Users/.../zotero-backups/Name_20260315", "collections_backed_up": 5, "files_written": 10 }

Errors are returned as {"error": "..."} with a non-zero exit code.

---

Tips for agents

• Always pass --json before the subcommand for structured output
• Item and collection keys are 8-character strings (e.g. "ABCD1234")
• Use zotero local * when Zotero doesn't need to be running and no writes are needed — it's faster and works offline
• zotero local pdf ITEM_KEY --text-only pipes clean text to stdout — ideal for feeding into summarization or QA tasks
• After bulk writes, run zotero session status to confirm undo stack is healthy

Full options

Run zotero <command> -h for any command's full options list.