Paperful documentation

New here? paperful.app, then Walkthroughs. Four ways to wire it up: Example setups. Search order: How it works.

Paperful is a local workbench for a Zotero library you already keep. Open access first; campus EZProxy when you have it. Zotero is well tested. Mendeley and EndNote are seeking testers. You keep a folder copy on this machine and attach the PDFs you trust. Terms.

Clone the repo, then docker compose build and docker compose up → http://127.0.0.1:8765 (GUI). Docker (light / heavy packs). CLI: docker compose run --rm paperful …. Host CLI without Docker: pipx install paperful (or uv tool install / pip install); campus login and HTML PDF need paperful[browser] (releases). Fetch stance: legal and privacy. Contributors: uv. Stability: releases. Why this shape: Why Paperful.

Start here

• How it works
  • A fill, in order
  • Where it looks
  • Around a fill
  • Slowing down
  • Using your Scholar or library login
  • What you get back
• Walkthroughs
  • Common workflows
  • More playbooks
  • Prerequisites
• Example setups
  • 1. One collection, open access
  • 2. Same collection, plus the campus library
  • 3. A desk that can grow
  • 4. All-in workbench
  • Which file to copy
• First fill: missing PDFs onto disk
  • Outcome
  • Starting point
  • What you’ll do
  • Walkthrough
  • What to notice
  • You should now have…
  • CLI equivalent
  • Next
• Grow the library: topic search and people you follow
  • Outcome
  • Starting point
  • What you’ll do
  • Walkthrough
  • What to notice
  • You should now have…
  • CLI equivalent
  • Next
• Tidy a collection: lint, identifiers, duplicates
  • Outcome
  • Starting point
  • What you’ll do
  • Walkthrough
  • What to notice
  • You should now have…
  • CLI equivalent
  • Next
• Paperful workbench
  • Product framing
  • Shell chrome
  • Simple loop
  • Advanced surfaces
  • HTTP capability API (P0 + GUI)
  • Non-goals
  • Related docs
• Why Paperful
  • Five jobs
  • What is true today
  • Related
• Docker
  • What still runs on the host
  • Prerequisites
  • Quick start
  • Environment and override
  • Optional LLM, RAG, and browser-agent
  • Custom playbook packs
  • Run configs
  • After doctor is green
  • Common commands
  • Image contents
  • Sessions and attach
  • Usual path (uv)
• Zotero
  • Setup
  • Write authorization
  • Attachment modes
  • Ghosts and quota
  • Checklist
  • Identifiers
  • Scoping runs (Paperful)
  • What Paperful asks of the API
  • Local API vs web API
• Commands
  • Scope filters
  • Doctor
  • Dry-run
  • Agent channel (--format json and mcp)
  • Exits
  • Run summary
  • Output
• Firefox add-on
  • Why a browser extension
  • What the button does
  • Where files land
  • Install
• Workflows
  • Do not conflate
  • 1. The shell sequence
  • 2. Same chain, one process
  • 3. Save the slice
  • Precedence
  • Docker
  • 4. Deep collection pass (example template)
  • 5. Research pack (cited works → parents → PDFs)
  • 6. Field author packs (corpus frequency → author_site)
  • 7. Reachout (ask authors, do not fetch)
  • 8. All-in E2E (NBA throwaway)
  • What this is not
• Research pack playbook
  • Sequence
  • What to read on disk
  • Exits (same table as commands)
  • Out of this playbook
• Dedupe
  • Phases
  • Flags
  • Disk
  • Gaps
  • Not this command
• Configuration (config.toml)
  • Run configs (profiles)
  • Grey literature playbooks
  • LLM (optional, local-first)
  • Exclude / protect collections
  • Advanced
• Paperful architecture
  • Mirror first
  • Data flow
  • Disk artifacts
  • Library adapter
  • LLM layer (optional, local-first)
  • Identifiers and lint
  • PDF text
  • Circuit breaker
  • Sci-Hub and presets
  • Disk mirror vs cloud quota
  • Ghost attachments
  • Operator tooling
  • Report JSON (paperful.run_report.v1)
  • Run packs (paperful.pack.v1)
  • Run configs
  • Grey literature
  • Related docs
• Developer guide
  • The rule: mirror first
  • What a command gets
  • Rules for new code
  • Module map
  • The refresh
  • Disk schemas
  • Adding things
  • Tests
  • PyPI releases
• Quiet mirror (out/)
  • Roles
  • Item folder
  • What “quiet” means
  • History
  • Non-goals (near term)
  • Related
