s2-cli

Name: s2-cli
Author: huggingface/paperswithcode

$npx mdskill add huggingface/paperswithcode/s2-cli

The `s2` CLI is read-only. It queries the Semantic Scholar Graph API and requires `PWC_SEMANTIC_SCHOLAR_API_KEY` or `S2_API_KEY`. Run `s2 --help` or a nested `--help` command when the live parser and this skill disagree; the parser is authoritative.

SKILL.md

.github/skills/s2-cliView on GitHub ↗

---
name: s2-cli
description: "Semantic Scholar CLI (`s2`) for on-demand citation graph lookup: papers a work cites, papers that cite a work, and graph search across 200M+ papers. Use whenever the user asks for Semantic Scholar, S2, cited papers, references, bibliography, citing papers, citation count from Semantic Scholar, or papers that may not be in the local Papers With Code catalog. Prefer `s2` over curl or ad-hoc Graph API requests. `pwc search` is the local catalog only; `s2 search` is the broader Semantic Scholar graph."
---

The `s2` CLI is read-only. It queries the Semantic Scholar Graph API and
requires `PWC_SEMANTIC_SCHOLAR_API_KEY` or `S2_API_KEY`. Run `s2 --help` or a
nested `--help` command when the live parser and this skill disagree; the
parser is authoritative.

Use compact TSV for reading. Prefer `--jsonl` for programmatic filtering,
sorting, or joining: it emits one unnested paper object per line with the same
shape for search, references, and citations. Use raw `--json` only when API
edge metadata or other schema-specific fields are required.

`PAPER` accepts a modern or legacy arXiv ID, a DOI, a 40-character Semantic
Scholar paper ID, a prefixed ID (`ARXIV:`, `DOI:`, `CorpusId:`, `PMID:`,
`URL:`), an arXiv or Semantic Scholar URL, or a quoted title. Title matching
uses Semantic Scholar's closest-title endpoint and prints a header with the
matched title, ID, arXiv ID, and match score. If the header is wrong, rerun
with an ID. Do not fall back to `s2 search` to resolve a specific paper.

In this Papers With Code checkout, prefix every command with:

```bash
uv run --directory clis/s2_cli --env-file ../../backend/keys.env
```

Elsewhere, install with `uv tool install git+https://github.com/huggingface/s2-cli.git`
and export `S2_API_KEY` or `PWC_SEMANTIC_SCHOLAR_API_KEY`.

## Commands

- `s2 refs PAPER [--limit LIMIT] [--offset OFFSET] [--fields FIELDS] [--json|--jsonl]` — papers this paper cites.
- `s2 citations PAPER [--limit LIMIT] [--offset OFFSET] [--fields FIELDS] [--json|--jsonl]` — papers that cite this paper.
- `s2 search QUERY [--limit LIMIT] [--offset OFFSET] [--year YEAR] [--fields FIELDS] [--json|--jsonl]` — search the Semantic Scholar graph.
- `s2 version` — show CLI and API contract versions.

All list commands accept `--sort-by citation-count --top N`. Sorting applies
only to the fetched page and prints that scope on stderr. `--top` requires
`--sort-by`, cannot exceed `--limit`, and can be combined with TSV or
`--jsonl`, not raw `--json`.

Default `--limit` is 20. Search max `--limit` is 100; refs/citations max is
1000. There is no `--all`. When stderr prints `# more: rerun with --offset N`,
pass that offset. Citations must keep `offset + limit <= 9999`.

## Research workflow

1. Prefer `pwc search` / `pwc paper info` for papers already in Papers With Code.
2. Use `s2 search QUERY --limit 100 --json` when you need the broader graph,
high-citation classics, or papers missing from the local catalog.
3. Run a second `s2 search QUERY --year 2025-2026 --limit 100 --json` for a
recent slice. Do not treat one search as both the classic and recent lists.
4. Use `s2 refs PAPER` for a bibliography and `s2 citations PAPER` for citing
work. Quote titles. Prefer `ARXIV:` IDs after the first resolution.
5. For a bounded list ranked by the citing papers' own citation counts, run
`s2 citations PAPER --limit 1000 --sort-by citation-count --top 20`. Describe
it as the highest-cited papers in that fetched page, never as a verified
global ranking.
6. Extract arXiv IDs from the `arxiv` TSV column or `externalIds.ArXiv` in
JSONL/JSON.
7. Prefer `--jsonl` for scripts. Raw `--json` paths are:
- search papers: `.data.data[]`
- references: `.data.data[].citedPaper`
- citations: `.data.data[].citingPaper`
8. If retrieval cannot establish a requested ranking, state the bounded scope
or API limitation. Never fill the gap from memory and then call the result
"most cited", "top", exhaustive, or verified.
9. Do not curl `api.semanticscholar.org` while this CLI is available.

## Output and limits

