SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsopencite

opencite

Writing & research

View repository

Updated 10-16 06:50

About this skill

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