paperful

paperful

Not affiliated with paperful.io. Local Compose sidecar, not a document service.

Clean the library. Find the PDFs. Keep a mirror.

Local Zotero sidecar. Open access first, campus access when you have it. The mirror is a folder on this machine, not a sync service. Not every paywalled paper comes back.

Zotero is well tested. Mendeley and EndNote are seeking testers. Clone and Compose — no docker pull, no pip. 0.9.0.

See how it works Install

Three moves

Five jobs sit under these: library, find, completeness, mirror, control. snowball grows the library. run fills PDFs already in it. Sci-Hub stays off until you opt in. The PDF keeps a stamp (paperful oa:unpaywall). The item also gets a readable line, such as “Free copy from Unpaywall.”

1. Build on this machine

git clone, then docker compose build. There is no published image and no PyPI package. Zotero stays on the host. Zotero 10+ attaches; 7–9 still saves PDFs to disk.

2. Doctor, then a dry-run

docker compose run --rm paperful doctor
docker compose run --rm paperful run -C interesting --preset oa --dry-run

No campus login: --preset oa. Campus EZProxy: --preset eoi, after uv run paperful session login ezproxy on the host. Empty email with Unpaywall in sources is a red doctor row.

3. What this is not

Not paperful.io. Not a sync service. Not a GUI. Not OCR. Not every paywall. Scholar and Sci-Hub are opt-in. Mendeley and EndNote are seeking testers, not a proven switch.

What can I do with it?

  • Tidy a collection: identifiers, duplicates, then a summary if you want one
  • Find PDFs that open access, campus access, and your playbooks can reach
  • Grow the library from a keyword, a DOI, or an ORCID, behind a gate
  • Snapshot the library to disk and restore only missing items
  • Hand the mirror to another tool as RIS, BibTeX, or EndNote XML
  • Use campus EZProxy without storing your password
  • Leave Scholar, Sci-Hub, and the local model off until you opt in

Walkthrough: commands · dedupe. Not sure if this is the right tool? why · comparison · architecture.

On your machine

paperful is a local CLI. The catalogue is read through an adapter (Zotero’s local API is the one that is well tested). Session cookies stay under state/sessions/. Sci-Hub stays off until you add it to sources or pass --scihub. The mirror under out/ is yours to copy.

From a checkout to a filled collection

  1. Copy config.minimal.toml, set email, then run paperful doctor. No campus access: --preset oa.
  2. List collections with “No PDF” counts: paperful collections.
  3. Dry-run a collection, then fetch and attach.
  4. Optionally log in to EZProxy or Scholar before a big run.

Commands · Config · EZProxy · Sessions

Install

Build it on this machine. 0.x · build locally · no PyPI. Zotero stays on the host, with the local API enabled. 

git clone https://github.com/glen-w/Paperful.git
cd Paperful
cp .env.example .env
cp config.minimal.toml config.toml
docker compose build
docker compose run --rm paperful doctor
docker compose run --rm paperful run --collection interesting --preset oa --dry-run
# campus: --preset eoi, after uv run paperful session login ezproxy on the host

Tagged v0.9 is clone and build. There is no docker pull and no pip install paperful. Docker is the operator path. Zotero 10+ attaches; Zotero setup. Headed session login uses uv on the host. Full guide: /guide/.

Details: Documentation · 0.x / 1.0 · README