zotero-cli

Zotero from the shell

zotero-cli reaches a Zotero library directly. Prefer it over the Zotero MCP server when you have shell access: the MCP server's tool schemas cost ~14k tokens of context on every request whether or not you use them, while this costs only what you actually run.

Check it is set up before the first real call:

zotero-cli config          # prints the resolved Zotero settings

If that fails, Zotero is not reachable. Local mode needs the Zotero desktop app running with its local API enabled; web mode needs ZOTERO_API_KEY and ZOTERO_LIBRARY_ID. Say so rather than guessing at library contents.

Always pass --json when you will read the output

Default output is markdown for humans. --json gives you one object per invocation with a stable shape, so you never parse prose:

{"ok": true, "command": "search", "schema": 1, "data": {...}}
{"ok": false, "command": "search", "schema": 1, "error": {"message": "...", "code": "..."}}

Both go to stdout; [INFO]/[WARN] diagnostics go to stderr. Check ok before using data. Run zotero-cli --json-schema for the full contract.

The core loop

Almost every task is: find keys → act on keys. Item keys are 8 characters and are the currency of every command.

# 1. find - use --detail keys_only to keep the result small while browsing
zotero-cli --json search "attention mechanisms" --limit 10 --detail keys_only

# 2. act - metadata, full text, or a page range
zotero-cli --json get metadata ABCD1234
zotero-cli --json get fulltext ABCD1234
zotero-cli --json read ABCD1234 --start-page 3 --end-page 8

Pipe keys straight into the next call:

zotero-cli --json search "diffusion models" --limit 5 --detail keys_only \
  | jq -r '.data.items[].key' \
  | while read -r key; do zotero-cli --json get metadata "$key"; done

Choosing a search mode

Mode	Use it for	Command
items (default)	a title, author or phrase you know	search "Vaswani attention"
semantic	a topic or idea, no exact wording	search --mode semantic "why transformers scale"
tag	items you filed under a tag	search --mode tag "to-read,important"
advanced	structured field conditions	search --mode advanced --conditions '[...]'
citekey	a BibTeX citation key	search --mode citekey smith2020
notes	text inside your notes, not item fields	search --mode notes "research question"