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.
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.
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.
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
# 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
# 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"}'
# 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
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 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
zotero session undo
zotero --json session status
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.
--json before the subcommand for structured output"ABCD1234")zotero local * when Zotero doesn't need to be running and no writes are needed — it's faster and works offlinezotero local pdf ITEM_KEY --text-only pipes clean text to stdout — ideal for feeding into summarization or QA taskszotero session status to confirm undo stack is healthyRun zotero <command> -h for any command's full options list.