gend-cli 빠른 시작

gend-cli 는 GenD Data Intelligence Platform 의 터미널 인터페이스다. 두 가지 자격증명 경로를 지원한다:

사용처	자격증명	권장
사람 (개인 머신/노트북)	`gend auth login` 으로 OS 키체인 저장 + 자동 갱신	★ 기본
CI / 자동화 / 외부 서비스	M2M 서비스 클라이언트 (`gend-svc-*` client_credentials)	★
즉석 curl / 디버깅	UI 모달의 SSO access_token 복사 (`GEND_TOKEN`)	일회성만

gend 는 환경변수와 키체인을 자동으로 resolve 한다 — 토큰 문자열을 직접 다룰 일은 없다.

데스크탑 / 노트북에서 본인 GenD 계정으로 작업하는 경우.

1단계 — 설치

git clone https://github.com/genonai/DataX.git
cd DataX/apps/cli
python -m venv .venv && source .venv/bin/activate
pip install -e .
gend version

2단계 — 로그인

gend auth login

기본 동작 (RFC 8252 Authorization Code Flow + Loopback + PKCE):

브라우저가 자동으로 열려 GenD Keycloak 로그인 페이지로 이동
SSO 로그인 (Google / 사내 IdP 또는 사용자 ID/비밀번호)
브라우저가 http://127.0.0.1:<임시포트>/callback 으로 redirect — CLI 가 코드를 수집
PKCE verifier 와 함께 토큰 endpoint 로 exchange
발급된 access_token + refresh_token 을 OS 키체인 (macOS Keychain / Linux Secret Service / Windows Credential Manager) 에 저장

3단계 — 사용

gend auth status
# Authority: https://gend.genon.ai/auth/realms/gend
# Client ID: gend-cli
# Scope:     openid profile email
# Expires:   2026-05-28 16:42:12 UTC (+3580s)
# Refresh:   yes

gend health
gend catalog catalogs
gend query exec "SELECT count(*) FROM hive.default.users"

토큰 만료가 임박하면 (expires_in - 60s) gend 가 자동으로 refresh_token 으로 새 access_token 을 받아온다. 사용자가 만료를 의식할 필요 없음.

4단계 — 로그아웃

gend auth logout

키체인 + 파일 fallback + 서버 측 refresh_token 모두 무효화.

헤드리스 환경 / 브라우저 부재

다음 조건 중 하나라도 만족하면 자동으로 RFC 8628 Device Flow 로 진입:

stdin 이 TTY 가 아님 (SSH 비-interactive / CI)
Linux 에서 DISPLAY + WAYLAND_DISPLAY 둘 다 미설정
GEND_HEADLESS=1 환경변수 명시

명시적 강제:

gend auth login --device
# Visit:    https://gend.genon.ai/auth/realms/gend/device?user_code=WDJB-MJHT
# Code:     WDJB-MJHT
# Waiting for browser confirmation... (polling every 5s, expires in 600s)

다른 머신/스마트폰의 브라우저에서 위 URL 을 열고 user_code 를 입력하면, CLI 가 polling 으로 결과를 받아 토큰을 저장한다.

진행 중인 호환성 fix

추적: #1361

Keycloak public client 가 PKCE S256 을 강제하므로 Device endpoint 호출 시 code_challenge + code_challenge_method=S256 동반 필요. M4 의 initiate_device_flow 가 아직 PKCE 미전송 → 별도 fix PR 머지 전까지는 --device 옵션이 prod 에서 invalid_request 로 실패할 수 있다. Loopback (기본 gend auth login) 흐름은 영향 없음.

raw curl 검증 패턴은 admin-ops/auth/cli-sso §3.2 참조.

M2M (CI / 자동화)

GenD admin 이 /admin/service-clients 에서 발급한 gend-svc-* 서비스 계정 자격증명으로 호출한다. 사람 계정과 분리되며 retire / rotate 가 안전하다.

자세한 발급 절차는 M2M 서비스 계정 인증 을 참조.

export GEND_API_URL="https://gend.genon.ai"
export GEND_CLIENT_ID="gend-svc-quant-ai"
export GEND_CLIENT_SECRET="<발급 모달에서 복사>"

gend health
gend query exec "SELECT count(*) FROM hive.default.users"

CLI 가 자동으로 client_credentials grant 토큰을 받아 30분 동안 캐시하고, 만료 임박 시 재발급한다. GEND_TOKEN env 와 동시 설정 시 M2M 이 우선이다.

CI 패턴

