opencite

name	opencite
description	Use this skill for "search for papers", "find citations", "look up a DOI", "get BibTeX", "download PDF", "convert PDF to markdown", "find canonical papers", "convert identifiers", "batch download papers", "configure opencite", "literature review", "find related papers", "what papers cite this", "export references", "read this paper", or mentions of opencite, Semantic Scholar, OpenAlex, PubMed, academic literature search, citation management, or paper retrieval.
version	0.1.0

OpenCite CLI

OpenCite is a CLI tool for academic literature search and citation management. It aggregates results from Semantic Scholar, OpenAlex, PubMed, arXiv, and bioRxiv/medRxiv, deduplicates them, and outputs formatted results. It also supports PDF retrieval, PDF-to-markdown conversion, and batch operations.

Installation

# Recommended
uv pip install opencite

# Alternative: run without installing
uvx opencite --version

PDF conversion support (markitdown and markit-mistral) is included by default. When MISTRAL_API_KEY is set, markit-mistral handles math, tables, and complex layouts. Otherwise, markitdown (free, local) is the fallback.

For development:

uv sync --extra dev

Research Workflow

Follow this end-to-end workflow for literature research, paper retrieval, or reading material on a topic.

1. Search for relevant papers

Choose the search strategy based on the request:

• Canonical/foundational papers: uvx opencite canonical "topic" --max 10
• Recent or specific papers: uvx opencite search "query" --max 20 --sort citations
• Citation graph exploration: uvx opencite cite "DOI" --direction both
• Combine strategies when appropriate (e.g., canonical for background + search for recent work)

2. Evaluate and select papers

Review results considering citation count, relevance, recency, and open access availability. Present a summary and confirm which papers to retrieve.

3. Download and convert

For multiple papers (preferred): Save search results as JSON and use batch-fetch:

uvx opencite search "topic" --max 10 -f json -o results.json
uvx opencite batch-fetch --from-json results.json --convert -o ./papers --summary report.json

batch-fetch --convert automatically creates this directory structure:

papers/
├── pdf/          # downloaded PDFs
└── markdown/     # converted markdown files
    └── img/      # per-paper image directories (mistral only)

For individual papers:

uvx opencite pdf "10.1234/example" -o papers/pdf/ --convert

Note: pdf --convert places the markdown file next to the PDF and does not extract images. For the organized subdirectory layout with image extraction, use batch-fetch.

4. Read and synthesize

Read the converted markdown files for deeper analysis:

• Summarize key findings across papers
• Identify common themes and disagreements
• When using batch-fetch, markdown is in papers/markdown/ and extracted images (markit-mistral only) are in per-paper subdirectories under papers/markdown/img/
• Generate BibTeX for citation: uvx opencite lookup "DOI" -f bibtex --append-bib refs.bib

Command Summary

Command	Purpose
search	Find papers matching a query across multiple APIs
lookup	Look up a specific paper by DOI, PMID, PMCID, or other identifier
cite	Get citing/cited-by papers for a given identifier
canonical	Find the most-cited, foundational papers for a topic
pdf	Download a PDF for a paper by identifier
convert	Convert a local PDF file to markdown
ids	Convert between identifier types (DOI, PMID, PMCID)
batch-fetch	Download PDFs for multiple papers with optional conversion
config	Manage opencite configuration (init, show, path)

For full option listings, see references/cli-reference.md.

Configuration Essentials

Initialize configuration and check resolved values:

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

Key environment variables:

• SEMANTIC_SCHOLAR_API_KEY - Semantic Scholar API
• PUBMED_API_KEY - NCBI/PubMed API
• OPENALEX_API_KEY - OpenAlex API (required since Feb 2026)
• MISTRAL_API_KEY - Enhanced PDF-to-markdown conversion (optional)

For full configuration details including publisher tokens and loading priority, see references/api-keys-and-config.md.

Error Handling

• Rate limits: Semantic Scholar has aggressive rate limiting (1 req/sec). When rate limit errors occur, wait and retry.
• Missing API keys: Commands warn about missing keys but still query available sources.
• Timeouts: Retry the command or try a different source with --source.
• PDF not found: opencite reports which sources were tried and why each failed. Papers behind paywalls may need institutional access or publisher API tokens.

References

• CLI Reference - Complete option listings for all subcommands and the Python API
• Common Workflows - Worked examples for typical usage patterns
• API Keys and Configuration - Configuration loading, API keys, and publisher tokens