# s2-cli

Adopt this skill: https://proskills.md/skills/other/huggingface-s2-cli

Page: https://proskills.md/skills/other/huggingface-s2-cli
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 2804
upstream: https://github.com/huggingface/s2-cli/blob/HEAD/SKILL.md

```text
---
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 outside a local catalog. Prefer `s2` over curl or ad-hoc Graph API requests."
---

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

Install with `uv tool install git+https://github.com/huggingface/s2-cli.git`.
Use compact TSV for reading. Add `--json` for programmatic filtering, joining,
or schema-dependent processing.

`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.

## Commands

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

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. Use `s2 search QUERY --limit 100 --json` for graph-wide discovery.
2. 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.
3. Use `s2 refs PAPER` for a bibliography and `s2 citations PAPER` for citing
   work. Quote titles. Prefer `ARXIV:` IDs after the first resolution.
4. Extract arXiv IDs from the `arxiv` TSV column or `externalIds.ArXiv` in JSON.
5. 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.
- Default request pacing is 1.5s. Do not page citations of famous papers up to
  the 10k cap unless the user explicitly asks.
```

## File: README.md
upstream: https://github.com/huggingface/s2-cli/blob/HEAD/README.md

````text
# s2 CLI and Skill

A fast, read-only command-line client for the [Semantic Scholar Graph API](https://api.semanticscholar.org/api-docs/graph), alongside a Skill for coding agents.

Built to power [Papers with Code](https://paperswithcode.co)'s chat interface.

Use `s2` to:

- list the papers a work **cites** (`s2 refs`)
- list the papers that **cite** a work (`s2 citations`)
- **search** the Semantic Scholar graph when a paper may not be in a local catalog

This CLI requires an API key. Set `PWC_SEMANTIC_SCHOLAR_API_KEY` or `S2_API_KEY`. Request a key at [Semantic Scholar's API page](https://www.semanticscholar.org/product/api).

```bash
s2 refs "Attention is All You Need"
s2 citations ARXIV:1706.03762 --limit 50
s2 search "image dehazing" --year 2025-2026 --limit 100 --json
```

## Installation

Python 3.10 or newer is required.

With [`uv`](https://docs.astral.sh/uv/):

```bash
uv tool install git+https://github.com/huggingface/s2-cli.git
```

Or with [`pipx`](https://pipx.pypa.io/):

```bash
pipx install git+https://github.com/huggingface/s2-cli.git
```

From a clone:

```bash
git clone https://github.com/huggingface/s2-cli.git
cd s2-cli
uv tool install .
```

Confirm the installation:

```bash
s2 version
```

## Add the CLI Skill

Copy [`SKILL.md`](SKILL.md) into your agent's skills directory:

```bash
mkdir -p .agents/skills/s2-cli
curl -LsSf https://raw.githubusercontent.com/huggingface/s2-cli/main/SKILL.md \
  -o .agents/skills/s2-cli/SKILL.md
```

## Quick start

```bash
export S2_API_KEY=...   # or PWC_SEMANTIC_SCHOLAR_API_KEY

s2 refs "Attention is All You Need"
s2 refs 1706.03762 --limit 50 --offset 20
s2 citations ARXIV:1706.03762 --json
s2 search "scene graph generation" --limit 100
s2 search "scene graph generation" --year 2025-2026 --limit 100 --json
```

`PAPER` accepts a quoted title, an arXiv ID (`1706.03762`, `arXiv:1706.03762`), a DOI, a 40-character Semantic Scholar paper ID, a prefixed ID (`ARXIV:`, `DOI:`, `CorpusId:`, `PMID:`, `URL:`), or an arXiv / Semantic Scholar URL. Titles are resolved with Semantic Scholar's closest-title match. The matched title, paper ID, arXiv ID, and match score are printed on stderr so a bad match is visible. Pass an ID if the header is wrong.

## Command reference

| Command | Description |
| --- | --- |
| `s2 refs PAPER` | Papers this paper cites (bibliography) |
| `s2 citations PAPER` | Papers that cite this paper |
| `s2 search QUERY` | Relevance search over the Semantic Scholar graph |
| `s2 version` | Show the CLI version |

Shared flags: `--limit`, `--offset`, `--json`, `--fields`. `s2 search` also accepts `--year` (`2025` or `2025-2026`). Defaults are `--limit 20`. Search `--limit` maxes at 100; refs/citations max at 1000. There is no `--all`; rerun with `--offset` when stderr prints `# more`.

Citation requests must keep `offset + limit <= 9999`. Highly cited papers are not fully enumerable through this CLI.

## Output and scripting

List commands print lossless TSV (`paperId`, `year`, `cites`, `arxiv`, `title`). Add `--json` for the raw Semantic Scholar payload wrapped as:

```json
{
  "schema_version": "v1",
  "paper": {"id": "ARXIV:1706.03762"},
  "data": {}
}
```

`paper` is present on `refs` and `citations`. Search JSON includes abstracts in `data` by default.

Stable exit codes:

| Code | Meaning |
| ---: | --- |
| `0` | Success |
| `2` | Invalid usage or missing API key |
| `3` | Network, server, or exhausted rate-limit failure |
| `4` | Not found or invalid API response |

## Configuration

| Variable | Meaning |
| --- | --- |
| `PWC_SEMANTIC_SCHOLAR_API_KEY` | Preferred API key |
| `S2_API_KEY` | Fallback API key if the preferred key is unset |
| `S2_REQUEST_DELAY` | Seconds to wait between requests (default `1.5`) |

The CLI never reads a secondary historical-backfill key. It sends `x-api-key`, honors `Retry-After` on HTTP 429, and identifies itself as `s2-cli/<version>`.

## Development

```bash
uv run --with pytest pytest tests
```
````
