opencite 0.5.4

Academic literature search, citation management, and PDF retrieval CLI

OpenCite

Academic literature search, citation management, and PDF retrieval CLI.

Searches Semantic Scholar, OpenAlex, PubMed, arXiv, bioRxiv, medRxiv, OSF Preprints (PsyArXiv/SocArXiv/...), Zenodo, Figshare, CrossRef, and CORE in parallel, deduplicates results, and supports BibTeX output, citation graph traversal, PDF retrieval (with HTML full-text shortcuts for arXiv ar5iv and bioRxiv .full), batch downloads, and PDF-to-markdown conversion.

Quick Start

Install and set up your API keys:

uv pip install opencite                # or: pip install opencite
opencite config init                   # creates ~/.opencite/config.toml

Add your API keys to ~/.opencite/config.toml or export them as environment variables:

export SEMANTIC_SCHOLAR_API_KEY=your_key
export PUBMED_API_KEY=your_key
export OPENALEX_API_KEY=your_key

Start searching:

opencite search "transformer attention mechanism"
opencite lookup 10.1038/nature12345
opencite canonical "deep learning" --min-citations 500
opencite cite 10.1038/nature12345
opencite pdf 10.1038/nature12345 -o paper.pdf --convert

[!NOTE] AI-agent skill: The opencite skill ships in neuromechanist/research-skills alongside the other research-tooling skills (figures, grant, manuscript, neuroinformatics, presentation, project). It works with Claude Code, Codex / OpenAI, and VS Code GitHub Copilot. For Claude Code, run /plugin marketplace add neuromechanist/research-skills, then open /plugin and install opencite from the research-skills marketplace; see the research-skills README for setup with the other agents.

[!TIP] PDF conversion requires pip install 'opencite[pdf]'. If MISTRAL_API_KEY is set, markit-mistral is used (better for math/complex layouts); otherwise markitdown (free, local).

Commands

search - Find papers

opencite search "query" [--max N] [--source all|openalex|s2|pubmed]
    [--year-from YYYY] [--year-to YYYY] [--oa-only]
    [--sort relevance|citations|year] [-f text|json|bibtex|csv] [-o FILE] [-v]

lookup - Look up papers by identifier

opencite lookup IDENTIFIER [IDENTIFIER ...] [--enrich] [--append-bib FILE]
    [-f text|json|bibtex] [-o FILE] [-v]

Accepts DOI, pmid:X, pmc:X, arxiv:X, S2 ID, or OpenAlex ID. Supports multiple IDs.

cite - Citation graph

opencite cite IDENTIFIER [--direction citing|references|both] [--max N]
    [--sort citations|year] [--min-citations N] [-f text|json|bibtex] [-o FILE]

canonical - Most-cited papers in a field

opencite canonical "topic" [--max N] [--year-from YYYY] [--min-citations N]
    [-f text|json|bibtex] [-o FILE]

pdf - Download PDF

opencite pdf IDENTIFIER [-o PATH] [--filename NAME] [--convert]
    [--converter auto|markitdown|mistral]

-o accepts a file path (e.g., paper.pdf) or directory. With --convert, also generates a markdown file alongside the PDF.

convert - PDF to markdown

opencite convert FILE.pdf [-o FILE] [--converter auto|markitdown|mistral]
    [--extract-images] [--images-dir DIR]

Auto mode uses markit-mistral when MISTRAL_API_KEY is set (better for math and complex layouts), otherwise falls back to markitdown (free, local).

batch-fetch - Batch download PDFs

opencite batch-fetch FILE [-o DIR] [--convert] [--concurrency N] [--summary FILE]
opencite batch-fetch --from-json FILE [options]
opencite batch-fetch --from-stdin [options]

Downloads PDFs for multiple papers with controlled concurrency. Supports text files (one ID per line), JSON files (array of DOIs or opencite search results), and stdin. With --convert, output is organized into pdf/, markdown/, and markdown/img/ subdirectories.

Example workflow:

