{"id":44509043,"url":"https://github.com/neuromechanist/opencite","last_synced_at":"2026-05-21T21:09:43.434Z","repository":{"id":337071737,"uuid":"1151882948","full_name":"neuromechanist/opencite","owner":"neuromechanist","description":"Academic literature search, citation management, and PDF retrieval CLI","archived":false,"fork":false,"pushed_at":"2026-05-06T08:27:20.000Z","size":215,"stargazers_count":2,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T08:36:10.978Z","etag":null,"topics":["citations","full-text-extraction","literature-review","literature-search","open-science","paper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neuromechanist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T03:02:45.000Z","updated_at":"2026-05-06T06:30:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/neuromechanist/opencite","commit_stats":null,"previous_names":["neuromechanist/opencite"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/neuromechanist/opencite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuromechanist%2Fopencite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuromechanist%2Fopencite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuromechanist%2Fopencite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuromechanist%2Fopencite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neuromechanist","download_url":"https://codeload.github.com/neuromechanist/opencite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuromechanist%2Fopencite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33315133,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"ssl_error","status_checked_at":"2026-05-21T12:22:11.673Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["citations","full-text-extraction","literature-review","literature-search","open-science","paper"],"created_at":"2026-02-13T12:59:42.881Z","updated_at":"2026-05-21T21:09:43.428Z","avatar_url":"https://github.com/neuromechanist.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCite\n\nAcademic literature search, citation management, and PDF retrieval CLI.\n\nSearches 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.\n\n## Quick Start\n\nInstall and set up your API keys:\n\n```bash\nuv pip install opencite                # or: pip install opencite\nopencite config init                   # creates ~/.opencite/config.toml\n```\n\nAdd your API keys to `~/.opencite/config.toml` or export them as environment variables:\n\n```bash\nexport SEMANTIC_SCHOLAR_API_KEY=your_key\nexport PUBMED_API_KEY=your_key\nexport OPENALEX_API_KEY=your_key\n```\n\nStart searching:\n\n```bash\nopencite search \"transformer attention mechanism\"\nopencite lookup 10.1038/nature12345\nopencite canonical \"deep learning\" --min-citations 500\nopencite cite 10.1038/nature12345\nopencite pdf 10.1038/nature12345 -o paper.pdf --convert\n```\n\n\u003e [!NOTE]\n\u003e **AI-agent skill:** The opencite skill ships in [neuromechanist/research-skills](https://github.com/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.\n\n\u003e [!TIP]\n\u003e **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).\n\n## Commands\n\n### search - Find papers\n\n```bash\nopencite search \"query\" [--max N] [--source all|openalex|s2|pubmed]\n    [--year-from YYYY] [--year-to YYYY] [--oa-only]\n    [--sort relevance|citations|year] [-f text|json|bibtex|csv] [-o FILE] [-v]\n```\n\n### lookup - Look up papers by identifier\n\n```bash\nopencite lookup IDENTIFIER [IDENTIFIER ...] [--enrich] [--append-bib FILE]\n    [-f text|json|bibtex] [-o FILE] [-v]\n```\n\nAccepts DOI, `pmid:X`, `pmc:X`, `arxiv:X`, S2 ID, or OpenAlex ID. Supports multiple IDs.\n\n### cite - Citation graph\n\n```bash\nopencite cite IDENTIFIER [--direction citing|references|both] [--max N]\n    [--sort citations|year] [--min-citations N] [-f text|json|bibtex] [-o FILE]\n```\n\n### canonical - Most-cited papers in a field\n\n```bash\nopencite canonical \"topic\" [--max N] [--year-from YYYY] [--min-citations N]\n    [-f text|json|bibtex] [-o FILE]\n```\n\n### pdf - Download PDF\n\n```bash\nopencite pdf IDENTIFIER [-o PATH] [--filename NAME] [--convert]\n    [--converter auto|markitdown|mistral]\n```\n\n`-o` accepts a file path (e.g., `paper.pdf`) or directory. With `--convert`, also generates a markdown file alongside the PDF.\n\n### convert - PDF to markdown\n\n```bash\nopencite convert FILE.pdf [-o FILE] [--converter auto|markitdown|mistral]\n    [--extract-images] [--images-dir DIR]\n```\n\nAuto mode uses markit-mistral when `MISTRAL_API_KEY` is set (better for math and complex layouts), otherwise falls back to markitdown (free, local).\n\n### batch-fetch - Batch download PDFs\n\n```bash\nopencite batch-fetch FILE [-o DIR] [--convert] [--concurrency N] [--summary FILE]\nopencite batch-fetch --from-json FILE [options]\nopencite batch-fetch --from-stdin [options]\n```\n\nDownloads 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.\n\nExample workflow:\n\n```bash\n# Search and save as JSON, then batch download with conversion\nopencite search \"tDCS motor cortex\" --max 30 -f json -o results.json\nopencite batch-fetch --from-json results.json --convert --summary report.json -o ./papers\n```\n\n### ids - Convert between identifiers\n\n```bash\nopencite ids IDENTIFIER [IDENTIFIER ...] [-f text|json]\n```\n\nConverts between DOI, PMID, and PMCID using the NCBI ID Converter API.\n\n### config - Manage configuration\n\n```bash\nopencite config init    # create ~/.opencite/config.toml template\nopencite config show    # display resolved config (keys masked)\nopencite config path    # show config file location\n```\n\n## Output Formats\n\nAll search/lookup/cite/canonical commands support `-f`/`--format`:\n\n- `text` (default) - human-readable output\n- `json` - structured JSON\n- `bibtex` - BibTeX entries for citation managers\n- `csv` - comma-separated values (search only)\n\nUse `-o`/`--output FILE` to write to a file instead of stdout.\n\n## Installation\n\n```bash\n# uv (recommended)\nuv pip install opencite              # core (no PDF-to-markdown conversion)\nuv pip install 'opencite[pdf]'       # with PDF download and markdown conversion\n\n# pip\npip install opencite                 # core (no PDF-to-markdown conversion)\npip install 'opencite[pdf]'          # with PDF download and markdown conversion\n\n# uvx (no install needed, runs from cache)\nuvx opencite --version\n```\n\nPDF conversion support (markitdown and markit-mistral) is available via the `[pdf]` extra.\nInstall `opencite[pdf]` when you need `opencite pdf`, `opencite convert`,\n`opencite batch-fetch --convert`, or preprint HTML full-text (arXiv ar5iv,\nbioRxiv/medRxiv `.full` HTML) which also depends on markitdown.\n\nFor development:\n\n```bash\ngit clone https://github.com/neuromechanist/opencite.git\ncd opencite\nuv sync --extra dev\n```\n\n## Configuration\n\nOpenCite supports TOML config, `.env` files, and environment variables.\n\n```bash\nopencite config init    # creates ~/.opencite/config.toml with template\nopencite config show    # display resolved config (keys masked)\nopencite config path    # show config file location\n```\n\n### Config loading priority\n\nLater sources override earlier ones:\n\n1. `~/.opencite/config.toml`\n2. `~/.opencite/.env`\n3. `.env` in working directory\n4. Environment variables\n\n### API keys\n\nRequired for academic database access:\n\n```bash\nexport SEMANTIC_SCHOLAR_API_KEY=your_key\nexport PUBMED_API_KEY=your_key\nexport OPENALEX_API_KEY=your_key\n```\n\nOptional:\n\n```bash\nexport MISTRAL_API_KEY=your_key        # for PDF-to-markdown via Mistral OCR\n```\n\n### Publisher tokens (optional)\n\nFor authenticated PDF downloads from paywalled publishers:\n\n```bash\nexport ELSEVIER_API_KEY=your_key       # Elsevier/ScienceDirect\nexport WILEY_TDM_TOKEN=your_token      # Wiley TDM\nexport SPRINGER_API_KEY=your_key       # Springer Nature\n```\n\nThese can also be set in `~/.opencite/config.toml`:\n\n```toml\n[publishers]\nelsevier = \"your_key\"\nwiley_tdm = \"your_token\"\nspringer = \"your_key\"\n```\n\n## Redistribution and licensing\n\nOpenCite retrieves PDFs and markdown for you and reports what it found, but it\ndoes not enforce a redistribution policy. The publication-vs-reuse decision\nbelongs to the caller.\n\nWhat we report:\n\n- **`Paper.oa_status`** -- the OpenAlex Open Access status (`gold`, `hybrid`,\n  `green`, `bronze`, `closed`, `diamond`, or empty when unknown). `is_oa = True`\n  collapses all open categories together; `oa_status` distinguishes them.\n  Notably, **bronze** is free-to-read but not openly licensed.\n- **`PDFLocation.license` and `version`** -- per-source license string\n  (`cc-by`, `cc-by-nc`, etc.) and version (`publishedVersion`,\n  `acceptedVersion`, `submittedVersion`) where the upstream API surfaces them.\n  Available in `opencite lookup --format json --verbose` and `opencite search`.\n- **`\u003cpdf\u003e.license.json`** -- a sidecar written next to every downloaded PDF\n  containing `{url, source, license, version, oa_status, publisher_tdm, doi,\n  retrieved_at}`. A later \"is this PDF safe to commit?\" check can run by\n  scanning sidecars without re-querying the original Paper.\n\nIf your pipeline publishes its artifacts (e.g. commits PDFs/markdown to a\npublic repo), be deliberate about which sources you enable. Publisher TDM\ntokens (Elsevier, Wiley, Springer) almost universally prohibit redistribution\nof the bytes they return; the sidecar's `publisher_tdm: true` flag is a\nmachine-readable signal for downstream scanners.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneuromechanist%2Fopencite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneuromechanist%2Fopencite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneuromechanist%2Fopencite/lists"}