kiwoom-cli

키움증권 REST API 전체를 터미널에서. 시세 조회부터 주문, 실시간 스트리밍, 미국주식까지 명령어 하나로.

uv tool install kiwoom-cli     # 권장
# 또는: pipx install kiwoom-cli
# 또는: pip  install kiwoom-cli

$ kiwoom stock price 005930          # 삼성전자 현재가
$ kiwoom order buy NVDA 10 --price 213.04   # 미국주식도 그대로
$ kiwoom -f json account balance | jq       # AI 에이전트·스크립트 친화

AI-agent native

모든 명령이 -f json에서 하나의 안정된 envelope를 stdout에 출력한다 (진행 메시지는 전부 stderr, stdout은 항상 파싱 가능한 단일 문서):

{"ok": true, "schema": "v1",
 "data": {"symbol": "005930", "price": 70000, "change_direction": "up"},
 "meta": {"profile": "default", "env": "mock", "cont": null},
 "error": null}

data는 타입 있는 정규화 필드(부호 문자열 파싱 불필요), error.code는 안정적인 enum 32종(retryable 포함), exit code는 0=성공 / 1=입력 / 2=API / 3=인증으로 고정된다. 에이전트는 문자열이 아니라 계약으로 분기한다.

주문 안전장치. 에이전트가 돈을 다루는 경로 전체에 가드가 있다:

kiwoom -f json order validate buy 005930 10          # read-only 사전점검
kiwoom -f json order buy 005930 10 --price 70000 --dry-run   # 전송될 body만 확인
kiwoom -f json order buy 005930 10 --price 70000 --confirm --client-order-id run-42
# 같은 키 재실행 → 재전송 없이 이전 응답 (idempotent_replay: true)

--confirm 없이 json 모드로 주문하면 프롬프트에 멈추는 대신 구조화된 CONFIRMATION_REQUIRED 오류로 즉시 반환된다. 에이전트가 걸려서 죽지 않는다.

에이전트 퀵스타트:

price=$(kiwoom -f json --fields price stock info 005930 | jq .data.price)
kiwoom -f json stream quote 005930 --max-events 10           # NDJSON 10줄 후 exit 0
kiwoom stream quote 005930 --record --duration 30m           # 녹화 → history query/export
kiwoom -f json describe order buy                             # 명령 스키마 자기서술

• 기계 계약 전체(envelope·error code·litmus loop): AGENTS.md
• 재현 가능한 증명 스크립트(모의투자): benchmark/litmus.sh
• 공식 CLI(kwcli)와의 정직한 비교: docs/vs-official.md

왜 kiwoom-cli인가

• 236개 API 전체 지원: REST 217개 + WebSocket 실시간 19종. 시세·차트·계좌·주문·순위·업종·테마·ETF·ELW·금현물·미국주식까지 키움 REST API를 빠짐없이 커버합니다.
• 프롬프트 제로: 인증정보는 OS 키체인에 저장되고 어떤 명령도 비밀번호를 묻지 않습니다. gh/aws/docker와 같은 모델. 크론잡, CI, AI 에이전트가 그대로 돌립니다.
• AI 에이전트 퍼스트: 구조화된 JSON 출력(-f json), 일관된 exit code(0/1/2/3), 주문 확인 게이트(--confirm). Claude Code, 자동매매 스크립트에 바로 연결됩니다.
• 미국주식 자동 라우팅: 005930은 국내로, NVDA는 미국으로. 거래소(NASDAQ/NYSE/AMEX)도 자동 판별. 국내+미국 통합 잔고를 원화 총계로 보여줍니다.
• 사람에게도 친절: Rich 테이블, 상승=빨강/하락=파랑 색상, 실시간 TUI 대시보드, shell 자동완성.
• 699개 테스트 + CI: Python 3.10–3.13 매트릭스, CodeQL 정적 분석.

전체 문서는 Wiki에서: 설치 가이드, 명령어 레퍼런스, 미국주식·AI 에이전트·멀티 프로필 가이드, 릴리스 노트.

