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 ```bash # 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: ```bash 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: ```bash 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:** ```bash 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](references/cli-reference.md). ## Configuration Essentials Initialize configuration and check resolved values: ```bash 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](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](references/cli-reference.md) - Complete option listings for all subcommands and the Python API - [Common Workflows](references/common-workflows.md) - Worked examples for typical usage patterns - [API Keys and Configuration](references/api-keys-and-config.md) - Configuration loading, API keys, and publisher tokens