Metadata-Version: 2.4
Name: kwcli
Version: 0.1.1
Summary: Kiwoom OpenAPI toolkit
License-File: LICENSE.md
Requires-Python: >=3.13
Requires-Dist: keyring>=25.7.0
Requires-Dist: pandas>=3.0.3
Requires-Dist: platformdirs>=4.9.4
Requires-Dist: requests>=2.33.1
Requires-Dist: websockets>=15.0.1
Description-Content-Type: text/markdown

# Kiwoom CLI

`kiwoomcli`는 키움증권 OpenAPI를 위한 커맨드라인 클라이언트입니다. 터미널에서
키움 OpenAPI 데이터를 조회하고, 인증 상태를 관리하며, 안전장치가 적용된 주문
작업을 수행해야 하는 사람과 AI 에이전트를 위한 **탐색(discovery) 중심**의 운영
도구입니다.

배포 패키지 이름은 `kwcli` 이며, 설치 후 사용하는 콘솔 명령은 `kiwoomcli` 입니다.

> **키움증권 공식 프로젝트**
> 본 프로젝트는 **키움증권(Kiwoom Securities)이 공식적으로 제공·관리**하는 도구입니다.
> PyPI 패키지 [`kwcli`](https://pypi.org/project/kwcli/)는 키움증권이 게시한 공식 배포본입니다.
> 키움 REST API 공식 포털: <https://openapi.kiwoom.com> (API 가이드: <https://openapi.kiwoom.com/guide/apiguide>)

## 설치

```sh
uv tool install kwcli
# 또는
pipx install kwcli
# 또는
pip install kwcli
```

설치한 뒤 계정과 자격 증명을 초기화합니다.

```sh
kiwoomcli setup
```

## 빠른 시작

일상적인 흐름은 **먼저 탐색하고, 그다음 명령 하나를 실행**하는 것입니다. 어떤
명령이든 `-h`를 붙이면 실시간으로 매핑된 계약 정보(요약 / 동작 / 예시 / OpenAPI
매핑)를 볼 수 있습니다.

```sh
kiwoomcli setup                                   # 온보딩: 별칭, demo/real, 키, 검증
kiwoomcli spec search "체결"                       # 필요한 API/명령 찾기
kiwoomcli domestic stocks info --code 005930 -h   # 매핑된 계약 확인
kiwoomcli domestic stocks info --code 005930 --format json
kiwoomcli domestic orders buy --code 005930 --qty 1 --price 70000 --order-type limit --confirm
```

전체 명령 목록을 외우기보다는, 평소에는 `spec search`와 `-h`를 활용하세요.

## 인증과 프로필

- `kiwoomcli setup`은 온보딩 초기화 명령입니다. 환경 사전 점검(OS 자격 증명
  저장소 사용 가능 여부와 PATH 모호성 경고)을 수행하고, 계정 별칭을 만들며,
  `demo`/`real`을 선택하고, App Key / Secret을 저장한 뒤, 안전한 읽기 전용
  호출로 검증하고, 현재 프로필을 지정한 다음 준비 상태 요약을 출력합니다.
  비대화형 셸에서는 멈추지 않고 안내 메시지와 함께 실패합니다(`--mode` 전달).
- `kiwoomcli doctor`는 읽기 전용 진단 명령입니다. 어떤 인증 컨텍스트가
  선택됐는지(우선순위 `--profile`/`KIWOOM_PROFILE` > `--mode`/`KIWOOM_MODE` >
  현재 프로필), 프로필별 자격 증명/토큰 상태, 권장 조치를 보여줍니다.
- `--profile NAME`은 저장된 계정 별칭(OS 자격 증명 저장소의 App Key / Secret)을
  사용합니다. `--mode demo|real`은 저장된 별칭을 쓰지 않으며, mode 단독 실행에는
  환경변수가 필요합니다. 이때 환경변수 이름은 모드별로 다릅니다 —
  `real`은 `APP_KEY` / `APP_SECRET`, `demo`는 `APP_KEY_MOCK` / `APP_SECRET_MOCK`.
  자격 증명이 없을 때는 진입 방식에 맞는 해결책을 함께 안내합니다.

자주 쓰는 인증 명령:

```sh
kiwoomcli auth login [--alias NAME] [--mode demo|real]
kiwoomcli auth list
kiwoomcli auth switch <alias>
kiwoomcli auth status [--profile NAME | --mode demo|real]
kiwoomcli auth refresh [--profile NAME | --mode demo|real]
kiwoomcli auth clear [--profile NAME | --mode demo|real] [--all]
kiwoomcli auth remove <alias>
```

- `auth clear`는 비밀 정보만 삭제합니다(기본은 토큰 캐시, `--all`을 주면 OS에
  저장된 App Key / Secret까지). 별칭 등록 자체는 유지됩니다.
- `auth remove <alias>`는 계정을 완전히 등록 해제합니다(프로필 항목, 토큰 캐시,
  저장된 자격 증명 모두).

## 명령 그룹

탐색 명령은 패키지에 포함된 로컬 스펙을 읽습니다(네트워크 불필요).

```sh
kiwoomcli spec search <query> [--limit N]
kiwoomcli spec show <api-id> [--format pretty|json|yaml]
kiwoomcli spec groups [--format pretty|json|yaml]
kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
```

국내 리소스 명령은 주제별 그룹으로 나뉩니다. 대표 예시는 아래와 같습니다(어떤
명령이든 `-h`를 붙이면 전체 옵션 계약을 볼 수 있습니다).

| 그룹 | 예시 |
| --- | --- |
| `stocks` | `kiwoomcli domestic stocks info --code 005930` |
| `quotes` | `kiwoomcli domestic quotes price --code 005930` |
| `orderbooks` | `kiwoomcli domestic orderbooks list --code 005930` |
| `candles` | `kiwoomcli domestic candles daily --code 005930 --date 20260529` |
| `rankings` | `kiwoomcli domestic rankings amount --market all --include-managed no --exchange KRX` |
| `sectors` | `kiwoomcli domestic sectors price --market kospi --code 001` |
| `etfs` | `kiwoomcli domestic etfs info --code 069500` |
| `elws` | `kiwoomcli domestic elws daily --code 57JBHH` |
| `investors` | `kiwoomcli domestic investors by-stock --code 005930` |
| `short-selling` | `kiwoomcli domestic short-selling trend --code 005930 --from 20260101 --to 20260529` |
| `securities-lending` | `kiwoomcli domestic securities-lending by-stock --code 005930` |
| `themes` | `kiwoomcli domestic themes by-stock --code 005930 --exchange KRX` |
| `accounts` | `kiwoomcli domestic accounts holdings --basis total --exchange KRX` |
| `orders` | `kiwoomcli domestic orders list-open --stock-scope all --side all --exchange ALL` |
| `streams` | `kiwoomcli domestic streams trades --code 005930 --count 1` |

## 출력 형식

도메인 명령은 `--format`과 프로필/모드 선택자를 받습니다.

```sh
--format pretty|json|jsonl|yaml
--profile NAME
--mode demo|real
```

- `pretty`(기본값)는 사람이 읽기 좋은 들여쓰기 형식입니다.
- `json`은 에이전트가 파싱하기 좋은 한 줄 압축 출력입니다.
- `jsonl`은 한 줄에 JSON 레코드 하나씩 출력합니다(목록 행이나 스트림에 유용).
- `yaml`은 YAML 형식으로 출력합니다.

안전장치가 적용된 계좌/주문 조회와 스트림에서는 출력 계층이 계좌 식별자를
마스킹합니다. 다만 주문번호(`ord_no`, `orig_ord_no` 등)는 `orders modify`/`cancel`
에 필요하므로 **마스킹하지 않습니다**. 마스킹은 `pretty`, `json`, `jsonl`, `yaml`
전반에서 동일하게 적용됩니다.

## 스트리밍 (WebSocket)

스트림 명령은 포그라운드에서 실행되며 키움 서버 메시지를 출력합니다. 유한한
실행을 원하면 `--count`/`--duration`을 사용하세요.

```sh
kiwoomcli domestic streams trades --code 005930 --count 1 --named --format json
```

- `--count`는 `REAL` 데이터 메시지만 셉니다. `REG`/`REMOVE`/`SYSTEM`은 제어
  메시지입니다.
- `--check`는 유한한 등록/수집을 수행하며, `REAL` 틱이 오지 않아도 정상 종료
  합니다.
- `--named`는 패키지에 포함된 키움 스펙 기반 내장 스키마로 `REAL` 프레임을
  변환합니다. 알 수 없는 FID는 `unknown` 아래에 보존됩니다.

장시간 구독을 저장하려면 파일로 출력하고 OS 도구로 프로세스를 백그라운드로
돌리세요(CLI는 자체 작업 관리자를 제공하지 않습니다).

```sh
# 계속 수신하며 이벤트를 파일에 추가 기록
kiwoomcli domestic streams trades --codes 005930,000660 --watch --format jsonl --output trades.jsonl

# Linux/macOS: 터미널을 닫아도 계속 실행
nohup kiwoomcli domestic streams trades --codes 005930,000660 --watch --output trades.jsonl &

# Windows PowerShell: 분리된 프로세스로 실행
Start-Process kiwoomcli -ArgumentList 'domestic streams trades --codes 005930,000660 --watch --output trades.jsonl'
```

조건검색식의 생성과 수정은 키움 영웅문 HTS에서 합니다. CLI는 HTS에 이미 저장된
조건식을 목록 조회, 선택, 조회, 구독, 해제만 합니다.

## 주문 안전장치

주문 쓰기 명령(`orders buy/sell/modify/cancel`, `credit-*`, `gold-*`)에는
안전장치가 적용됩니다.

- `--confirm`이 없으면 짧은 미전송 주문 요약을 출력하고 주문 API를 호출하지
  않습니다.
- `--confirm`이 있으면 실제 엔드포인트로 전송합니다.
- 주문 유형별 가격 규칙은 전송 경로 이전에 검증됩니다. 예를 들어
  `--order-type limit`에는 `--price`가 필요하고, `--order-type market`에는
  `--price`를 넣으면 안 됩니다. 잘못된 주문 식별자는 전송 전에 보고됩니다.
- 주문 쓰기는 `--profile`/`--mode`로 인증 대상을 선택합니다. 먼저 데모(모의투자)
  서버에서 검증하세요.

## 용어

안정적인 사용자 대상 옵션 이름이 키움 원본 필드명을 숨깁니다. 구체적인 코드
종류는 명령 맥락에 따라 결정됩니다.

| 개념 | 옵션 | 예시 |
| --- | --- | --- |
| 종목/주식/업종/ETF/ELW 코드 | `--code`, `-c` | `--code 005930` |
| 인증 프로필 | `--profile` | `--profile demo-main` |
| 실행 모드 | `--mode` | `--mode demo` |
| 시장/거래소 선택 | `--market` | `--market kospi` |
| 수량 | `--qty` | `--qty 10` |
| 가격 | `--price` | `--price 70000` |
| 매수/매도 구분 | `--side` | `--side buy` |
| 주문 유형 | `--order-type` | `--order-type limit` |
| 주문 식별자 | `--order-id` | `--order-id 123` |
| 시작 / 종료 일자 | `--from` / `--to` | `--from 20260101 --to 20260529` |
| 단일 기준 일자 | `--date` | `--date 20260529` |
| 분 단위 간격 | `--interval` | `--interval 1` |
| 결과 개수 | `--limit` | `--limit 200` |
| 출력 형식 | `--format` | `--format json` |
| 쓰기 확인 | `--confirm` | `--confirm` |

## 안전 유의사항

- 개발과 검증 단계에서는 `demo` 모드를 우선 사용하세요.
- 자격 증명, 토큰, 계좌번호, 정제되지 않은 실제 호출 출력은 절대 로그로 남기거나
  커밋하지 마세요.
- 자격 증명·네트워크·계좌 안전 제약으로 실제 호출이 막히면, CLI는 결과를
  지어내지 않고 차단됨/미실행으로 보고합니다.