# Search and save as JSON, then batch download with conversion
opencite search "tDCS motor cortex" --max 30 -f json -o results.json
opencite batch-fetch --from-json results.json --convert --summary report.json -o ./papers

ids - Convert between identifiers

opencite ids IDENTIFIER [IDENTIFIER ...] [-f text|json]

Converts between DOI, PMID, and PMCID using the NCBI ID Converter API.

config - Manage configuration

opencite config init    # create ~/.opencite/config.toml template
opencite config show    # display resolved config (keys masked)
opencite config path    # show config file location

Output Formats

All search/lookup/cite/canonical commands support -f/--format:

• text (default) - human-readable output
• json - structured JSON
• bibtex - BibTeX entries for citation managers
• csv - comma-separated values (search only)

Use -o/--output FILE to write to a file instead of stdout.

Installation

# uv (recommended)
uv pip install opencite              # core (no PDF-to-markdown conversion)
uv pip install 'opencite[pdf]'       # with PDF download and markdown conversion

# pip
pip install opencite                 # core (no PDF-to-markdown conversion)
pip install 'opencite[pdf]'          # with PDF download and markdown conversion

# uvx (no install needed, runs from cache)
uvx opencite --version

PDF conversion support (markitdown and markit-mistral) is available via the [pdf] extra. Install opencite[pdf] when you need opencite pdf, opencite convert, opencite batch-fetch --convert, or preprint HTML full-text (arXiv ar5iv, bioRxiv/medRxiv .full HTML) which also depends on markitdown.

For development:

git clone https://github.com/neuromechanist/opencite.git
cd opencite
uv sync --extra dev

Configuration

OpenCite supports TOML config, .env files, and environment variables.

opencite config init    # creates ~/.opencite/config.toml with template
opencite config show    # display resolved config (keys masked)
opencite config path    # show config file location

Config loading priority

Later sources override earlier ones:

1. ~/.opencite/config.toml
2. ~/.opencite/.env
3. .env in working directory
4. Environment variables

API keys

Required for academic database access:

export SEMANTIC_SCHOLAR_API_KEY=your_key
export PUBMED_API_KEY=your_key
export OPENALEX_API_KEY=your_key

Optional:

export MISTRAL_API_KEY=your_key        # for PDF-to-markdown via Mistral OCR

Publisher tokens (optional)

For authenticated PDF downloads from paywalled publishers:

export ELSEVIER_API_KEY=your_key       # Elsevier/ScienceDirect
export WILEY_TDM_TOKEN=your_token      # Wiley TDM
export SPRINGER_API_KEY=your_key       # Springer Nature

These can also be set in ~/.opencite/config.toml:

[publishers]
elsevier = "your_key"
wiley_tdm = "your_token"
springer = "your_key"

Redistribution and licensing

OpenCite retrieves PDFs and markdown for you and reports what it found, but it does not enforce a redistribution policy. The publication-vs-reuse decision belongs to the caller.

What we report:

• Paper.oa_status -- the OpenAlex Open Access status (gold, hybrid, green, bronze, closed, diamond, or empty when unknown). is_oa = True collapses all open categories together; oa_status distinguishes them. Notably, bronze is free-to-read but not openly licensed.
• PDFLocation.license and version -- per-source license string (cc-by, cc-by-nc, etc.) and version (publishedVersion, acceptedVersion, submittedVersion) where the upstream API surfaces them. Available in opencite lookup --format json --verbose and opencite search.
• <pdf>.license.json -- a sidecar written next to every downloaded PDF containing {url, source, license, version, oa_status, publisher_tdm, doi, retrieved_at}. A later "is this PDF safe to commit?" check can run by scanning sidecars without re-querying the original Paper.

If your pipeline publishes its artifacts (e.g. commits PDFs/markdown to a public repo), be deliberate about which sources you enable. Publisher TDM tokens (Elsevier, Wiley, Springer) almost universally prohibit redistribution of the bytes they return; the sidecar's publisher_tdm: true flag is a machine-readable signal for downstream scanners.

License

MIT