최근 업데이트

v2.5 에이전트 네이티브: 정규화 데이터·NDJSON 스트리밍·녹화 (2026-07)

-f json의 data가 정규화된 타입 있는 필드로 바뀌고 원본은 data.raw로 이동했습니다 (기존 -f json 소비자에게는 breaking: 기존 키는 data.raw 아래에 그대로 있습니다). 전역 --fields 투영, kiwoom describe 자기서술, NDJSON 스트리밍(--max-events/--duration/--until 종료조건), --record 녹화 + history query/export, AGENTS.md 기계 계약이 추가됐습니다. 위 AI-agent native 섹션 참고.

v2.1 비밀번호 프롬프트 완전 제거 (2026-07)

앱 자체 암호화 계층을 걷어내고 모든 인증정보를 OS 키체인에 직접 저장합니다. config setup, auth login 어디서도 더 이상 비밀번호를 묻지 않습니다. 기존 사용자는 업그레이드 후 kiwoom config setup 한 번만 다시 실행하면 됩니다.

v2.0 미국주식 지원 (2026-07)

미국주식 29개 엔드포인트를 기존 명령 체계에 그대로 통합했습니다. 티커만 입력하면 시장을 자동 판별하므로 미국 주문도 국내 주문과 똑같이 짧습니다. 소수점 가격, stop/stop-limit/vwap/twap 주문유형, 환전(account exchange), 국내+미국 통합 계좌 뷰를 지원합니다.

전체 변경 내역: CHANGELOG · Wiki 릴리스 노트

설치

kiwoom은 라이브러리가 아니라 CLI 도구이므로 격리된 환경에 설치하는 편이 좋습니다. 전역 Python 환경을 건드리지 않아 다른 패키지와 의존성이 충돌하지 않습니다.

# uv (권장) https://docs.astral.sh/uv/
uv tool install kiwoom-cli

# pipx
pipx install kiwoom-cli

# pip: 격리되지 않음
pip install kiwoom-cli

셋 다 kiwoom 명령 하나를 PATH에 노출합니다. Python 3.10–3.13을 지원하고, 인증정보를 다루는 keyring은 격리 환경에서도 OS 키체인 백엔드를 그대로 사용합니다.

설치 없이 한 번만 실행

uvx --from kiwoom-cli kiwoom stock price 005930

패키지 이름은 kiwoom-cli인데 명령 이름은 kiwoom이라서, uvx kiwoom-cli는 동작하지 않습니다. --from으로 패키지와 명령을 따로 지정해야 합니다.

프로젝트 의존성으로 쓰기

봇이나 스크립트에서 kiwoom_cli를 라이브러리로 함께 쓰는 경우:

uv add kiwoom-cli
uv run kiwoom -f json stock info 005930

업그레이드 · 삭제

uv tool upgrade kiwoom-cli      # pipx upgrade kiwoom-cli
uv tool uninstall kiwoom-cli    # pipx uninstall kiwoom-cli

kiwoom이 예전 버전을 가리킬 때

전에 pip install kiwoom-cli를 한 적이 있으면 그때의 실행 파일이 PATH 앞쪽에 남아 새로 설치한 쪽을 가릴 수 있습니다 (pyenv shim이 대표적입니다):

which kiwoom       # 실제로 어떤 실행 파일이 잡히는지
kiwoom --version   # 기대한 버전이 맞는지

버전이 다르면 예전 설치본을 지웁니다:

pip uninstall kiwoom-cli

시작하기

키움증권 REST API에서 appkey/secretkey를 발급받은 뒤:

# 1. 초기 설정 (appkey, secretkey → OS 키체인)
#    토큰 저장 방식도 여기서 선택: keychain (기본) 또는 env (KIWOOM_TOKEN 직접 관리)
kiwoom config setup

# 2. 토큰 발급
kiwoom auth login

# 3. 끝. 이후 모든 명령은 프롬프트 없이 동작
kiwoom stock info 005930

