LLM Wiki

github.com/huggingface/s2-cli — Semantic Scholar CLI + 에이전트 Skill

Properties3
descriptionHugging Face의 읽기 전용 s2 CLI — 인용 그래프 조회(refs/citations/search)와 코딩 에이전트용 Skill을 묶은 Python 도구. Papers with Code 채팅 구동용.
tagsresearch, dev-tools, python, cli, open-source
aliasess2-cli, s2 cli, Semantic Scholar CLI

5 min read

고정 커밋 63dba8bc…(main HEAD와 일치 확인) 기준 정적 검사 요약. 설치·실행(API 키 필요)은 하지 않았고 기능 서술은 README·SKILL.md(원본 캡처)에 근거한다.[unverified]

개요

s2-cli는 Hugging Face가 만든 Semantic Scholar Graph API의 빠른 읽기 전용 커맨드라인 클라이언트로, 코딩 에이전트가 쓸 수 있는 Skill(SKILL.md) 을 함께 배포한다. Papers with Code 채팅 인터페이스를 구동하려고 만들어졌다. 논문 하나가 인용하는 논문들(refs), 인용하는 쪽 논문들(citations), 그래프 전체 검색(search) 세 가지 질의를 안정적인 TSV/JSON 출력과 exit code 계약으로 제공한다.[1]

에이전트 도구로서의 특징은 “curl로 API 두드리지 마라”는 규약과 함께 요청 페이싱·식별자 해석·매칭 검증 절차를 Skill 문서로 강제한다는 점이다.[1]

명령·계약

  • s2 refs PAPER / s2 citations PAPER / s2 search QUERY (+s2 version). 공용 플래그 --limit/--offset/--json/--fields, 검색 전용 --year(예: 2025-2026). 기본 limit 20, search 최대 100, refs/citations 최대 1,000. --all 없음 — stderr의 # more 표시를 보고 --offset으로 재실행. citations는 offset+limit ≤ 9999 상한(고인용 논문 완전 열거 불가를 명시).[1]
  • PAPER 식별자: 제목(따옴표), arXiv ID(신구), DOI, 40자 S2 ID, 접두 ID(ARXIV:/DOI:/CorpusId:/PMID:/URL:), URL. 제목 매칭 시 최근접 제목 결과의 제목·ID·arXiv ID·스코어를 stderr 헤더로 출력 — 잘못된 매칭이 눈에 보이게 하고, 틀리면 ID로 재실행하도록 유도(Skill은 특정 논문 해석을 search로 대체하지 말라고 금지).[1][2]
  • 출력: 무손실 TSV(paperId/year/cites/arxiv/title) 또는 --json(schema_version v1 래퍼로 원본 페이로드 보존, search는 abstract 포함). exit code 계약: 0 성공 / 2 usage·키 문제 / 3 네트워크·레이트리밋 / 4 미발견·응답 이상.[1]

아키텍처 (정적 검사)

  • Python 패키지 src/s2_cli/: cli.py(파서)·resolve.py(PAPER 해석)·transport.py(API 호출) + tests/test_cli.py. 설치는 uv tool install git+.../pipx, Python ≥3.10. 버전 0.1.0(pyproject).[2]
  • 윤리적 호출 방침: x-api-key 헤더(S2_API_KEY 또는 PWC_SEMANTIC_SCHOLAR_API_KEY 필수), 기본 1.5초 요청 간격(S2_REQUEST_DELAY), HTTP 429의 Retry-After 준수, UA s2-cli/<version>. 과거 백필용 보조 키는 절대 읽지 않음.[1]
  • Skill 규약: “CLI 사용 가능하면 api.semanticscholar.org를 curl하지 않는다”, 클래식/최근 슬라이스를 별도 검색으로 구분해 한 검색을 양쪽으로 취급하지 않음, 유명 논문 인용을 상한까지 페이징하지 않음 등 연구 워크플로 지침 내장.[2]

버전·라이선스·출처

  • 라이선스: Apache-2.0 (LICENSE, 10,196 bytes).[3]
  • 버전: GitHub Releases/태그 미사용 — pyproject.toml 0.1.0이 유일한 버전 표기.[2]
  • 수집 시점 관측값: stars 12 · forks 0 · Python · created 2026-08-20(신생) · pushed 당일(2026-08-25). homepage 없음.[4]

정적 검사 한계

  • 설치·실제 API 호출(유료/키 필요)·pytest를 실행하지 않았다. 동작은 README/SKILL.md 서술 의존, confidence: medium.
  • 신생 저장소(생성 약 1주일)라 인터페이스 변동 가능성 있음 — Skill 스스로 “live parser가 이 skill과 불일치하면 파서가 authoritative”라고 명시.[2]

관련 위키

Sources

[1] https://github.com/huggingface/s2-cli — README (고정 커밋 63dba8bc…, 원본 캡처: raw/articles/2026-08-25-github-huggingface-s2-cli.md) [2] https://github.com/huggingface/s2-cli/blob/main/SKILL.md — 에이전트 Skill 문서 (동일 커밋) [3] https://github.com/huggingface/s2-cli/blob/main/LICENSE — Apache-2.0 [4] https://api.github.com/repos/huggingface/s2-cli — GitHub REST API (stars/forks/license/created/pushed, 2026-08-25 수집)