@h6s-ai/cli — headless Open API CLI

AI 에이전트용 한국 금융 데이터 API를 터미널에서 호출하는 공식 CLI입니다. headless Open REST API (/api/v1/**) 위에서 cron 스크립트, CSV·JSON 추출, 자격증명 검증, CI 적재를 처리합니다.

AI 에이전트가 자연어로 데이터를 조회하게 만드는 경우에는 @h6s-ai/toolkit이 적합합니다. 단순히 데이터를 받아 자기 시스템에 적재하는 경우에는 이 CLI 또는 REST API가 더 적합합니다.

설치

npm i -g @h6s-ai/cli
# 또는 일회성
npx @h6s-ai/cli --help

Node.js 20 이상이 필요합니다.

업데이트

h6s upgrade        # 설치 매니저 자동 감지 → 확인 후 최신으로 갱신
h6s upgrade --check   # 갱신 안 하고 현재/최신 버전만 확인

수동으로 갱신한다면 설치에 쓴 매니저와 같은 매니저를 사용합니다 (@latest 필수):

npm install -g @h6s-ai/cli@latest      # npm
pnpm add -g @h6s-ai/cli@latest         # pnpm
bun add -g @h6s-ai/cli@latest          # bun

npm update -g @h6s-ai/cli는 동작하지 않습니다. npm의 update는 semver 범위를 지키는데 0.x 캐럿은 같은 minor 안에만 머물러 0.1 → 0.7 같은 이동을 하지 못합니다. 항상 install … @latest(또는 h6s upgrade)를 사용합니다.

여러 매니저로 중복 설치하면(예: pnpm 전역 + npm 전역) PATH 우선순위가 높은 사본 하나만 실행됩니다. which -a h6s 목록에서 실제로 실행되는 사본을 확인할 수 있으며, 해당 매니저로 갱신합니다. h6s upgrade는 실행 중인 사본을 감지해 맞는 명령을 제안하고, 중복이 보이면 경고합니다.

빠른 시작

처음이라면 h6s init 한 번으로 충분합니다. 프로필 확인 → Device Flow 로그인 → 가용 schema 표 → 다음 명령 안내까지 자동으로 진행됩니다.

h6s init
# 막히면 로컬 설정·인증·네트워크 상태를 먼저 확인
h6s doctor
# 안내된 명령을 그대로 복사·실행
h6s fetch bank.transactions.cb.v1 --provider CB_KB --month 2026-03 --output markdown --save ./out/

LLM 에이전트나 일회성 스크립트는 init 없이 login + fetch 두 줄로도 끝낼 수 있습니다. credential 매칭/생성 → 수집 요청 실행 → 결과 회수까지 자동으로 진행됩니다.

h6s login
h6s fetch bank.transactions.cb.v1 --provider CB_KB --month 2026-03 --output markdown --save ./out/

세부 단계가 필요할 때:

# 1. 인증
h6s login

# 2. 디스커버리
h6s ai-guide --format markdown      # AI 에이전트용 cheatsheet
h6s providers list
h6s schemas list

# 3. 자격증명 생성
h6s credentials create --interactive --cert                # 공동인증서 — 모든 기관 공용 (추천)
h6s credentials create --interactive --provider CB_KB    # 또는 이 기관만 ID·비밀번호
h6s credentials create --explain --cert > credential.json  # 공동인증서 템플릿
h6s credentials create --input @credential.json            # 스크립트

# 4. 데이터 수집 요청 실행 (자격증명 유효성은 첫 수집 요청으로 확인)
h6s data-jobs run --input @job.json --wait --timeout 30m
# job.json: { "providerCode": "CB_KB", "schema": "bank.transactions.cb.v1", "params": { ... } }

# 5. 결과 조회 (ContractRecord 배열)
h6s data-jobs results <job-id> --output json

h6s credentials create 사용 방식

자격증명은 두 종류입니다 — 공동인증서 (GLOBAL — 모든 금융기관 공용) 와 provider ID·비밀번호 (특정 기관만). 공동인증서는 PFX 파일 1번 등록으로 은행·홈택스 전체에 자동 매칭됩니다 (대다수 사용자에게 가장 빠른 첫 등록 경로). 사용 방식은 3가지입니다:

| 사용 방식 | 명령 (공동인증서) | 명령 (provider ID·비밀번호) | 용도 | |---|---|---|---| | 대화형 | --interactive --cert | --interactive --provider <code> | credential-schema 를 동적 폼으로 받아 사람 입력. PASSWORD/FILE 도 안전 처리. TTY 필수. | | 템플릿 | --explain --cert | --explain --provider <code> | 입력 받지 않고 빈 credential.json 템플릿만 stdout. 다른 도구에서 채우는 용도. | | 파일 | --input @file.json | --input @file.json | JSON/YAML 본문을 그대로 POST. CI/스크립트. (providerCode 없으면 자동 GLOBAL) |

대화형에서 --cert / --provider 어느 것도 없으면 첫 질문은 "공동인증서 / ID·비밀번호?" 선택지로 시작됩니다. --input/--interactive/--explain 중 정확히 하나만 지정해야 하며, --cert 와 --provider 동시 사용은 에러입니다.

h6s mcp — MCP stdio 서버

AI 클라이언트(Claude Code, Cursor, Gemini, 일반 MCP)가 headless 데이터를 도구로 호출할 수 있게 해 주는 stdio 서버입니다. @h6s-ai/toolkit의 .mcp.json에서도 이 명령이 사용됩니다.

// claude_desktop_config.json 또는 .mcp.json
{
  "mcpServers": {
    "h6s": { "command": "npx", "args": ["-y", "@h6s-ai/cli", "mcp"] }
  }
}

도구 12개 (h6s_catalog, h6s_list_providers, h6s_list_schemas, h6s_get_schema, h6s_list_credentials, h6s_credentials_create, h6s_fetch_data, h6s_fetch_data_start, h6s_fetch_data_status, h6s_fetch_data_results, h6s_report_bug, h6s_validate_brn):

| 도구 | 호출 시 | |---|---| | h6s_catalog | provider + authMethod + schema + 공동인증서 입력 폼을 한 번에 (디스커버리) | | h6s_list_providers | provider 코드 결정 전 | | h6s_list_schemas | schema 결정 전 | | h6s_get_schema | request 필드(필수/선택/타입) 확인 | | h6s_list_credentials | provider → credential id 매핑 확인 | | h6s_credentials_create | 자격증명 등록 — h6s_catalog fieldKey 그대로. FILE 은 base64. ⚠ 민감 값 LLM context 경유, 사용자 동의 선행 | | h6s_fetch_data | 매크로 — schema + provider + 기간 → 결과. 제한 시간 안에 끝나지 않으면 pending + jobId 반환 | | h6s_fetch_data_start | 오래 걸리는 수집 요청 시작 후 jobId 즉시 반환 | | h6s_fetch_data_status | data-job 상태 조회 | | h6s_fetch_data_results | 완료된 data-job 결과 조회 | | h6s_report_bug | 에이전트가 발견한 이상 동작을 운영팀 백채널로 즉시 제보 | | h6s_validate_brn | 사업자등록번호 형식·체크섬 검증 |

인증: H6S_API_KEY 환경변수 우선, 없으면 ~/.h6s/config.json 의 currentProfile. 키가 없으면 도구 호출 시 친절한 에러로 h6s init 안내.

친절한 에러 메시지

CLI는 잘 알려진 에러 코드(NO_API_KEY, CREDENTIAL_INSUFFICIENT_FOR_PROVIDER, CREDENTIAL_AMBIGUOUS, CREDENTIAL_PROBE_FAILED, CERT_INVALID/CERT_EXPIRED/CERT_WRONG_PASSWORD/CERT_BIZNO_MISMATCH, INVALID_DATA_JOB_PARAMS, DATE_RANGE_EXCEEDED, LOGIN_FAILED, API_RATE_LIMITED 등)에 다음 단계 한 줄을 함께 출력합니다.

$ h6s fetch bank.transactions.cb.v1 --provider CB_KB --month 2026-03
CREDENTIAL_INSUFFICIENT_FOR_PROVIDER: 매칭되는 credential 이 없습니다 (provider=CB_KB).

다음 단계:
  h6s credentials create --interactive --cert            # 공동인증서 1개로 모든 기관 공용 (추천)
  h6s credentials create --interactive --provider <code> # 또는 이 기관만 ID·비밀번호

인증 방식

세 가지 우선순위 (앞이 우선):

1. CLI 플래그 --api-key h6s_live_...
2. 환경변수 H6S_API_KEY
3. config 파일 (~/.h6s/config.json, mode 0o600) — h6s login 또는 h6s config set api_key ... 로 저장

명령어 색인

| 그룹 | 명령 | 엔드포인트 | |---|---|---| | init | (대화형 첫 설정) | login + GET /schemas | | auth | login | POST /auth/device + POST /auth/device/token (Device Flow) | | auth | logout | (로컬 config 만 정리) | | auth | whoami | GET /me/usage | | fetch | <schema> | (매크로) POST /data-jobs (body: providerCode+schema+params, credential 매칭은 백엔드 위임) + /data-jobs/{id}/results | | doctor | --json, --summary, --all, --no-color | (로컬 + readiness 조회) | | ai-guide | (LLM 에이전트용 cheatsheet) | (로컬) | | cache | path, list, prune | (로컬, ~/.h6s/cache/data-jobs) | | credentials | list (ls), get, create, update, delete (rm), find | /credentials 계열 5개 + find | | data-jobs (dj, jobs) | list (ls), count, get (--wait), results, run (--wait) | /data-jobs 계열 5개 | | providers (prov) | list, get, credential-schema, actions | /providers 계열 4개 | | schemas | list, get | /schemas 계열 2개 | | actions | list | GET /actions | | me | usage | GET /me/usage | | mcp | (MCP stdio 서버) | 12개 도구 (catalog/providers/schemas/credentials/fetch/status/results/bug-report/brn) | | config | path, list, get, set, unset, use | (로컬) | | completion | bash, zsh, fish | (로컬) |

h6s fetch 매크로

h6s fetch <schema>
  --provider <code>         # 필수. credential 매칭은 백엔드가 자동 처리
  [--month YYYY-MM | --from YYYY-MM-DD --to YYYY-MM-DD]
  [--param <key=value>]*    # schema request 필드 추가
  [--params @file.json]     # 또는 한 번에 JSON 으로
  [--output json|csv|jsonl|markdown|yaml|table]
  [--save <path|->]         # 디렉토리만 주면 자동 파일명, "-" 면 stdout
  [--no-wait] [--timeout 30m]

내부적으로 /api/v1/schemas/{id} (request 필드 검증) → POST /api/v1/data-jobs (body: providerCode + schema + params, 백엔드가 PROVIDER_BOUND credential 1순위 / 공동인증서 2순위로 자동 선택) → 폴링 → /api/v1/data-jobs/{id}/results 까지 한 번에 처리합니다. 같은 (provider, schema, params) 조합은 24h 동안 캐시됩니다 (--cache fresh 로 우회).

결과 캐시

• 위치: ~/.h6s/cache/data-jobs/<hash>__<schemaId>.json (mode 0o600)
• TTL: 24h freshness, 30d hard expiration. 200MB 초과 시 LRU
• 글로벌 플래그 --cache=stale|fresh|off|refresh (기본 stale)
• h6s cache list / prune --older-than 7d / path

글로벌 플래그

| 플래그 | env | 설명 | |---|---|---| | --api-key <key> | H6S_API_KEY | API key | | --profile <name> | H6S_PROFILE | 프로필 이름 (디폴트: default) | | -o, --output <fmt> | H6S_OUTPUT | table | json | yaml | csv | jsonl | markdown (TTY 면 table, 아니면 json) | | --cache <mode> | H6S_CACHE | stale | fresh | off | refresh (기본 stale, 24h) | | --verbose | H6S_VERBOSE | 요청/응답 로그 + rate-limit 상태 (stderr) | | --no-color | NO_COLOR | 색상 끄기 | | --quiet | — | spinner/progress 숨김 | | — | H6S_NO_UPDATE_CHECK | 새 버전 알림 끄기 (기본은 1일 1회 stderr 한 줄 알림. h6s mcp / CI / --quiet 에서는 자동 skip) |

진단

h6s doctor
h6s doctor --json

doctor는 Node 버전, 설치 경로 중복, config 권한, API key 마스킹 상태, whoami, base URL reachability, 업데이트 상태, provider/schema/action 조회, credential/data-job readiness, MCP stdio, 로컬 캐시를 읽기 전용으로 점검합니다. --json은 비밀값이 마스킹된 JSON만 stdout에 출력하고, 하나라도 실패한 진단이 있으면 exit code 1로 종료합니다.

Profile

API key 와 출력 설정을 작업별로 분리할 때:

h6s login --profile finance
h6s --profile finance credentials list

# 기본 프로필 변경
h6s config use finance

자동완성

# bash
echo 'eval "$(h6s completion bash)"' >> ~/.bashrc

# zsh
echo 'eval "$(h6s completion zsh)"' >> ~/.zshrc

# fish
h6s completion fish > ~/.config/fish/completions/h6s.fish

Exit Codes

| 코드 | 의미 | |---|---| | 0 | 성공 | | 1 | 비즈니스 에러 (4xx, ambiguous credential 등) | | 2 | 네트워크/타임아웃 | | 3 | 인증 에러 (401/403) | | 4 | NOT_FOUND — credentials find 0건 등 자동 회복 가능 | | 64 | 사용법 오류 (잘못된 인자) | | 130 | 사용자 중단 (SIGINT) |

Rate Limit

모든 응답에 다음 헤더가 포함됩니다 (--verbose 로 확인):

• X-RateLimit-Limit-Minute (분당 한도)
• X-RateLimit-Limit-Hour (시간당 한도)
• X-RateLimit-Remaining
• 429 응답: Retry-After (초)

CLI는 429 응답 시 Retry-After를 존중해 1회 자동 재시도합니다.

비동기 잡 폴링

data-jobs run 은 비동기입니다. --wait 를 추가하면 완료까지 대기:

h6s data-jobs run --input @job.json --wait --timeout 1h --poll-interval 5s

서버가 응답에 포함하는 suggestedPollIntervalMs 가 있으면 --poll-interval 보다 우선합니다.

AI 에이전트로 사용

Claude Code · Cursor · Gemini · 일반 MCP 클라이언트는 별도 패키지 @h6s-ai/toolkit으로 설치합니다. 본 CLI의 h6s mcp가 stdio MCP 서버 본체이고, toolkit은 매니페스트(plugin/skill)와 install 라우터만 담당합니다.

# Claude Code (권장)
/plugin marketplace add bolta-io/h6s-toolkit
/plugin install h6s-data@h6s

# Cursor / Gemini / 일반 MCP 클라이언트
npx @h6s-ai/toolkit install --target=cursor    # 또는 gemini / mcp

LLM 측 cheatsheet는 h6s ai-guide --format markdown 또는 <gateway>/llms.txt에서 가져올 수 있습니다.

라이선스

Apache License 2.0 — 자유롭게 사용/수정/재배포 가능. 특허 라이선스 부여 + 명시적 retaliation 조항 포함.