모의투자 vs 실거래

config setup 시 도메인을 선택합니다. 이후 변경:

kiwoom config domain mock   # 모의투자 (기본값, 테스트용)
kiwoom config domain prod   # 실거래

kiwoom config show          # 현재 설정 확인

모의투자는 KRX만 지원됩니다. 실거래 전환 후에는 kiwoom auth login으로 토큰을 재발급하세요.

환경변수 설정

도메인, 계좌번호, 프로필, 토큰은 환경변수로도 설정 가능합니다.

export KIWOOM_DOMAIN="prod"       # prod 또는 mock
export KIWOOM_ACCOUNT="1234567"   # 선택
export KIWOOM_PROFILE="isa"       # 선택
export KIWOOM_TOKEN="..."         # 선택: 키체인 대신 사용할 접근토큰 (샌드박스/CI용)

appkey/secretkey는 보안을 위해 환경변수를 지원하지 않습니다. 반드시 kiwoom config setup으로 OS 키체인에 저장하세요. KIWOOM_TOKEN은 만료·폐기 가능한 접근토큰만 담는 통로로, 키체인에 접근할 수 없는 환경(샌드박스, CI, AI 에이전트)에서 사용합니다. 설정하면 키체인 토큰보다 우선합니다.

토큰 저장 방식 (keychain vs env)

config setup에서 토큰 저장 방식을 선택합니다.

• keychain (기본): auth login이 토큰을 OS 키체인에 저장합니다. 본인 터미널에서 쓰는 일반적인 방식.
• env: 토큰을 키체인에 저장하지 않습니다. auth login이 토큰과 export KIWOOM_TOKEN=... 명령을 출력하면 셸에서 실행하세요. 키체인 접근이 불가능한 환경(샌드박스, CI, 컨테이너)이 주 작업 환경일 때 적합합니다.

이후 전환은 kiwoom config set token_storage keychain|env.

멀티 프로필

계좌별로 다른 appkey/secretkey를 사용할 수 있습니다.

# 프로필별 설정
kiwoom config setup --profile default   # 메인계좌
kiwoom config setup --profile isa       # ISA계좌

# 프로필 설정 변경
kiwoom config set domain prod           # 도메인 변경
kiwoom config set account 1234567       # 계좌번호 설정
kiwoom -p isa config set domain mock    # 특정 프로필

# 프로필 전환 / 목록
kiwoom config use isa
kiwoom config profiles

# 특정 프로필로 사용
kiwoom -p isa account balance
kiwoom -p isa auth login

AI 에이전트와 함께 쓰기

kiwoom-cli는 AI 에이전트가 도구로 쓰는 것을 처음부터 염두에 두고 설계됐습니다.

# 구조화된 JSON: 파싱이 필요 없는 출력
kiwoom -f json stock info 005930
kiwoom -f json market rank volume | jq '.[].stk_nm'

# 일관된 exit code: 0=성공, 1=입력오류, 2=API오류, 3=인증필요
kiwoom stock price 005930 || echo "재시도 또는 재인증"

# 주문은 기본 확인 게이트, 자동화 시에만 --confirm으로 명시적 스킵
kiwoom order buy 005930 10 --type market --confirm

# 주문 3단 안전장치: 사전점검 → dry-run → 멱등 주문
kiwoom -f json order validate buy 005930 10 --price 70000
kiwoom -f json order buy 005930 10 --price 70000 --type limit --dry-run
kiwoom -f json order buy 005930 10 --price 70000 --type limit --confirm --client-order-id run-42

