@h6s-ai/cli — headless Open API CLI

headless 의 Open REST API (/api/v1/**) 를 터미널에서 사용하는 공식 CLI.

설치

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 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"] }
  }
}

도구 8개 (h6s_catalog, h6s_list_providers, h6s_list_schemas, h6s_get_schema, h6s_list_credentials, h6s_credentials_create, h6s_fetch_data, h6s_report_bug):

| 도구 | 호출 시 | |---|---| | 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 + 기간 → 결과 (credential 매칭은 백엔드 위임) | | h6s_report_bug | 에이전트가 발견한 이상 동작을 운영팀 백채널로 즉시 제보 |

인증: 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 | | 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 서버) | 5개 도구 (providers/schemas/credentials/fetch) | | config | path, list, get, set, unset, use | (로컬) | | completion | bash, zsh, fish | (로컬) |

h6s fetch 매크로

h6s fetch <schema>
  --provider <code>         # 필수. credential 매칭은 백엔드 CredentialMatcher 위임
  [--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, credentialId 누락 시 백엔드 매처가 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) | | --base-url <url> | H6S_API_BASE_URL | gateway URL override | | -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) |

Profile

여러 환경(예: prod, sandbox)을 분리할 때:

# sandbox
h6s login --profile sandbox --base-url https://h6s-gateway-rest.boltadev.com
h6s --profile sandbox credentials list

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

| 환경 | gateway base URL | |---|---| | production (디폴트) | https://api.h6s.ai | | sandbox | https://h6s-gateway-rest.boltadev.com | | 로컬 개발 | http://localhost:10002 |

--base-url / H6S_API_BASE_URL 은 origin 까지만 지정합니다. /api/v1 은 CLI 가 path 에 자동으로 붙입니다 (잘못 붙여도 자동 정정).

자동완성

# 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 조항 포함.