Metadata-Version: 2.5
Name: kwcli
Version: 1.0.3
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

# 키움증권 CLI (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 overseas stocks info --exchange NASDAQ --code AAPL --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 revoke [--profile NAME | --mode demo|real]
kiwoomcli auth clear [--profile NAME | --mode demo|real] [--all]
kiwoomcli auth remove <alias>
kiwoomcli auth export [--profile NAME | --mode demo|real] [--dir DIR] [--yes]
```

- `auth clear`는 비밀 정보만 삭제합니다(기본은 토큰 캐시, `--all`을 주면 OS에 저장된 App Key / Secret까지). 별칭 등록 자체는 유지됩니다.
- `auth remove <alias>`는 계정을 완전히 등록 해제합니다(프로필 항목, 토큰 캐시, 저장된 자격 증명 모두).
- `auth revoke`는 서버에서 현재 토큰을 폐기하고 로컬 토큰 캐시도 삭제합니다.
- `auth export`는 저장된 App Key/Secret을 화면에 출력하지 않고 `.env` 파일로 내보냅니다. 비대화형 환경에서는 `--yes`가 필요합니다.

## 명령 그룹

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

```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 <테마그룹코드> --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` |

미국주식 리소스는 `overseas` 아래에서 제공합니다.

| 그룹 | 예시 |
| --- | --- |
| `stocks` | `kiwoomcli overseas stocks info --exchange NASDAQ --code AAPL` |
| `quotes` | `kiwoomcli overseas quotes info --exchange NASDAQ --code AAPL` |
| `orderbooks` | `kiwoomcli overseas orderbooks list --exchange NASDAQ --code AAPL` |
| `candles` | `kiwoomcli overseas candles stock-daily --exchange NASDAQ --code AAPL` |
| `rankings` | `kiwoomcli overseas rankings today-volume-top --exchange nasdaq` |
| `sectors` | `kiwoomcli overseas sectors period-returns --exchange NASDAQ` |
| `investment-info` | `kiwoomcli overseas investment-info research --kind stock` |
| `accounts` | `kiwoomcli overseas accounts balance --exchange NASDAQ` |
| `orders` | `kiwoomcli overseas orders orderable-quantity --exchange NASDAQ --code AAPL --price 150` |
| `exchange` | `kiwoomcli overseas exchange rate --direction krw-to-usd` |
| `streams` | `kiwoomcli overseas streams trades --exchange NASDAQ --code AAPL --count 1` |

전체 API 337개(OAuth 2, 국내주식 206, 미국주식 129)가 로컬 스펙과 CLI 맵에 포함됩니다. 정확한 옵션은 각 명령의 `-h` 출력으로 확인하세요.

미국주식 `--exchange` 값의 대소문자는 명령별 API 계약을 따릅니다. 종목·시세· 호가·캔들·계좌·스트림은 `AMEX|NASDAQ|NYSE`, 순위는 `all|nyse|nasdaq|amex`, 업종의 `period-returns`는 `ALL|NYSE|AMEX|NASDAQ`을 사용합니다. 항상 해당 명령의 `-h`를 확인하세요.

## 출력 형식

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

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

- `pretty`(기본값)는 사람이 읽기 좋은 들여쓰기 형식입니다.
- `json`은 에이전트가 파싱하기 좋은 한 줄 압축 출력입니다.
- `jsonl`은 한 줄에 JSON 레코드 하나씩 출력합니다(목록 행이나 스트림에 유용).
- `yaml`은 YAML 형식으로 출력합니다.
- `--pages`는 REST 연속조회 페이지 수입니다. 기본값은 1이며, 0은 서버가 제공하는 모든 페이지를 조회합니다. `spec` 명령에는 적용되지 않습니다.
- REST 명령의 `--named`는 응답 필드 코드를 스펙의 한글명으로 변환합니다.

안전장치가 적용된 계좌/주문 조회와 스트림에서는 출력 계층이 계좌 식별자를 마스킹합니다. 다만 주문번호(`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
kiwoomcli overseas streams trades --exchange NASDAQ --code AAPL --count 1 --named --format json
```

- `--count`는 `REAL` 데이터 메시지만 셉니다. `REG`/`REMOVE`/`SYSTEM`은 제어 메시지입니다.
- `--check`는 유한한 등록/수집을 수행하며, `REAL` 틱이 오지 않아도 정상 종료합니다.
- 스트림 명령의 `--named`는 키움 스펙 기반 내장 스키마로 `REAL` 프레임 FID를 변환합니다. 알 수 없는 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-*`)과 미국주식 환전 신청(`overseas exchange request`)에는 안전장치가 적용됩니다.

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

## 용어

각 옵션 이름은 키움 원본 필드명 대신 안정적인 사용자 대상 이름으로 노출됩니다. 구체적으로 어떤 코드를 넣어야 하는지는 명령마다 다릅니다.

| 개념 | 옵션 | 예시 |
| --- | --- | --- |
| 종목/주식/업종/ETF/ELW 코드 | `--code` | `--code 005930` |
| 인증 프로필 | `--profile` | `--profile demo-main` |
| 실행 모드 | `--mode` | `--mode demo` |
| 시장/거래소 선택 | `--market` | `--market kospi` |
| 수량 | `--qty` | `--qty 10` |
| 가격 | `--price` | `--price 70000` |
| 매수/매도 구분 | `--side` | 명령별 값은 `-h`에서 확인 |
| 주문 유형 | `--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는 결과를 지어내지 않고 차단됨/미실행으로 보고합니다.

## 알려진 제약

- 국내 주문 취소(`domestic orders cancel`)는 `--qty`로 수량 일부만 취소할 수 있지만, 해외 주문 취소(`overseas orders cancel`)는 **전량만** 가능합니다. 해외 주문 정정(`overseas orders modify`)은 수량은 바꿀 수 없고 **가격만** 바꿀 수 있습니다(원주문이 STOP 주문이면 `--stop-price` 필수).
- `domestic orders list-open`의 `--exchange`는 주문용 값인 `SOR`을 받지 않습니다 — `ALL`로 조회하세요. `overseas accounts open-orders`는 `--exchange`를 `--code` 없이 받지 않습니다(서버 제약) — 종목을 지정하지 않는 미체결 조회는 거래소 없이 전체로 조회하세요.
- 너무 짧은 간격으로 연속 조회하면 유량 제한(429) 오류가 날 수 있습니다. 반복 호출에는 간격을 두세요.
- 모의투자(demo) 계좌에서는 환율 조회, 주문가능금액 조회가 거절됩니다(실전 계좌에서만 가능).
- 계좌마다 거래할 수 있는 시장이 다를 수 있습니다. 해당 계좌가 다루지 않는 시장은 주문이 거절되거나 조회 결과가 오류 없이 빈 목록으로 돌아올 수 있으므로, 결과가 비어 있다면 먼저 `--profile`/`--mode`로 선택한 계좌를 확인하세요. 장 운영 시간이 아닐 때 국내 주문을 시도하면 이와는 다른 이유(장 종료)로 거절됩니다.
- 현재가 조회(`domestic quotes price`) 응답에는 전일대비 값이 직접 포함되어 있지 않습니다 — 현재가와 전일 종가의 차이로 직접 계산해야 합니다.
- `auth list`/`auth status`는 `--format json`을 지원하지 않고 사람이 읽는 텍스트만 출력합니다.
- 일부 계좌 조회 명령(`accounts valuation`/`accounts holdings`)에는 `--named`가 없어, 응답 필드가 키움 원본 코드로 나옵니다.