• 어떤 명령도 비밀번호·생체인증을 요구하지 않으므로 에이전트 세션이 중간에 멈추지 않습니다. json/csv 모드에서는 확인 프롬프트 대신 CONFIRMATION_REQUIRED 오류(exit 1)로 응답합니다.
• 페이지네이션(연속조회)은 전역 --all-pages(끝까지 자동 수집·리스트 병합) 또는 --next-key <값>(특정 페이지부터 재조회)로 명시 제어합니다. 커서를 직접 다루지 않아도 됩니다.
• kiwoom describe --paths -f json으로 전체 명령 경로를 저비용에 훑어본 뒤, 필요한 명령만 kiwoom describe <경로> -f json으로 상세 스키마를 조회하세요.
• 테이블 출력은 50행(차트는 30행)에서 잘리며 잘린 경우 안내 문구가 표시됩니다. 전체 데이터가 필요하면 -f json 또는 -f csv를 사용하세요.
• account/market의 옵션 19개(--side sell, --period 1h 등)는 사람이 읽는 이름이 표준이며 기존 숫자 코드(--side 1)도 계속 허용됩니다 (stock 등 나머지 명령의 숫자 옵션은 이번 티어의 범위 밖).
• 자세한 패턴은 Wiki: AI 에이전트 가이드 참고.

명령어/API 찾기

kiwoom find 미체결          # 관련 명령어 + API ID 통합 검색
kiwoom api list             # 전체 217개 REST API 목록
kiwoom api list 주문        # 키워드로 필터

샌드박스 환경 (키체인 접근 불가)

샌드박스 셸, CI, 컨테이너에서는 OS 키체인을 읽을 수 없습니다. 이때는 본인 터미널에서 토큰을 발급받아 KIWOOM_TOKEN으로 전달하세요. appkey/secretkey는 키체인 밖으로 나가지 않고 토큰은 만료·폐기 가능합니다.

# 본인 터미널에서 (하루 1회 정도). env 모드라면 login이 export 명령을 그대로 출력
kiwoom config set token_storage env
kiwoom auth login
export KIWOOM_TOKEN='...'   # login 출력의 export 라인을 복사해 실행

# 이 셸에서 에이전트를 실행하면 환경변수가 상속되어 모든 명령이 동작
kiwoom auth status   # 토큰 있음 (환경변수 KIWOOM_TOKEN)

keychain 모드를 유지하면서 일회성으로 꺼내 쓰려면:

export KIWOOM_TOKEN=$(security find-generic-password -s kiwoom-cli -a "default:token" -w)  # macOS

명령어 구조

kiwoom [--format table|json|csv] [--no-color] [-p 프로필]
├── config      설정 (setup / show / domain / profiles)
├── auth        인증 (login / logout / status)
├── stock       종목 조회 (info / orderbook / chart / compare ...)
├── account     계좌 조회 (balance / deposit / returns / pnl ...)
├── order       주문 (buy / sell / modify / cancel / credit / gold)
├── market      시장 정보 (rank / sector / theme / etf / elw / gold)
├── stream      실시간 스트리밍 (quote / orderbook / order / vi ...)
├── watch       실시간 종목 모니터링 (TUI)
├── dashboard   대시보드 (계좌 + 거래량 상위 한눈에)
└── api         Raw API 호출

stock - 종목 조회

kiwoom stock info 005930              # 기본정보 (PER, PBR, 시가총액 등)
kiwoom stock price 005930             # 현재가 한 줄
kiwoom stock orderbook 005930         # 10단계 호가창
kiwoom stock daily 005930             # 일별 시세
kiwoom stock daily 005930 --type week # 주별 시세
kiwoom stock exec 005930              # 체결정보
kiwoom stock trader 005930            # 거래원
kiwoom stock foreign 005930           # 외국인 매매동향
kiwoom stock institution 005930       # 기관 매매동향
kiwoom stock short 005930 --from 20260101 --to 20260330  # 공매도 추이
kiwoom stock sync                        # 전 시장 종목 리스트 다운로드 (캐시)
kiwoom stock search 삼성                 # 캐시에서 종목 검색
kiwoom stock search 삼성 --market kospi  # 코스피만 필터
kiwoom stock watchlist "005930|000660" # 관심종목
kiwoom stock compare 005930 000660     # 종목 비교 (최대 여러 종목)

차트

