kwcli 0.1.1

Kiwoom OpenAPI toolkit

Kiwoom CLI

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

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

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

설치

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

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

kiwoomcli setup

빠른 시작

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

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. 자격 증명이 없을 때는 진입 방식에 맞는 해결책을 함께 안내합니다.

자주 쓰는 인증 명령:

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>는 계정을 완전히 등록 해제합니다(프로필 항목, 토큰 캐시, 저장된 자격 증명 모두).

명령 그룹

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

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과 프로필/모드 선택자를 받습니다.

--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을 사용하세요.

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

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

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

# 계속 수신하며 이벤트를 파일에 추가 기록
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는 결과를 지어내지 않고 차단됨/미실행으로 보고합니다.