Opencite

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

bashCopy code
# 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:

bashCopy code
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:

bashCopy code
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:

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

For individual papers:

bashCopy code
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

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

Configuration Essentials

Initialize configuration and check resolved values:

bashCopy code
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