krx-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Jung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# krx-cli
+
+AI 에이전트를 위한 KRX(한국거래소) Open API CLI 도구입니다.
+
+Claude Code, GPT, Cursor 등의 AI 에이전트가 Bash tool을 통해 한국 주식시장 데이터를 조회할 수 있습니다.
+
+## 특징
+
+- **Agent-Native**: JSON 출력 기본, 시맨틱 exit code, 스키마 인트로스펙션
+- **전체 시장 커버리지**: 지수, 주식, ETF/ETN/ELW, 채권, 파생상품, 일반상품, ESG (31개 엔드포인트)
+- **안전한 사용**: 입력 검증, rate limit 추적, dry-run 지원
+- **서비스 승인 관리**: API별 승인 상태 자동 확인
+
+## 설치
+
+```bash
+npm install -g krx-cli
+```
+
+## 설정
+
+### 1. API 키 발급
+
+[KRX Open API 포털](https://openapi.krx.co.kr/)에서 회원가입 후 API 키를 발급받습니다.
+
+### 2. API 키 등록
+
+```bash
+krx auth set <your-api-key>
+
+# 또는 환경변수 사용
+export KRX_API_KEY=<your-api-key>
+```
+
+### 3. 서비스 승인 확인
+
+KRX Open API는 카테고리별로 별도 승인이 필요합니다.
+
+```bash
+krx auth status
+```
+
+```json
+{
+  "api_key_set": true,
+  "services": {
+    "index": { "approved": true },
+    "stock": { "approved": true },
+    "etp": { "approved": true },
+    "bond": { "approved": true },
+    "derivative": { "approved": true },
+    "commodity": { "approved": true },
+    "esg": { "approved": false, "error": "Unauthorized API Call" }
+  }
+}
+```
+
+## 사용법
+
+### 지수 조회
+
+```bash
+krx index list --date 20250307 --market kospi
+krx index list --date 20250307 --market kosdaq
+```
+
+### 주식 조회
+
+```bash
+krx stock list --date 20250307 --market kospi
+krx stock list --date 20250307 --market kosdaq
+krx stock info --market kospi
+```
+
+### ETF/ETN/ELW 조회
+
+```bash
+krx etp list --date 20250307 --type etf
+krx etp list --date 20250307 --type etn
+```
+
+### 채권 조회
+
+```bash
+krx bond list --date 20250307 --market kts
+krx bond list --date 20250307 --market general
+```
+
+### 파생상품 조회
+
+```bash
+krx derivative list --date 20250307 --type futures
+krx derivative list --date 20250307 --type options
+```
+
+### 일반상품 조회
+
+```bash
+krx commodity list --date 20250307 --type gold
+krx commodity list --date 20250307 --type oil
+```
+
+### ESG 조회
+
+```bash
+krx esg list --date 20250307 --type index
+krx esg list --date 20250307 --type sri-bond
+```
+
+### 스키마 조회
+
+```bash
+krx schema --all
+krx schema stock.stk_bydd_trd
+```
+
+## 글로벌 옵션
+
+| 옵션 | 설명 | 기본값 |
+|------|------|--------|
+| `-o, --output <format>` | 출력 형식: json, table, ndjson | json (파이프) / table (터미널) |
+| `-f, --fields <fields>` | 출력 필드 필터 (쉼표 구분) | 전체 |
+| `--dry-run` | API 호출 없이 요청 내용 출력 | - |
+| `-v, --verbose` | 상세 로그 (stderr) | - |
+
+## Exit Codes
+
+| 코드 | 의미 |
+|------|------|
+| 0 | 성공 |
+| 1 | 일반 오류 |
+| 2 | 사용법 오류 (잘못된 인자) |
+| 3 | 데이터 없음 |
+| 4 | 인증 실패 |
+| 5 | Rate limit 초과 (일 10,000건) |
+| 6 | 서비스 미승인 |
+
+## AI 에이전트 연동
+
+### Claude Code
+
+SKILL.md 파일을 프로젝트에 포함하면 Claude Code가 자동으로 사용법을 인식합니다.
+
+```bash
+# Claude Code에서 바로 사용 가능
+krx stock list --date 20250307 --market kospi --fields ISU_NM,TDD_CLSPRC,FLUC_RT -o json
+```
+
+## 개발
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm typecheck
+pnpm lint
+```
+
+## 라이선스
+
+MIT

package/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: krx-cli
+description: Query KRX (Korea Exchange) market data via CLI
+required_env:
+  - KRX_API_KEY
+install: npm install -g krx-cli
+binary: krx
+invariants:
+  - Always use YYYYMMDD format for --date (e.g., 20250307)
+  - Data is T-1 (previous trading day), available from 2010 onwards
+  - Default output is JSON to stdout, errors go to stderr
+  - Rate limit is 10,000 API calls per day
+  - Each API category requires separate approval from KRX
+  - All response field values are strings (including numbers)
+---
+
+# krx-cli
+
+Agent-native CLI for querying KRX (Korea Exchange) Open API data.
+
+## Setup
+
+```bash
+# Install
+npm install -g krx-cli
+
+# Set API key (get from https://openapi.krx.co.kr/)
+krx auth set <your-api-key>
+
+# Check which services are approved
+krx auth status
+```
+
+## Commands
+
+### Authentication
+
+```bash
+krx auth set <api-key>       # Save API key
+krx auth status               # Check all service approvals (JSON)
+krx auth check <category>     # Check specific category: index, stock, etp, bond, derivative, commodity, esg
+```
+
+### Index (지수)
+
+```bash
+krx index list --date 20250307 --market kospi     # KOSPI index
+krx index list --date 20250307 --market kosdaq     # KOSDAQ index
+krx index list --date 20250307 --market krx        # KRX index
+krx index list --date 20250307 --market bond       # Bond index
+krx index list --date 20250307 --market derivative # Derivative index
+```
+
+### Stock (주식)
+
+```bash
+krx stock list --date 20250307 --market kospi   # KOSPI stocks
+krx stock list --date 20250307 --market kosdaq   # KOSDAQ stocks
+krx stock list --date 20250307 --market konex    # KONEX stocks
+krx stock info --market kospi                     # Stock base info
+```
+
+### ETP (ETF/ETN/ELW)
+
+```bash
+krx etp list --date 20250307 --type etf   # ETF
+krx etp list --date 20250307 --type etn   # ETN
+krx etp list --date 20250307 --type elw   # ELW
+```
+
+### Bond (채권)
+
+```bash
+krx bond list --date 20250307 --market kts       # Government bonds
+krx bond list --date 20250307 --market general    # General bonds
+krx bond list --date 20250307 --market small      # Small bonds
+```
+
+### Derivative (파생상품)
+
+```bash
+krx derivative list --date 20250307 --type futures          # Futures
+krx derivative list --date 20250307 --type options           # Options
+krx derivative list --date 20250307 --type futures-kospi     # KOSPI stock futures
+krx derivative list --date 20250307 --type futures-kosdaq    # KOSDAQ stock futures
+krx derivative list --date 20250307 --type options-kospi     # KOSPI stock options
+krx derivative list --date 20250307 --type options-kosdaq    # KOSDAQ stock options
+```
+
+### Commodity (일반상품)
+
+```bash
+krx commodity list --date 20250307 --type gold       # Gold
+krx commodity list --date 20250307 --type oil         # Oil
+krx commodity list --date 20250307 --type emission    # Emission trading
+```
+
+### ESG
+
+```bash
+krx esg list --date 20250307 --type index       # ESG index
+krx esg list --date 20250307 --type etp          # ESG ETP
+krx esg list --date 20250307 --type sri-bond     # SRI bonds
+```
+
+### Schema (introspection)
+
+```bash
+krx schema --all              # All 31 endpoint schemas (JSON)
+krx schema index.kospi_dd_trd # Specific endpoint schema
+```
+
+## Global Flags
+
+```
+--output, -o <format>    json (default) | table | ndjson
+--fields, -f <fields>    Filter output fields: --fields ISU_NM,TDD_CLSPRC,FLUC_RT
+--dry-run                Show request details without calling API
+--verbose, -v            Verbose logging to stderr
+```
+
+## Exit Codes
+
+```
+0 = Success
+1 = General error
+2 = Usage error (bad arguments)
+3 = No data found
+4 = Auth failure (no/invalid API key)
+5 = Rate limit exceeded (10,000/day)
+6 = Service not approved (category not activated)
+```
+
+## Common Patterns
+
+### Get KOSPI closing price for a specific date
+
+```bash
+krx index list --date 20250307 --market kospi --fields IDX_NM,CLSPRC_IDX,FLUC_RT
+```
+
+### Get Samsung Electronics stock price
+
+```bash
+krx stock list --date 20250307 --market kospi --fields ISU_NM,TDD_CLSPRC,FLUC_RT | jq '.[] | select(.ISU_NM == "삼성전자")'
+```
+
+### Check API availability before querying
+
+```bash
+krx auth status -o json
+```
+
+### Dry run to verify request
+
+```bash
+krx stock list --date 20250307 --market kospi --dry-run
+```
+
+## Key Response Fields
+
+### Stock / Index common fields
+- `BAS_DD` - Date (YYYYMMDD)
+- `ISU_NM` / `IDX_NM` - Name
+- `TDD_CLSPRC` / `CLSPRC_IDX` - Closing price
+- `CMPPREVDD_PRC` / `CMPPREVDD_IDX` - Change from previous day
+- `FLUC_RT` - Change rate (%)
+- `TDD_OPNPRC` / `OPNPRC_IDX` - Opening price
+- `TDD_HGPRC` / `HGPRC_IDX` - High price
+- `TDD_LWPRC` / `LWPRC_IDX` - Low price
+- `ACC_TRDVOL` - Trading volume
+- `ACC_TRDVAL` - Trading value
+- `MKTCAP` - Market capitalization