nhncloud-cli

NHN Cloud 를 터미널과 AI 에이전트에서 쓸 수 있게 해 주는 비공식 CLI 예요. NHN 이 만든 공식 제품이 아니에요.

인스턴스, 네트워크, 로드밸런서, Kubernetes, 컨테이너 레지스트리와 컨테이너 서비스, 로그 검색, 배포, API Gateway, 키 관리를 명령 한 줄로 다루고, 결과를 --json 으로 내보내요. Claude Code 나 Codex 에 스킬로 설치하면 "인스턴스 목록 보여줘" 같은 말을 그대로 알아듣고 처리해요.

npm install -g @bifos/nhncloud-cli
nhncloud configure
nhncloud skills install

"인스턴스 목록 보여줘"
"kr1 리전에 인스턴스 만들고 ACTIVE 될 때까지 기다려줘"
"최근 1시간 에러 로그 찾아줘"
"배포 실행하고 완료되면 알려줘"
"클러스터 kubeconfig 받아줘"

이런 분께 맞아요

• NHN Cloud 콘솔을 열지 않고 터미널에서 리소스를 확인하고 바꾸고 싶은 분
• AI 에이전트에게 인스턴스 관리, 로그 조회, 배포 실행을 맡기고 싶은 분
• 로그 추출이나 배포처럼 반복되는 작업을 스크립트로 자동화하고 싶은 분

빠른 시작

Node.js 20.18.1 이상이 필요해요.

1. 설치해요

npm install -g @bifos/nhncloud-cli

2. 자격증명을 설정해요

아래 명령을 실행하면 profile 과 서비스별 자격증명을 차례로 물어봐요. 쓰는 서비스의 값만 입력해도 돼요. 저장하기 전에 연결 테스트를 자동으로 수행해요.

nhncloud configure

인스턴스, 네트워크 같은 IaaS 명령을 쓴다면 두 값을 특히 조심해 주세요.

• "API 비밀번호"(--iaas-password)는 콘솔 로그인 비밀번호가 아니라 IAM 의 API 비밀번호예요. IAM 사용자 상세 페이지의 "API 비밀번호 설정"에서 따로 발급해요.
• "IAM username"(--iaas-username)은 계정 이메일이나 IAM 계정 ID 예요. tenantId 와 비슷하게 생긴 UUID 형태의 "API 사용자 ID"가 아니에요.

나머지 입력 항목은 IaaS 가이드에 있어요. 공공기관용 NHN Cloud 설정은 공통 가이드에 있어요.

3. 설정을 확인해요

nhncloud doctor
nhncloud doctor --check-connection   # 대상 profile 의 실제 연결까지 확인

doctor 는 기본으로 외부 API 를 호출하지 않고 자격증명, 설정 파일, 스킬 설치 상태를 확인해요. --check-connection 을 주면 대상 profile 의 자격증명으로 실제 연결까지 확인해요.

4. 첫 명령을 실행해요

nhncloud instance list --region kr1    # 인스턴스 목록
nhncloud network list --region kr1     # VPC 목록

--region 은 IaaS 와 NKS 계열에서 결과가 달라지므로, 기본값에 기대지 말고 직접 지정하는 편이 안전해요.

5. AI 에이전트에 연결해요 (선택)

Claude Code 나 Codex 를 쓴다면 스킬을 설치해요. 에이전트가 이 CLI 의 사용법을 알게 돼요. 설치하면 Claude Code 의 ~/.claude/skills/nhncloud-cli 와 Codex 의 ~/.agents/skills/nhncloud-cli 에 함께 연결돼요.

nhncloud skills install
nhncloud skills status

이제 에이전트에게 한국어로 시키면 돼요. 에이전트가 알맞은 nhncloud 명령을 고르고, 필요하면 인스턴스 id 나 VPC id 를 먼저 조회해요.

CLI 를 새 버전으로 올린 뒤에는 nhncloud skills update 를 한 번 실행해 주세요. 그래야 스킬도 함께 갱신돼요. 전역 설치 없이 npx --yes @bifos/nhncloud-cli@latest skills install 로도 설치할 수 있어요.

할 수 있는 일

Load Balancer TLS 인증서는 공용망과 공공망 모두 key-manager 에 저장해요. loadbalancer certificate 명령은 두 망에서 같은 방식으로 동작하고, IAM 계정에 key-manager 권한이 있어야 해요.

명령과 옵션 전체는 카탈로그로 확인할 수 있어요. 외부 API 를 호출하지 않고 명령 트리 정보만 출력해요.

nhncloud commands --json | jq '.commands[] | select(.path=="nks cluster list")'

에이전트 없이 직접 쓰기

터미널에서 바로 써도 돼요.