# .github/workflows/sample.yml
jobs:
  ingest:
    runs-on: ubuntu-latest
    env:
      GEND_API_URL: https://gend.genon.ai
      GEND_CLIENT_ID: ${{ secrets.GEND_CLIENT_ID }}
      GEND_CLIENT_SECRET: ${{ secrets.GEND_CLIENT_SECRET }}
    steps:
      - run: pip install -e DataX/apps/cli
      - run: gend query exec "SELECT 1"

권한 매트릭스

/admin/service-clients 발급 시 선택한 role 에 따라 호출 가능 명령어가 달라진다.

Role	호출 가능
`viewer`	`health`, `catalog/`, `quality/`, `gov/*`
`analyst`	viewer + `query exec`, `query history`
`admin`	analyst + `financial create/delete` (변경 작업)

Workspace W2 — 다중 멤버십 전환 (Epic #1362)

한 사용자가 여러 워크스페이스에 속할 때 (예: finance-invest + energy-kogas), CLI 명령을 어떤 워크스페이스 컨텍스트로 보낼지 결정합니다.

명령 요약

# 멤버십 전체 보기
gend workspace list

# 현재 active slug
gend workspace current

# 영구 설정 (~/.gend/active_workspace 저장)
gend workspace switch finance-invest

# per-call override (영구 설정 변경 없이 1회)
gend --workspace energy-kogas catalog list
gend --workspace energy-kogas query run "SELECT 1"

# 환경변수 (스크립트 / CI)
GEND_ACTIVE_WORKSPACE_SLUG=finance-invest gend intel filings list

# 영구 설정 제거 (JWT 첫 멤버십 폴백)
gend workspace clear

우선순위

출처	우선
`--workspace <slug>` flag	최상
`GEND_ACTIVE_WORKSPACE_SLUG` env	2
`~/.gend/active_workspace` 파일	3
(헤더 미첨부 → 서버가 JWT 폴백)	최하

내부적으로 모든 gend 명령이 _headers() 에서 X-Workspace-Slug 헤더를 자동 첨부합니다. 우선순위가 한 번 결정되면 그 호출의 모든 서브명령에 일관 적용.

자세한 흐름 / UI 동작 / 격리 정책은 워크스페이스 전환 가이드.

부록 — 즉석 curl / 디버깅 (UI 모달 토큰 복사)

GenD UI 우상단의 API 토큰 모달은 현재 SSO 세션의 access_token 을 그대로 노출한다. 다음과 같은 일회성 용도에 한정 사용:

컨퍼런스 라이브 데모 (1초 안에 curl 실행)
토큰 클레임을 jwt.io 등에 붙여 디버깅
사내 와이파이가 localhost callback 을 막은 환경에서의 임시 회피

export GEND_TOKEN="<UI 모달에서 복사>"
gend health

한계:

1시간 후 만료 → 다시 복사 필요 (자동 갱신 없음)
사람 권한 그대로 노출 → 실수로 git add / Slack 붙여넣기 유출 위험
회전 / 회수 불가 (세션 종료가 유일한 무효화)

자동화에는 사용 금지. 사람용은 gend auth login, 머신용은 M2M 을 사용한다.

트러블슈팅

에러	원인 / 조치
`Authentication required. Run \`gend auth login` ...`	자격증명 없음. 사람용이면 `gend auth login`, CI면 `GEND_CLIENT_ID`/`SECRET` env, 일회성이면 `GEND_TOKEN` 복사
`Permission denied.`	403 — role 미부여. M2M 은 M2M 서비스 계정 인증 의 절차
`Sign-in failed: Timed out waiting for browser sign-in`	브라우저가 자동으로 안 열리거나 사용자가 5분 이내에 로그인 미완료. `--device` 로 재시도
`Device sign-in failed: Device code expired`	user_code 입력 시간 초과 (보통 10분). `gend auth login --device` 재실행
`Sign-in failed: OAuth state mismatch`	redirect 가 다른 세션의 state 와 충돌. 브라우저 탭 정리 후 재시도
`Cannot connect to GenD API at ...`	`GEND_API_URL` 확인. AKS prod = `https://gend.genon.ai`, 로컬 dev = `http://localhost:30000`

다음 단계

gend-cli CLI 레퍼런스 — 명령어 전체 목록
M2M 서비스 계정 인증 — 운영자가 client 발급
CLI SSO 운영 — Keycloak gend-cli client 운영

사람용 (gend auth login)​

1단계 — 설치​

2단계 — 로그인​

3단계 — 사용​

4단계 — 로그아웃​

헤드리스 환경 / 브라우저 부재​

M2M (CI / 자동화)​

CI 패턴​

권한 매트릭스​

Workspace W2 — 다중 멤버십 전환 (Epic #1362)​

명령 요약​

우선순위​

부록 — 즉석 curl / 디버깅 (UI 모달 토큰 복사)​

트러블슈팅​

다음 단계​

사람용 (gend auth login)