- Stable exit codes are `0` success, `2` invalid usage or missing key, `3`
network/rate-limit failure, and `4` not found or invalid API response.
- The citations endpoint does not provide global citation-count ordering.
Sorting one fetched page is useful but cannot establish the globally most
cited papers. Citations beyond offset 9,999 cannot be enumerated, so famous
papers may be impossible to rank exhaustively through this API.
- Never read `PWC_SEMANTIC_SCHOLAR_API_KEY_2`. That key is reserved for
historical backfill jobs.
- Default request pacing is 1.5s. Do not page citations of famous papers up to
the 10k cap unless the user explicitly asks.

More from huggingface/paperswithcode

Skill	Description
add-benchmark	Add or update benchmark datasets/leaderboards in the paperswithcode repo database. Use this whenever the user asks to add a benchmark, add a leaderboard, set default/featured benchmarks for a task, link benchmarks to tasks, add Accuracy or other metrics for a benchmark, or fix benchmark source links. This is repo-specific and should trigger even if the user only names benchmark titles and a task page.
add-conference	Add or update conference rows in the paperswithcode repo database. Use this whenever the user asks to add a conference, create a conference page, import accepted papers for a venue (CVPR, ICLR, NeurIPS, ICML, ICRA, etc.), set conference dates/venue/description/hero image, or link papers to a conference edition. Trigger even for casual phrasing like "add CVPR 2027", "create the ICLR 2026 page", "import conference papers from this CSV", or "set the conference thumbnail".
add-evals	Add evaluation results to the paperswithcode database from any source — Hugging Face model cards, arXiv/HF/PapersWithCode paper text, or GitHub repository READMEs — restricted to benchmarks that already exist with a task association and the exact leaderboard metric already configured. Use this whenever the user shares a Hugging Face model URL or repo id, an arXiv id / HF paper / PapersWithCode paper, a GitHub repository URL, or a model release page and asks to add evaluation results, benchmark scores, or leaderboard entries — even when phrased casually like "add scores from this model", "import benchmarks from <hf url>", "ingest the eval table from this paper into the DB", "grab the benchmarks from this repo's README", or "add evaluations for this release". By default import only the model(s) the source paper introduces — never post comparison-table baselines onto other papers as external evals unless the user explicitly asks. If the source is not backed by an arXiv paper, first use the add-external-paper skill to create or update the `source = 'external'` paper row, then attach evaluation rows to that paper. This skill must skip source-only metrics, component scores, subscores, and alternate metric labels unless that metric is already configured for the exact leaderboard; use it instead of generic ingestion guidance whenever the user is trying to populate evaluation results from a model, paper, or repository source.
add-external-paper	Add non-ArXiv external papers/resources to the paperswithcode repo database. Use this whenever the user asks to add, index, submit, or populate a paper/resource/release that does not have an arXiv paper, including Hugging Face model cards, GitHub repositories, blog posts, vendor technical reports, external PDFs, project pages, or release announcements. This skill should trigger even when the user casually says "add this repo/model/blog to paperswithcode" or gives a URL such as GitHub, Hugging Face, a company blog, a PDF, or a technical report and wants it to appear as a paper page with tasks, methods, code, project links, HF artifacts, and a thumbnail.
add-method	Add or update AI/ML method taxonomy rows in the paperswithcode repo database. Use this whenever the user asks to add a method, technique, architecture, attention mechanism, training method, model-family method, or source/visual metadata for a method; says phrases like "make GPT-4 a method", "add X as a method", "similarly add this method", "link papers that cite the source paper", or "update the method source to point to the paper page"; or gives a method name plus a paper, arXiv id, PapersWithCode URL, Hugging Face report, GitHub explainer, blog post, or image for the method thumbnail.
add-task	Add or update AI/ML task taxonomy rows in the paperswithcode repo database. Use this whenever the user asks to add a task, create a new benchmark category, add a subtask under an existing task, set task description/keywords/area/image, or expand task coverage; says phrases like "add X as a task", "create a task page for", "similarly add this task", or "we need a task for"; or names a research area (ASR, object detection, agents, tabular learning) that should become a browsable /tasks/ page with keywords and a hero image. After adding the task, recommend standard benchmarks to link next (use add-benchmark when the user wants them ingested).
complete-task	>-
complete-task-based-on-hf	Complete or audit a Papers With Code task using Hugging Face model popularity as the discovery signal. Use this whenever a user asks to scan the most downloaded or trending Hugging Face models for a pipeline/task, resolve their canonical technical reports, and add missing paper-native evaluations to existing Papers With Code benchmarks. Trigger for requests like "complete this task from HF", "check popular Hub models for missing evals", or a Hugging Face models URL with `pipeline_tag` and `sort`; use `add-evals` instead for one already-known model or paper, and `complete-task-v2` for a holistic field survey beyond Hugging Face.
complete-task-v2	>-
create-thumbnail	Create, replace, audit, and publish Papers With Code paper thumbnails for one paper or every paper on a benchmark page. Use this whenever a user asks to add a thumbnail, fix an "Untitled resource" card, use artwork from a source/project/GitHub README, regenerate a paper preview, or find papers on a benchmark with missing, generic, stale, or broken thumbnails. This is the repo-specific end-to-end workflow for source selection, portrait composition, cache-safe publication, and live visual verification.