nhncloud instance list                                        # 인스턴스 목록
nhncloud instance get <instance-id>                           # 인스턴스 상세
nhncloud network list                                         # VPC 목록
nhncloud network security-group list                          # 보안그룹 목록
nhncloud instance security-group add <instance-id> <group> --yes  # 인스턴스에 보안그룹 연결
nhncloud volume list                                          # 블록 스토리지 볼륨
nhncloud floatingip list                                      # Floating IP
nhncloud loadbalancer list                                    # 로드밸런서
nhncloud loadbalancer listener list --loadbalancer <lb>       # 로드밸런서 리스너
nhncloud loadbalancer certificate upload --name <name> --certificate-file cert.pem --private-key-file key.pem --dry-run  # TLS 인증서 업로드 미리보기
nhncloud ncr list                                             # 컨테이너 레지스트리
nhncloud nks cluster list                                     # Kubernetes 클러스터
nhncloud deploy artifacts                                     # 배포 아티팩트
nhncloud deploy scenarios --artifact-id <id> --server-group-id <id>  # 서버그룹 시나리오
nhncloud logncrash available-token                            # 남은 조회 토큰과 추정 대기 시간
nhncloud logncrash search --query '*' --from 1h --to now      # 최근 1시간 로그
nhncloud logncrash export --query '<lucene>' --from 1h --to now --output logs.jsonl  # 대량 로그 파일 저장
nhncloud apigateway service list                              # API Gateway 서비스
nhncloud apigateway stage deploy create <service-id> <stage-id> --yes  # API Gateway 스테이지 배포
nhncloud skm key list <keystore-id>                           # Secure Key Manager 키 목록
nhncloud skm secret get <key-id> --quiet                      # 기밀 데이터 원문
nhncloud skm secret get <key-id> --field <name> --quiet       # JSON 기밀 데이터의 필드 하나
printf '%s' "$VALUE" | nhncloud skm secret patch <key-id> <field> --replace --yes   # JSON 기밀 데이터의 필드 하나만 바꾸기
nhncloud rds-mysql user list <db-instance-id>                  # RDS for MySQL DB 사용자 목록
nhncloud rds-mysql user create <db-instance-id> --name app --host '10.0.0.%' --authority crud --password-file ./pw.txt   # 미리보기
nhncloud rds-mysql user create <db-instance-id> --name app --host '10.0.0.%' --authority crud --password-file ./pw.txt --yes --wait   # 반영하고 완료까지 대기
nhncloud dnsplus zone list                                    # DNS Plus 존 목록
nhncloud dnsplus recordset list --zone example.com            # 존의 레코드 세트 목록
nhncloud dnsplus recordset create --zone example.com --name www.example.com --type A --value 192.0.2.10 --dry-run   # 보낼 요청 미리보기
nhncloud dnsplus recordset create --zone example.com --name www.example.com --type A --value 192.0.2.10 --yes       # 같은 이름이 없을 때만 생성

삭제처럼 되돌리기 어려운 일부 명령은 --yes 를 붙여야 실행돼요. 비대화형 환경에서 --yes 가 없으면 API 를 호출하기 전에 끝나요. dnsplus recordset create·delete 는 --yes 나 --dry-run 이 없으면 API 를 호출하기 전에 끝나요. rds-mysql 쓰기 명령과 skm secret patch 는 --yes 가 없으면 바뀔 내용만 보여 주는 미리보기로 끝나요. 확인 없이 바로 실행되는 변경 명령도 있으니, 에이전트에게 맡기기 전에 공통 가이드의 「되돌릴 수 없는 명령」 절을 먼저 봐 주세요.

명령과 옵션은 --help 로 볼 수 있어요.

nhncloud --help
nhncloud instance --help
nhncloud instance create --help

출력 형식을 골라요

nhncloud instance get <instance-id> --json | jq -r '.status'
nhncloud logncrash available-token --json | jq -r '.availableToken'

--json 은 CLI 가 가공한 출력이라 원본 응답과 모양이 달라요. 명령별 모양은 「할 수 있는 일」 표의 서비스별 가이드에 있어요. 요청 타임아웃, 환경변수, 비대화형 설정은 공통 가이드에 있어요.

더 알아보기

문제가 생기면

• 설정이 의심되면 nhncloud doctor 를 먼저 실행해 보세요.
• 에이전트가 새 명령을 모르면 nhncloud skills update 를 실행해 주세요.
• 프록시를 거쳐야 하면 --proxy http://proxy.example:3128 또는 HTTPS_PROXY 를 지정해요. 자세한 규칙은 공통 가이드의 「프록시」 절에 있어요.
• 종료 코드별 대처는 문제 해결에 있어요.
• 버그나 제안은 GitHub Issues 에 남겨 주세요. 설정 문제라면 nhncloud doctor --json 출력을 함께 붙여 주세요. 비밀값은 출력에 들어가지 않지만 파일 경로에 사용자 이름이 보일 수 있으니 필요하면 가려 주세요.

기여하기

이슈와 PR 모두 환영해요. 개발 환경은 아래 명령으로 준비해요.

git clone https://github.com/jon890/nhncloud-cli.git
cd nhncloud-cli
pnpm install
pnpm run build
pnpm tsc --noEmit
pnpm test

새 명령을 추가하는 규칙은 AGENTS.md 와 docs/code-architecture.md 에 있어요. 커밋과 PR 제목은 type(scope): 설명 형식으로, 커밋 메시지와 PR 본문은 한국어로 써 주세요. 이 저장소는 공개돼요. 실제 자격증명이나 리소스 ID 는 남기지 말고 <instance-id> 같은 placeholder 를 써 주세요.

라이선스

MIT