kiwoom stock chart tick 005930 --range 1        # 틱
kiwoom stock chart minute 005930 --interval 5    # 5분봉
kiwoom stock chart day 005930 --base-date 20260301   # 일봉
kiwoom stock chart week 005930 --base-date 20260301  # 주봉
kiwoom stock chart month 005930 --base-date 20260301 # 월봉
kiwoom stock chart year 005930 --base-date 20260301  # 년봉

투자자/분석

kiwoom stock investor daily-trade --from 20260301 --to 20260330
kiwoom stock investor by-stock 005930 --date 20260301
kiwoom stock investor program-top
kiwoom stock analysis vi-trigger
kiwoom stock analysis per-rank --type low-per
kiwoom stock lending trend
kiwoom stock credit trend 005930 --date 20260301 --type loan

account - 계좌 조회

kiwoom account list                # 계좌번호
kiwoom account balance             # 잔고 + 보유종목 + 손익 (국내+미국 통합)
kiwoom account deposit             # 예수금
kiwoom account asset               # 추정자산
kiwoom account today               # 당일현황
kiwoom account returns summary     # 수익률
kiwoom account pnl today 005930    # 당일 실현손익
kiwoom account orders pending      # 미체결 주문
kiwoom account orders executed     # 체결 내역
kiwoom account holdings eval       # 잔고내역
kiwoom account orderable amount 005930 --side buy --price 70000

미국주식 (US Stocks)

티커를 입력하면 자동으로 미국 시장으로 라우팅됩니다 (6자리 숫자 = 국내, 알파벳 = 미국).

kiwoom order buy NVDA 10 --price 213.04           # 매수 (거래소 자동 판별)
kiwoom order sell NVDA 5 --type stop-limit --price 200.5 --stop 199.99 --confirm
kiwoom stock price NVDA                            # 현재가
kiwoom stock chart day NVDA --base-date 20260701   # 일봉
kiwoom stock search apple --market us              # 종목 검색
kiwoom account balance                             # 국내+미국 통합 잔고 (원화 총계)
kiwoom account balance --market us                 # 미국만
kiwoom account exchange rate                       # 환율
kiwoom account exchange apply 1000000 --confirm    # 원화 → 달러 환전

• 거래소(--exchange nasdaq|nyse|amex)는 자동 판별되며 복수 상장 종목만 직접 지정이 필요합니다.
• 미국 주문 유형: limit/market/vwap/twap/vwap-limit/twap-limit/loc (매수·매도), moc/stop/stop-limit (매도 전용).
• 정정은 가격만 가능(전량), 취소는 전량 취소만 지원됩니다 (키움 API 제약).
• 계좌 조회 명령(balance/deposit/pnl/orders/history)은 기본 통합 표시이며 --market kr|us로 필터링합니다.

자세한 가이드: Wiki: 미국주식

order - 주문

주문은 실행 전 미리보기 + 대화형 확인이 기본입니다. 자동화 시에만 --confirm(별칭 --yes)으로 스킵하세요. -f json/-f csv 모드는 절대 프롬프트하지 않습니다. --confirm 없이 실행하면 CONFIRMATION_REQUIRED 오류(exit 1)로 응답해 에이전트 세션이 멈추지 않습니다.

# 안전장치 (에이전트/자동화)
kiwoom -f json order validate buy 005930 10 --price 70000        # 사전점검 (주문 미전송)
kiwoom order buy 005930 10 --price 70000 --type limit --dry-run  # 전송될 내용만 확인 (미전송)
kiwoom order buy 005930 10 --price 70000 --type limit --confirm --client-order-id run-42  # 멱등 주문

# 주식
kiwoom order buy 005930 10 --type market --confirm          # 시장가 매수
kiwoom order buy 005930 10 --price 70000 --type limit --confirm  # 지정가 매수
kiwoom order sell 005930 10 --type market --confirm         # 매도
kiwoom order modify 0000139 005930 1 70000 --confirm        # 정정
kiwoom order cancel 0000140 005930 --confirm                # 취소