• Paperful terms
  • Ladder (staging → gate → library of record)
  • Mounts
• Releases and stability
  • Schema compatibility (1.0 contract)
  • Ladder
  • Optional LLM
  • What 1.0 includes
  • Known limits (1.0)

Using paperful

• Mendeley
  • Setup
  • What the API actually does
  • Paperful rules
  • Commands
• EndNote
  • Setup
  • Read path
  • Write path (import bundle)
  • Paperful rules
  • Commands
• Adapter SDK
  • What to implement
  • Promotion (all three, or it stays “seeking testers”)
  • Explicitly out
• Source routing and circuit breaker
  • OSF Preprints (demand check, no source yet)
  • HTML→PDF (web, news, blogs)
• Screen for problematic papers (PPS-based)
  • What it checks
  • CLI
  • Write-back (--apply)
  • Config
  • Attribution
• Systematic review
• Critique (local manuscript pack)
  • What it checks
  • CLI
  • Input formats
  • Review lanes (--lane / [critique].lanes)
  • Optional reviewers (--lane reviewers / --llm)
  • Optional adversary (--lane adversary)
  • Optional outline (--lane outline)
  • Optional claims (--lane claims)
  • Optional verify (--lane verify)
  • Optional MARG-S (--lane marg / --advanced)
  • Optional context (--lane context / --lane context-web)
  • Optional AI-text extra (--ai-model / [critique].ai_model)
  • House glossary (state/glossary/)
  • Optional Vale (--vale / [critique].vale)
  • Optional forensics (--forensics / [critique].forensics)
  • Workbench
  • Config
• Rewrite (apply a critique pack)
  • CLI
  • Areas
  • Config
  • Honesty
  • Workbench
  • See also
• Stuff (extra citations from the library)
  • CLI
  • Pack
  • Config
  • What this is not
  • Workbench
• Campus EZProxy
  • What EZProxy will try
  • 1. Find your library’s EZProxy base URL
  • 2. Put the URL in config.toml
  • 3. Log in (session vault)
  • 4. Verify the session
  • 5. Run (or retry) downloads
  • 6. When the session expires
  • Advanced: Netscape cookies.txt
  • Alternatives and limits
• Research operators
  • Unpaywall email
  • Campus acceptable use
  • Provenance
  • Wrong-work PDFs
  • What a fill is not
• Browser sessions (Scholar, EZProxy, publishers)
  • If Google says “This browser or app may not be secure”
  • If Chrome never opens / Chrome did not open a debug port
  • If CDP attach fails (Browser context management is not supported)
  • If you see Session not ready (Scholar)
• Sci-Hub
  • Coverage cutoff (~2021)
• Legal, fetch stance, and privacy
  • Fetch stance
  • Credentials and privacy
  • Sustainability note
• SerpApi (Google Scholar search)
  • When it can help
  • When it will not help
  • Setup
  • Order in a run
  • Caps (max_calls / --serpapi-max)
  • What Paperful does not do
• Camofox recover lane
  • When to use it
  • Setup
  • Behaviour
  • Privacy
  • Related
• GROBID sidecar
  • When to use it
  • Setup
  • Behaviour
• AI for notes and Ask: what is feasible
  • Two paths
  • Try it out vs library scale
  • Local models: pick by job, not by hype
  • Hosted models via LiteLLM
  • Cost order of magnitude (hosted)
  • Practical recipes
  • Privacy and grounding (unchanged)
  • See also
• Optional LLM: setup and verbs
  • 1. Install
  • 2. Configure
  • 3. Check
  • 4. Verbs
  • 5. Docker
  • 6. Troubleshooting
  • Related docs
• Ask your library: rag and ask
  • What it reads and writes
  • Coverage depends on the mirror
  • Install
  • Configure
  • Build the index
  • Search and ask
  • Check
  • Troubleshooting
  • Related docs
• Browser agent: local models (Ollama + browser-use)
  • How Paperful uses browser-use (not vanilla quickstart)
  • Recommended Ollama tags (by VRAM band)
  • Context, temperature, and Ollama tuning
  • Acceptance test (one page, your rights)
  • Deterministic paths beat the agent
  • LiteLLM / remote
  • References

Product

• How Paperful compares
• How Paperful compares — reference
• Snowball
• Author watch lists
• Co-author network
• Search Page
• Keepup (alert loop and what cites)
• BBNJ author-site + authorwatch (dogfood)
• E2E stack (topic + effort)
• E2E all-in: NBA (reference dogfood)
• Roadmap