s2cli 0.1.0

A CLI for Semantic Scholar API - designed for humans and AI agents

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

# 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-3011 or 10.18653/v1/N18-3011
• arXiv: ARXIV:1706.03762 or arXiv: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:

1. Human-first by default - Tables and readable output in terminals
2. Machine-friendly when piped - Automatic JSON for scripts and AI agents
3. Explicit overrides - --json and --bibtex flags when you need control
4. BibTeX included - Every paper result can include a citation

License

MIT