# 신용
kiwoom order credit buy 005930 10 --type market --confirm
kiwoom order credit sell 005930 10 --type market --confirm

# 금현물
kiwoom order gold buy M04020000 1 --type market --confirm
kiwoom order gold balance             # 잔고
kiwoom order gold pending             # 미체결

# 조건검색
kiwoom order condition list
kiwoom order condition search 001 --confirm

주문유형: limit market conditional after-hours pre-market single best first ioc market-ioc best-ioc fok market-fok best-fok stop mid mid-ioc mid-fok

--price를 지정하고 --type을 생략하면 지정가(limit)로 주문됩니다. 시장가 주문은 --price 없이 실행하세요.

주문 안전장치 (v2.4)

• --dry-run: 실제 전송될 request body를 그대로 출력하고 아무것도 전송하지 않습니다. --confirm보다 우선합니다. 시장가 주문은 현재가를 조회해 예상비용(est_cost)을 계산합니다.
• --client-order-id KEY: 멱등성 키. 같은 키로 재실행하면 재전송 없이 이전 응답을 반환합니다(idempotent_replay: true). 네트워크 단절·에이전트 재시도로 인한 중복 주문을 방지합니다. 원장: ~/.kiwoom/idempotency/<프로필>-<환경>.jsonl
• order validate buy|sell CODE QTY: read-only 사전점검. symbol_ok / market_open(KST 시계 휴리스틱, 공휴일 미감지) / sufficient_balance / price_ok / price_known(--price 미지정 시 현재가로 예상비용을 계산할 수 있었는지)를 점검하고 실패 시 VALIDATION_FAILED + 실패 항목을 error.details에 담아 exit 1. 국내 주식 전용.

market - 시장 정보

순위

kiwoom market rank volume           # 거래량 상위
kiwoom market rank amount           # 거래대금 상위
kiwoom market rank change           # 등락률 상위
kiwoom market rank surge            # 가격 급등락
kiwoom market rank hot              # 실시간 조회 순위
kiwoom market rank limit            # 상하한가
kiwoom market rank foreign-period   # 외인 기간별 매매
kiwoom market rank foreign-inst     # 외국인/기관 매매

업종 / 테마 / ETF / ELW / 금현물 / 프로그램

kiwoom market sector current 001        # 업종 현재가
kiwoom market sector index              # 전업종 지수
kiwoom market sector chart day 001 --date 20260301

kiwoom market theme groups              # 테마 그룹
kiwoom market theme stocks THEMA001     # 테마 구성종목

kiwoom market etf all                   # ETF 전체 시세
kiwoom market etf info 069500           # ETF 종목정보

kiwoom market elw detail 580001         # ELW 상세정보
kiwoom market elw search                # ELW 조건검색

kiwoom market gold price                # 금현물 시세
kiwoom market gold orderbook            # 금현물 호가

kiwoom market program time-trend --date 20260301
kiwoom market program stock-daily 005930

stream - 실시간 스트리밍

WebSocket 실시간 시세. Ctrl+C로 종료.

kiwoom stream quote 005930              # 체결 실시간
kiwoom stream orderbook 005930          # 호가 실시간
kiwoom stream order                     # 주문체결 (계좌)
kiwoom stream balance                   # 잔고 변동 (계좌)
kiwoom stream vi 005930                 # VI 발동/해제
kiwoom stream multi 005930              # 체결+호가 동시
kiwoom stream quote 005930 000660 035420  # 복수 종목
kiwoom stream custom 0B,0D 005930       # 타입 직접 지정
kiwoom stream types                     # 타입 코드 목록

녹화와 조회 (Recording & history)

모든 stream 명령에 --record를 붙이면 수신 이벤트를 NDJSON 파일로 저장한다 (출력 형식과 무관하게, 테이블을 보면서도 기록된다). 경로를 생략하면 ~/.kiwoom/data/<심볼>_<날짜>.ndjson에 심볼별로 쌓이고 경로를 주면 한 파일에 모인다. 저장된 데이터는 history로 다시 읽는다.

