kbo-cli

터미널에서 KBO 경기를 가볍게 관전하는 standalone TUI CLI. 점수 · 이닝 · 카운트 · 주자 · 최근 플레이를 ANSI 그래픽으로 표시하고 watch 모드에서 한 자리에서 갱신된다.

설치

# 일회 실행
npx kbo today
npx kbo watch

# 전역 설치
npm i -g kbo-cli
kbo today
kbo watch

요구사항: Node ≥ 18.

사용

kbo                                      # 기본 명령 (kbo config 의 "기본 명령"), 미설정이면 도움말
kbo today --date 2026-05-01
kbo watch                                # 진행중 경기 라이브
kbo watch --team LG
kbo watch --game 20260501NCLG02026 --interval 3
kbo status --team LG                     # 한 줄 요약 (statusline 용)
kbo stats                                # 팀 순위 (←/→ 정렬 전환)
kbo stats batting                        # 타자 리더보드
kbo stats pitching                       # 투수 리더보드
kbo config                               # 즐겨찾기 팀 / 폴링 간격 / 기본 명령 / 레이아웃 (인터랙티브)
kbo --layout compact watch --team LG     # 강제 레이아웃 (auto/compact/normal/wide)
kbo --help

좁은 터미널 (분할/세로 모드) 에선 자동으로 compact 모드로 다이아몬드와 카운트가 한 줄로 줄어들고, 넓은 환경에선 좌우 2단 wide 로 타자·투수 정보와 최근 플레이가 함께 보인다. 임계값은 80 / 120 컬럼이며, --layout 또는 kbo config 의 "레이아웃" 항목으로 강제할 수 있다.

개발

git clone https://github.com/jeonbyeongmin/kbo-cli
cd kbo-cli
bun install
bun run dev                              # = bun run src/index.ts
bun run build                            # → dist/kbo.js

요구사항: Bun ≥ 1.0 (curl -fsSL https://bun.sh/install | bash)

라이브/통계 화면 키

| 키 | 동작 | | ----------- | ----------------------------------------------------------------------------- | | q | 종료 | | r | 즉시 새로고침 | | ← → | watch: 진행중 경기 전환 · stats: 정렬/카테고리 전환 · config: 값 변경 | | ↑ ↓ | watch: 중계 영역 스크롤백 · stats 순위: 뷰(기본/공격/수비) · stats 리더보드: 행 스크롤 · config: 항목 이동 | | h l | stats: 컬럼 가로 스크롤 (좁은 폭에서 ◂/▸ 표시 시) | | t | stats 리더보드: 팀 필터 cycling (전체 ↔ 각 팀) | | s Enter | config: 저장 후 종료 | | Ctrl+C | 종료 |

statusline 통합

kbo status 는 풀 TUI 가 아니라 한 줄 ANSI 출력만 stdout 에 찍고 종료한다. tmux/starship/Sketchybar 같은 외부 statusline 에 끼워넣을 수 있다. 응답은 ~/.cache/kbo-cli/ (또는 $XDG_CACHE_HOME/kbo-cli/) 에 30초간 캐시되어, 호출자가 5초마다 호출해도 실제 API 는 30초당 1회 이하로만 때린다.

kbo status --team LG     # 라이브:  LG 4 - 2 NC · 7회말 1사 1·3루 · 타: 오스틴
kbo status               # --team 생략 시 즐겨찾기 팀 (kbo config)

종료 코드로 호출자가 상태를 분기할 수 있다 — 0 라이브/시작 전, 2 오늘 경기 없음, 3 종료, 1 에러.

tmux 예시:

set -g status-right "#(kbo status --team LG)"
set -g status-interval 5

출력은 항상 풀 정보(점수 · 이닝 · 카운트 · 주자 · 타자/투수)다. 좁은 statusline 에서는 호출자 측에서 잘라 쓰는 걸 권한다. 팀명은 kbo config 표기와 동일해야 한다 (LG, 두산, KIA, KT, 삼성, 한화, SSG, 롯데, NC, 키움).

데이터 소스

Naver Sports 비공식 게이트웨이 (api-gw.sports.naver.com):

• 일정: /schedule/games?upperCategoryId=kbaseball&date=YYYY-MM-DD
• 라이브: /schedule/games/{gameId}/relay
• 순위: /statistics/categories/kbo/seasons/{seasonCode}/teams
• 리더보드: /statistics/categories/kbo/seasons/{seasonCode}/top-players?playerType=HITTER|PITCHER
• 팀 로스터: /statistics/categories/kbo/seasons/{seasonCode}/players?playerType=...&field=...&direction=...&teamCode=...

비공식이라 무공지 변경 위험이 있다. 응답 구조가 깨지면 --debug 와 watch --debug --game <id> 로 raw JSON 을 덤프해 비교한다.

구조

src/
  index.ts    # CLI 엔트리, 인자 파싱
  api.ts      # Naver 게이트웨이 + 정규화
  types.ts    # 응답/내부 타입
  render.ts   # TUI 레이아웃 (다이아몬드, 스코어, 카운트)
  watch.ts    # 폴링 루프 + alt-screen + 키 입력
  stats.ts    # 순위/리더보드 인터랙티브 표
  oneline.ts  # kbo status 한 줄 렌더 + 게임 픽
  cache.ts    # XDG 기반 파일 캐시 (status 30s TTL)

의존성은 picocolors 단 하나.

면책 / Disclaimer

이 프로젝트는 팬메이드 비공식 도구이며 KBO, 각 구단, 네이버, 통신사 어디와도 무관합니다.

• 데이터를 비공식 게이트웨이에서 조회하므로 사전 공지 없이 동작이 멈출 수 있습니다.
• 개인 학습/관전 용도로만 사용하세요. 상업적 사용/재배포, 데이터 대량 수집, 2차 서비스 구축은 권장하지 않습니다.
• 표시되는 텍스트 중계 문장은 원 출처(네이버/통신사)의 저작물입니다. 본 도구는 단순 표시만 합니다.
• 폴링은 기본 5초(하한 1초)로, 모바일 앱과 비슷한 수준의 호출 빈도를 유지합니다. --interval 을 무리하게 낮추지 말아 주세요.
• 권리자 측에서 takedown 요청이 있을 경우 즉시 응합니다. 이슈로 알려주세요.

라이선스

MIT

kbo-cli