Letterboxd CSV → Zotero import script (one-shot, idempotent)

A Python 3 script at ~/.hermes/scripts/letterboxd_csv_to_zotero.py created 2026-07-02. Reads a Letterboxd Pro data export (ratings.csv, optionally watched.csv), creates a "Films" collection in Zotero, and POSTs one film itemType per row.

2026-07-02 with the user's actual export (/Users/nathanmaxwell/.hermes/.hermes/desktop-attachments/ letterboxd-nateterrence-2026-07-02-03-33-utc.zip → extracted to /tmp/letterboxd-import/). Dry-run with --limit 5 produced the expected item payloads; type checking against the live Zotero schema (itemType=film, fields: title, abstractNote, distributor, place, date, genre, videoRecordingFormat, runningTime, DOI, citationKey) — confirmed via the /itemTypeFields?itemType=film endpoint.

~/.hermes/hermes-agent/venv/bin/python \ ~/.hermes/scripts/letterboxd_csv_to_zotero.py --dry-run # preview ~/.hermes/hermes-agent/venv/bin/python \ ~/.hermes/scripts/letterboxd_csv_to_zotero.py --limit 5 # import 5 rows ~/.hermes/hermes-agent/venv/bin/python \ ~/.hermes/scripts/letterboxd_csv_to_zotero.py # full import ~/.hermes/hermes-agent/venv/bin/python \ ~/.hermes/scripts/letterboxd_csv_to_zotero.py --include-watched # add seen-not-rated films too

The extra field is Zotero's standard catch-all for tag-style metadata (cited in the Zotero docs). The gbrain daemon's body-merge regex doesn't currently parse extra-field content, but the field is preserved in the compiled_truth markdown body so future parsers can read it.

How it's structured

What ships A Python 3 script at ~/.hermes/scripts/letterboxd_csv_to_zotero.py created 2026-07-02. Reads a Letterboxd Pro data export (ratings.csv,…
What ships Idempotent: re-running checks for existing items by title+year via the Zotero Web API's /items?q=...&itemType=film endpoint and skips dupl…
What it requires ZOTERO_API_KEY=<key with write access> ZOTERO_USER_ID=<numeric user ID>
What it requires Get the key at https://www.zotero.org/settings/keys/new with "Allow library access" = "All" and "Allow write access" = ON. The User ID is sh…
Usage ~/.hermes/hermes-agent/venv/bin/python \ ~/.hermes/scripts/letterboxd_csv_to_zotero.py --dry-run # preview ~/.hermes/hermes-agent/venv/bin…
Usage The "Films" collection is created on first run and reused thereafter.
… 8 more sections in the full essay