huntpdf

A Python-based CLI tool to fetch PDFs of arxiv, DOI, and PubMed articles.

Installation

pip install huntpdf
playwright install chromium  # one-time setup for browser fallback

Usage

huntpdf <query> [-o OUTPUT]

Where <query> can be:

Output is JSON:

{"status": "success", "pdf_path": "/absolute/path/to/file.pdf"}

Options

• -o, --output PATH — Save PDF to a specific path (default: auto-generated in current directory)

Supported URL patterns

• arxiv.org/abs/{id} and arxiv.org/pdf/{id}
• doi.org/{doi}
• pubmed.ncbi.nlm.nih.gov/{pmid}
• pmc.ncbi.nlm.nih.gov/articles/{PMCID}
• Direct PDF links (any URL serving application/pdf)
• Other URLs (attempted via headless browser fallback)

Download strategy

For each URL, huntpdf tries:

1. Direct HTTP download — fast streaming via httpx
2. Headless browser — Playwright-based fallback for JavaScript-rendered pages

For DOI lookups specifically, if the Unpaywall PDF URL fails (e.g. paywall), huntpdf queries the Semantic Scholar API for alternate open-access copies and tries existing resolvers (arXiv, PMC) with the discovered identifiers.

Environment variables

• UNPAYWALL_EMAIL (required for DOI lookups) — Your email address for Unpaywall API requests

Development

pip install -e ".[dev]"
pytest

Run only unit tests (skip integration tests that hit real APIs):

pytest -m "not integration"