# 1. 캡처: 장중 30분간 체결 실시간을 녹화
kiwoom stream quote 005930 --record --duration 30m

# 2. 조회: 시각 범위/타입으로 필터 (파일은 한 줄씩 스트리밍으로 읽음)
kiwoom history list                     # 녹화 파일 목록 (심볼·날짜·건수·시작/종료 ts)
kiwoom history query 005930 --from 2026-07-16T10:00:00 --to 2026-07-16T10:30:00 --type 0B

# 3. 내보내기: sqlite/csv (parquet은 pandas+pyarrow 설치 시)
kiwoom history export 005930 --dest sqlite --out samsung.sqlite
kiwoom history export 005930 --dest csv --from 2026-07-16T09:00:00 --to 2026-07-16T15:30:00

sqlite 내보내기는 events(ts, symbol, type, price, volume, raw_json) 테이블과 (symbol, ts) 인덱스를 만든다.

dashboard / Raw API

kiwoom dashboard                        # 계좌 요약 + 거래량 상위 한눈에

kiwoom api ka10001 '{"stk_cd":"005930"}'        # Raw API: 테이블 출력
kiwoom api ka10001 '{"stk_cd":"005930"}' --raw   # JSON 원본

주문성 API(매수/매도/정정/취소/환전)를 raw로 호출할 때도 확인 게이트가 적용됩니다. table 모드는 미리보기 후 y/n 프롬프트, 자동화는 --confirm:

kiwoom api kt10000 '{"stk_cd":"005930","ord_qty":"1",...}' --confirm

출력 형식

모든 명령에 -f / --format 옵션 사용 가능:

kiwoom stock info 005930                # 기본: Rich 테이블
kiwoom -f json stock info 005930        # JSON (파이핑, AI 에이전트용)
kiwoom -f csv stock daily 005930        # CSV (엑셀, 데이터 분석용)
kiwoom --no-color stock info 005930     # 색상 없이 (파일 저장용)

# jq로 필터링 (본문은 .data 아래)
kiwoom -f json market rank volume | jq '.data[].stk_nm'

# CSV를 파일로 저장
kiwoom -f csv stock daily 005930 > samsung_daily.csv

JSON 응답 envelope (v1)

-f json의 모든 응답은 성공/실패 모두 하나의 안정적인 envelope로 감쌉니다. 이 envelope 구조 자체는 table/csv 모드에는 적용되지 않습니다. 단, 호가·체결가 등 방향지시자 필드의 부호 제거·숫자 타입 변환(kiwoom_cli/formatters.py의 _ABS_FIELDS/_SIGNED_FIELDS)은 -f json의 data뿐 아니라 table 렌더링에도 동일하게 적용됩니다(_needs_fmt가 같은 필드 분류를 공유). -f csv는 정규화·서식 변환 없이 원본 값을 그대로 쓰므로 영향이 없습니다.

{
  "ok": true,
  "schema": "v1",
  "data": { "stk_nm": "삼성전자", "cur_prc": "+70000" },
  "meta": { "profile": "default", "env": "prod", "cont": { "next_key": "..." } },
  "error": null
}

• data: 기존 응답 본문 그대로 (return_code/return_msg만 제거)
• meta.profile / meta.env: 해석된 프로필과 도메인(prod/mock)
• meta.cont: 연속조회 커서. 값이 있으면 다음 페이지가 존재: kiwoom api <api_id> <body> --next-key <meta.cont.next_key>
• 실패 시 ok: false, data: null이고 error에 안정적인 코드가 담깁니다:

{ "code": "TOKEN_EXPIRED", "retryable": false, "message": "Token이 유효하지 않습니다", "upstream_code": 8005 }

error.code는 키움 오류코드/HTTP 상태를 분류한 stable enum입니다. 에이전트는 메시지 문자열 대신 이 코드로 분기하세요:

CLI 수준의 인자/옵션 오류(잘못된 값, 인자 누락 등)도 json 모드에서는 INVALID_INPUT envelope로 출력됩니다 (upstream_code: null, exit 1). kiwoom api --raw는 json 모드에서도 envelope로 감싸되 data에 응답 원본을 그대로(return_code 포함) 담습니다. auth login은 json 모드에서 {profile, token_storage, saved, token}을 반환하며 token 원문은 env 모드에서만 포함됩니다.

exit code 계약은 그대로입니다 (0=성공, 1=입력오류, 2=API오류, 3=인증필요).

Shell 자동완성

# Bash
eval "$(_KIWOOM_COMPLETE=bash_source kiwoom)"

# Zsh
eval "$(_KIWOOM_COMPLETE=zsh_source kiwoom)"

# Fish
eval (env _KIWOOM_COMPLETE=fish_source kiwoom)

Exit Codes

보안

모든 인증정보(appkey, secretkey, 토큰)는 OS 키체인(macOS Keychain / Windows Credential Manager / Linux Secret Service)에 저장됩니다. 파일로 존재하지 않으며 키체인이 디스크 저장 시 암호화를 담당합니다. gh, aws, docker CLI와 동일한 모델입니다.

• 모든 명령어는 비밀번호/생체인증 프롬프트 없이 동작 (AI 에이전트·자동화 친화적)
• 앱 자체 암호화 계층은 의도적으로 두지 않음. 추가 계층은 명령마다 잠금 해제 프롬프트를 요구하게 되어 CLI 사용성을 해침
• v2.0 이하에서 업그레이드한 경우: 암호화 저장소 형식이 제거되어 kiwoom config setup을 한 번 다시 실행해야 합니다
• 주문은 기본적으로 미리보기 + 대화형 확인을 거칩니다 (--confirm으로 스킵)
• ~/.kiwoom 디렉토리는 0700, config.toml·주문 원장·레코딩 파일은 0600으로 생성됩니다. 기존 설치본도 아무 명령 실행 시 자동으로 조여집니다 (--record로 명시한 경로는 제외)
• 프로필 이름은 [A-Za-z0-9_-]{1,64} allowlist로 제한됩니다. 원장 파일명·키링 키로의 경로 조작을 차단합니다
• raw kiwoom api로 주문성 API(17개)를 직접 호출하면 확인 게이트가 적용됩니다: table 모드는 body 미리보기 + y/n 프롬프트, json/csv 모드는 --confirm 없이 CONFIRMATION_REQUIRED(exit 1)
• PyPI 배포는 Trusted Publishing(OIDC)으로 이루어집니다. 장기 API 토큰을 저장하지 않습니다

자세한 내용: Wiki: 보안 모델 · SECURITY.md

참고

• kiwoom <명령> --help로 상세 옵션 확인
• 모의투자 먼저 테스트: kiwoom config domain mock
• 연속조회(페이지네이션) 자동 처리
• 종목코드 6자리: 005930 (삼성전자)
• 금현물: M04020000 (1kg), M04020100 (미니 100g)

라이선스

kiwoom-cli는 Source-Available License, Version 1.0을 따릅니다. 자세한 내용은 LICENSE를 참고하세요.

• 개인 (자연인 본인 명의로 사용): 영리 목적(예: 본인 계좌로 매매)을 포함해 어떤 용도로든 자유롭게 사용·수정·배포할 수 있습니다. 저작권 표시 의무만 있고 소스 공개 의무는 없습니다.
• 기관, 무수정 영리 사용: 상업 라이선스가 필요합니다.
• 기관, 수정 후 영리 사용: 상업 라이선스를 구매(이 경우 소스는 비공개 유지 가능)하거나 전체 코드베이스를 이 라이선스로 공개해야 합니다. 두 경우 모두 수정된 전체 소스를 라이선서에게 전달해야 합니다.

v2.0 이전 릴리스는 계속 MIT 라이선스로 제공됩니다. 상업 라이선스는 ge.jyn14@gmail.com으로 문의하세요. 자세한 내용은 COMMERCIAL.md를 참고하세요.