Using riszotto
CLI for searching, reading, and exporting papers from Zotero. Run via riszotto <command>. Requires Zotero desktop running with local API enabled.
If riszotto is not found, instruct the user to install it: uv tool install riszotto (or uv tool install "riszotto[semantic]" for semantic search support).
Default: personal library. Use -L "Name" for groups, -A for all libraries. Discover with riszotto libraries.
Dos and Don'ts
Do:
- Run
riszotto search "query"directly — output is a readable table - Read the table output as-is — keys, dates, authors, and titles are all there
- Use
-l/--limitto control result count - Combine filters:
--author,--tag,--full-textto narrow results - Run multiple searches as separate commands
Don't:
- Pipe riszotto output through
python3 -c "import sys,json;..."— the table is already human-readable - Use
--format jsonunless you have a specific programmatic need (you almost never do) - Use
2>/dev/nullto suppress stderr — let errors surface so you can act on them - Truncate titles manually with
[:80]— the table already truncates - Parse table output with scripts — if you truly need structured data, use
--format json, but question why first - Chain multiple searches in a single shell command with
echo "---"separators
Quick Reference
| Task | Command |
|---|---|
| List libraries | riszotto libraries |
| Search keywords | riszotto search "query" |
| Search all libraries | riszotto search -A "query" |
| Search group library | riszotto search -L "Group" "query" |
| Search all fields | riszotto search --full-text "query" |
| Semantic search | riszotto search --semantic "query" |
| Filter by author | riszotto search "topic" --author "Name" |
| Fuzzy author match | riszotto search "topic" --author "Name" --fuzzy |
| Filter by tag | riszotto search "topic" --tag "tag" |
| Read paper | riszotto show <KEY> |
| Search within PDF | riszotto show <KEY> --search "term" |
| Export BibTeX | riszotto export <KEY> |
| Collections | riszotto collections |
| Recent papers | riszotto recent |
| Build semantic index | riszotto index |
| JSON output | riszotto search "query" --format json |
Search Strategy
Follow this cascade when searching:
- Keyword search (default) — fast, precise for known titles/authors
--full-text— if 0 results, retry (searches all metadata fields)--semantic— for natural language queries; requiresindexbuilt first-A— search across all libraries at once
Tips:
- Fewer terms = more hits (keyword mode uses AND logic)
--author "name"handles diacritics automatically ("schafer" matches "Schäfer")--fuzzywith--authorfor uncertain spelling (Levenshtein distance <= 2)- Check
librariesoutput forIndexedcolumn before using--semantic
Common Mistakes
- Zotero not running: Start Zotero desktop with local API enabled
- Semantic without index: Run
riszotto indexfirst (per library) showneeds parent key, not attachment key; requires locally synced PDFs for group libraries- Flag conflict:
-L=--library,-l=--limit,-f=--format
Run riszotto <command> --help for full options.