s2cli - Semantic Scholar CLI
A command-line interface for the Semantic Scholar API, designed for both human researchers and AI agents.
Installation
pip install s2cli
Or with uv:
uv pip install s2cli
Quick Start
Run directly without installing using uvx:
uvx s2cli search "attention mechanism transformers"
Or after installing:
# Search for papers (shows table in terminal)
s2cli search "attention mechanism transformers"
# Get paper details
s2cli paper ARXIV:1706.03762
# Export BibTeX
s2cli bibtex ARXIV:1706.03762 >> references.bib
# Get papers citing this paper
s2cli citations 204e3073870fae3d05bcbc2f6a8e263d9b72e776
# Get paper recommendations
s2cli recommend 204e3073870fae3d05bcbc2f6a8e263d9b72e776
Output Formats
s2cli is designed to work seamlessly for both humans and AI agents:
| Context | Default Output | Behavior |
|---|---|---|
| Terminal (interactive) | Human-readable table | Easy to scan and read |
| Piped to another command | Compact JSON | Machine-parseable for scripts |
--json flag |
Pretty JSON | Explicit JSON when you need it |
--bibtex / -b flag |
BibTeX | Ready for LaTeX |
# Terminal: shows a nice table
s2cli search "transformers"
# Piped: automatically outputs JSON for jq, scripts, AI agents
s2cli search "transformers" | jq '.results[0].title'
# Explicit JSON (pretty-printed in terminal)
s2cli search "transformers" --json
# BibTeX output
s2cli search "transformers" --bibtex
Commands
Paper Commands
| Command | Description |
|---|---|
s2cli search <query> |
Search papers by keyword |
s2cli paper <id>... |
Get paper details (batch supported) |
s2cli citations <id> |
Get papers citing this paper |
s2cli references <id> |
Get papers cited by this paper |
s2cli recommend <id> |
Get paper recommendations |
s2cli bibtex <id>... |
Export BibTeX only |
Author Commands
| Command | Description |
|---|---|
s2cli author get <id> |
Get author details |
s2cli author search <name> |
Search authors by name |
s2cli author papers <id> |
Get author's papers |
Dataset Commands
| Command | Description |
|---|---|
s2cli datasets |
List available dataset releases |
s2cli dataset <release> |
Get dataset info |
Search Filters
# Filter by year
s2cli search "LLM" --year 2023
s2cli search "LLM" --year 2020-2024
# Filter by minimum citations
s2cli search "attention" --min-citations 1000
# Only open access papers
s2cli search "BERT" --open-access
# Filter by venue
s2cli search "vision" --venue "CVPR,ICCV"
# Combine filters
s2cli search "transformers" --year 2022- --min-citations 500 --open-access
Examples
Human Workflows
# Find influential papers on a topic
s2cli search "large language models" --min-citations 1000
# Get all papers by an author
s2cli author papers 1741101 --limit 50
# Export bibliography for a set of papers
s2cli bibtex paper1 paper2 paper3 > refs.bib
# Explore citation network
s2cli citations 204e3073870fae3d05bcbc2f6a8e263d9b72e776 --limit 20
AI Agent / Scripting Workflows
# Quick context gathering (auto-JSON when piped)
s2cli search "retrieval augmented generation" | jq '.results[:3]'
# Batch lookup with specific fields
s2cli paper id1 id2 id3 --fields paperId,title,year,citationCount
# Get top cited paper
s2cli search "NLP" --min-citations 5000 --limit 1 | jq '.results[0]'
# Extract just titles
s2cli search "vision transformers" | jq -r '.results[].title'
Paper ID Formats
The CLI accepts various paper ID formats:
- Semantic Scholar ID:
204e3073870fae3d05bcbc2f6a8e263d9b72e776 - DOI:
DOI:10.18653/v1/N18-3011or10.18653/v1/N18-3011 - arXiv:
ARXIV:1706.03762orarXiv:1706.03762 - CorpusId:
CorpusId:215416146 - PubMed:
PMID:123456
Configuration
Set your API key for higher rate limits:
export S2_API_KEY=your_key_here
Or pass it directly:
s2cli search "query" --api-key your_key_here
Design Philosophy
Based on CLI best practices and GitHub CLI patterns:
- Human-first by default - Tables and readable output in terminals
- Machine-friendly when piped - Automatic JSON for scripts and AI agents
- Explicit overrides -
--jsonand--bibtexflags when you need control - BibTeX included - Every paper result can include a citation
License
MIT
Metadata
Release files for s2cli 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| s2cli-0.1.1.tar.gz | 26.6 kB | Without provenance | Details for s2cli-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| s2cli-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for s2cli-0.1.1-py3-none-any.whl |
Total release size: 43.4 kB
Release files / s2cli-0.1.1.tar.gz
| Download URL | s2cli-0.1.1.tar.gz |
|---|---|
| Size | 26.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
85c31cc2e9c63f1a2b95c19aa5f295df7e67a57363efaa104c33e09166662678
|
|
BLAKE2b-256 checksum How to use checksums |
129ab8a05277d06999ee2bd70e509682c1ae402a91340691f7e49c8c53ecb553
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.21 {"installer":{"name":"uv","version":"0.9.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / s2cli-0.1.1-py3-none-any.whl
| Download URL | s2cli-0.1.1-py3-none-any.whl |
|---|---|
| Size | 16.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
de01bb211fb05e77627cbdd62a74bf8411da5c8d9bd644fbf2f9e0c09cf64b42
|
|
BLAKE2b-256 checksum How to use checksums |
bcf3243c6864fd21291cbbc2a4ee09b948531ace59eba4c45f2cfb0ffe5152b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.21 {"installer":{"name":"uv","version":"0.9.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for s2cli 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.