| name | zotero-cli |
| description | Use when user mentions papers, references, citations, Zotero, literature, bibliography, or needs to search, read, export, or organize documents. Handles all zot CLI operations including ranked search over Zotero collections. |
Zotero CLI Skill
zot is an all-in-one Zotero CLI: search, CRUD, PDF extraction, citation export, and ranked retrieval over collections. Local SQLite for reads, Zotero Web API for writes.
Quick Start
zot search "transformer attention"
zot --detail minimal search "transformer attention"
zot --detail full search "transformer attention"
zot --json read ABC123
zot export ABC123
zot --json search --ranked "RLHF" --collection my-collection
Critical Rules
- Always use
--json for programmatic processing (auto-enabled when stdout is not a TTY).
- Windows CJK encoding: On Windows with a CJK locale, recent
zot versions auto-reconfigure stdout to UTF-8. For older versions or subprocess calls, set PYTHONIOENCODING=utf-8. See references/windows-encoding.md.
- Write safety: Use
--dry-run to preview mutations. Pass --idempotency-key on retries.
- Large PDFs: Use
--outline first, then --section N (the heading number from the outline) to extract selectively. Avoid pulling full text when >20k chars.
- Find Full Text:
zot find-pdf KEY fetches paywalled PDFs but needs Zotero desktop running + the bridge plugin. One-time setup: zot bridge install. See references/commands.md.
- Canonical schema: Run
zot schema <cmd> for exhaustive flags, types, and safety tiers.
Routing Table
| User Intent | Command |
|---|
| Search metadata | zot --json search "query" |
| Read item detail | zot --json read KEY |
| Export BibTeX/RIS/JSON | zot export KEY --format bibtex |
| Formatted citation | zot cite KEY --style apa |
| Batch import DOIs | zot add --from-file dois.txt |
| Add single item | zot add --doi "10.1038/..." |
| Update metadata | zot update KEY --title "New" |
| Delete item | zot --no-interaction delete KEY |
| PDF full text | zot --json pdf KEY |
| PDF outline | zot --json pdf --outline KEY |
| PDF section | zot --json pdf --section N KEY |
| Local PDF path | zot attachment path KEY (first PDF; --all for appendix/supplementary too) |
| Fetch/attach missing PDF | zot find-pdf KEY (needs Zotero desktop + bridge) |
| Rename attachment files | zot rename KEY --dry-run (needs bridge; preview first) |
| Add journal metrics (IF/分区) | zot enrich KEY --set "JCR=Q1" or --from-map journals.toml |
| Set up find-pdf bridge | zot bridge install |
| Collection list | zot --json collection list |
| Collection items | zot --json collection items COLLKEY |
| Find duplicates | zot --json duplicates |
| Recent items | zot --json recent --days 7 |
| Library stats | zot --json stats |
| Collection create | zot collection create "NAME" |
Rule of thumb: zot search for quick metadata + full-text lookups. zot search --ranked for relevance-ranked deep search with scores and snippets, optionally scoped to a collection via --collection. zot ask when you need a citation-keyed evidence pack to write a grounded answer — it returns chunks tagged with their Zotero item key plus answer_instructions; zot does not call an LLM, so you synthesize and cite the answer from the evidence.
Global Flags
| Flag | Purpose |
|---|
--json | JSON output (always use for programmatic processing) |
--limit N | Limit results (default: 50) |
--detail minimal | Only key/title/authors/year — saves tokens |
--detail full | All fields |
--no-interaction | Suppress prompts (automation) |
--verbose | Debug output |
Key Facts
- Read ops work offline with zero config
- Write ops need API credentials (
zot config init)
- Item keys are 8-char alphanumeric strings (e.g.
K853PGUG)
- Non-TTY stdout auto-emits JSON envelope — agents never need explicit
--json
References
references/commands.md — Full command reference with examplesreferences/ranked-search.md — Ranked search and evidence packs over collectionsreferences/workflows.md — Common multi-step workflow patternsreferences/windows-encoding.md — Windows CJK encoding fix
