gcube-cli 0.1.0

Official command-line tool for the gcube AI GPU cloud platform

gcube CLI

gcube 플랫폼(AI GPU 클라우드) 공식 커맨드라인 도구. 브라우저 없이 터미널만으로 GPU 워크로드를 등록하고, 리소스를 모니터링하고, 사용자를 관리한다.

---

Overview

gcube <service> <operation> [options]

gcube는 gcube 플랫폼의 REST API를 직접 호출하는 Python CLI다.

특징	설명
pip 설치	pip install gcube-cli로 설치, Python 3.10+
AWS CLI 스타일	gcube <service> <operation> 구조, --output table|json|yaml
웹 토큰 인증	gcube 웹 프론트에서 토큰 발급 후 CLI에 설정
주요 의존성	click · httpx · rich · pyyaml

---

Installation

pip 설치 (권장)

pip install gcube-cli

소스 설치

git clone https://github.com/data-alliance/gcube-cli.git
cd gcube-cli
pip install -e ".[dev]"

---

Quick Start

핵심 워크플로우를 4개 명령어로 완료한다.

# 1. 토큰 설정 (gcube 웹 프론트에서 복사한 토큰)
gcube configure set --token "eyJ..."

# 2. GPU 워크로드 등록
gcube workload register -f workload.yaml

# 3. 상태 확인
gcube workload list

# 4. 로그 조회
gcube workload logs my-train-job

---

Configuration

토큰 발급 및 설정

1. gcube 웹 프론트에 로그인
2. "API 토큰 발급" 메뉴에서 토큰 복사
3. CLI에서 토큰 설정:

gcube configure set --token "eyJ..."

설정 파일

gcube configure 이후 ~/.gcube/config.yaml에 자동 생성된다.

platform_url: https://console.gcube.ai
ws_url: wss://console.gcube.ai:61443
auth:
  access_token: "eyJ..."
  expires_at: "2026-04-03T10:00:00Z"
output: table          # table | json | yaml

Commands

gcube configure                                     # 대화형 설정
gcube configure set --token <token>                 # 토큰 설정
gcube configure set --platform-url <url>            # 플랫폼 URL 설정
gcube configure set --ws-url <url>                  # WebSocket URL 설정 (로그 스트리밍용)
gcube configure set --output <format>               # 기본 출력 형식 설정
gcube configure get <key>                           # 설정값 조회 (token, platform-url, ws-url, output)
gcube configure status                              # 현재 설정 및 토큰 유효 여부 표시

환경변수

환경변수는 설정 파일보다 우선 적용된다.

환경변수	설명	예시
GCUBE_PLATFORM_URL	플랫폼 Base URL	https://gcube.ai
GCUBE_ACCESS_TOKEN	Bearer 토큰 (CI/CD용)	eyJ...
GCUBE_OUTPUT	기본 출력 형식	json
GCUBE_CONFIG	설정 파일 경로 override	/etc/gcube/config.yaml

다중 프로파일

--profile 플래그로 여러 플랫폼 환경(dev/prod 등)을 전환한다.

# 개발 환경 토큰 설정
gcube configure set --token "eyJ..." --platform-url https://dev.gcube.ai --profile dev

# dev 프로파일로 명령 실행
gcube workload list --profile dev

프로파일별 설정은 ~/.gcube/profiles/<profile>/config.yaml에 저장된다.

---

Command Reference

Workload

GPU 워크로드 수명주기를 관리한다.

명령	설명
gcube workload register -f <yaml>	YAML 파일로 워크로드 등록
gcube workload register --image <img> ...	인라인 플래그로 워크로드 등록
gcube workload update <ser> -f <yaml>	중지된 워크로드 수정
gcube workload list	워크로드 목록 조회
gcube workload describe <name>	워크로드 상세 조회
gcube workload start <name>	워크로드 시작
gcube workload stop <name>	워크로드 중지
gcube workload delete <name>	워크로드 삭제
gcube workload logs <ser>	컨테이너 로그 실시간 스트리밍 (WebSocket)
gcube workload logs <ser> --pod <idx>	특정 pod 로그 스트리밍
gcube workload logs <ser> --pod <idx> --container <idx>	특정 컨테이너 로그 스트리밍
gcube workload pods <name>	Pod 목록 조회

주요 플래그

플래그	설명	기본값
-f, --file <path>	워크로드 YAML 파일 경로	—
--image <image>	컨테이너 이미지	—
--gpu <code>	GPU 코드 (예: 029, gcube gpu list의 CODE 컬럼)	—
--cuda <version>	CUDA 버전 코드	—
--category <type>	워크로드 유형: infer|learn	—
--owner <email>	워크로드 소유자 (list 필터)	—
--container <name>	컨테이너명 (logs용)	—
--backend astrago	AstraGo 백엔드 사용	—
--namespace gai	GAI 네임스페이스 사용	—

CUDA 버전 코드 (형식: major×1000 + minor×10)

코드	CUDA 버전
12000	12.0
12020	12.2
12030	12.3
12040	12.4
12050	12.5
12060	12.6
12080	12.8
12090	12.9
13000	13.0

워크로드 YAML 형식 (register -f / update -f 공통)

# workload.yaml
description: "My ML training job"  # 필수, 2-80자
cuda: "12020"                      # CUDA 버전 코드 (선택)
sharedMemory: 1                    # GB

containers:
  - containerImage: "pytorch/pytorch:2.0"  # 필수
    repo: docker.io
    port: 0                        # 0 = 자동 감지
    maxConnection: 4
    containerCommand: "python train.py"
    isCredential: false
    containerEnvs:
      - EPOCHS: "100"
      - BATCH_SIZE: "32"

gpuSpecs:
  - gpuCode: "029"                 # 필수 — 'gcube gpu list'의 CODE 컬럼 값
  # 레플리카 추가: 항목 반복
  # - gpuCode: "029"

gcube workload register --skeleton 으로 빈 템플릿을 출력할 수 있습니다. gcube workload update <ser> --skeleton > workload.yaml 으로 현재 워크로드 설정을 내보낸 후 gpuCode를 채워 -f로 전달합니다.

---

GPU

사용 가능한 GPU 목록과 스펙·가격을 조회한다.

명령	설명
gcube gpu list	가용 GPU 목록 (CODE·스펙·시간당 가격 범위)
gcube gpu list --all	전체 GPU 목록 (비가용 포함, AVAIL 컬럼 표시)

gcube gpu list                        # 가용 GPU만 (CODE 포함)
gcube gpu list --all                  # 전체 (비가용 포함)
gcube -o json gpu list        # JSON 출력
gcube -o yaml gpu list        # YAML 출력

CODE는 API 응답 순서 기반 3자리 순번(001, 002, ...)이며, 워크로드 등록 시 GPU 특정에 사용된다.

---

Resource

워크로드의 CPU·GPU·메모리 사용량을 조회한다. workload 이름을 입력하면 내부적으로 pod를 resolve하여 리소스를 조회한다.

명령	설명
gcube resource workload <name>	워크로드 리소스 사용량 (시간 평균)

---

Point

포인트 잔액과 일별 지출 내역을 조회한다.

명령	설명
gcube point status	포인트 현황 (잔액·충전·지출 요약, 잔액 부족 경고)
gcube point spending	당월 일별 지출 내역
gcube point spending --month 2026-03	특정 월 일별 지출 내역
gcube point spending --workload <ser>	특정 워크로드 지출 필터

---

User

사용자 계정과 크레덴셜을 관리한다.

명령	설명
gcube user list [--keyword <search>]	사용자 목록 조회
gcube user describe <email>	사용자 상세 조회
gcube user create --email <e> --name <n> [--role <r>]	사용자 생성
gcube user update <email> [--name <n>]	사용자 정보 수정
gcube user delete <email>	사용자 삭제
gcube user credentials list <email>	크레덴셜 목록
gcube user credentials create <email> --name <n>	크레덴셜 생성
gcube user credentials delete <email> --cred-id <id>	크레덴셜 삭제
gcube user token <email>	플랫폼 토큰 발급/조회

---

Output Formats

--output 플래그(또는 GCUBE_OUTPUT 환경변수)로 출력 형식을 선택한다.

table (기본값)

$ gcube workload list

NAME              CATEGORY   TARGET   GPU          GPU COUNT   STATE
my-train-job      learn      any      RTX4090      2           running
my-infer-svc      infer      svr      A100         1           stopped

json

$ gcube -o json workload list

[
  {"ser":"abc123","owner":"[e-mail]","category":"learn","gpu":"RTX4090","gpuCount":2,"state":"running"},
  {"ser":"def456","owner":"[e-mail]","category":"infer","gpu":"A100","gpuCount":1,"state":"stopped"}
]

yaml

$ gcube -o yaml workload list

- ser: abc123
  owner: [e-mail]
  category: learn
  gpu: RTX4090
  gpuCount: 2
  state: running
- ser: def456
  owner: [e-mail]
  category: infer
  gpu: A100
  gpuCount: 1
  state: stopped

---

Global Options

모든 명령에서 사용 가능한 플래그.

플래그	설명	기본값
--platform-url <url>	gcube 플랫폼 Base URL	config.yaml 값
--output <format>	출력 형식: table|json|yaml	table
--profile <name>	사용할 프로파일 이름	default
--debug	HTTP 요청/응답 상세 출력	false
--help, -h	도움말 출력	—

---

Exit Codes

코드	의미	예시
0	성공	정상 출력
1	잘못된 인수 또는 플래그	필수 플래그 누락
2	gcube API 오류	API Error [NOT_FOUND]: workload not found
3	인증 실패 또는 토큰 만료	Token expired or invalid. Please get a new token from https://gcube.ai
4	네트워크 오류	Cannot connect to https://gcube.ai. Check network.

스크립트에서 활용:

gcube workload start my-job
if [ $? -eq 3 ]; then
  echo "Token expired. Please get a new token from https://gcube.ai"
  echo "Then run: gcube configure set --token <new-token>"
fi

---

Environment Variables

변수	설명
GCUBE_PLATFORM_URL	플랫폼 Base URL (--platform-url override)
GCUBE_ACCESS_TOKEN	Bearer 토큰 직접 지정 (CI/CD 환경)
GCUBE_OUTPUT	기본 출력 형식 (--output override)
GCUBE_PROFILE	기본 프로파일 이름 (--profile override)
GCUBE_CONFIG	설정 파일 경로 override
GCUBE_DEBUG	1 로 설정 시 --debug 활성화

---

Examples

토큰 설정

# gcube 웹 프론트에서 복사한 토큰 설정
gcube configure set --token "eyJ..."

# 설정 상태 확인
gcube configure status

# 대화형 설정 (플랫폼 URL, 토큰, 출력 형식을 순서대로 입력)
gcube configure

워크로드 등록 및 관리

# YAML 파일로 학습 잡 등록
gcube workload register -f train.yaml

# 인라인 플래그로 인퍼런스 서비스 등록 (GPU CODE는 gcube gpu list에서 확인)
gcube workload register \
  --image pytorch/pytorch:2.0-cuda12.0 \
  --gpu 029 \
  --cuda 12020 \
  --category infer

# 내 워크로드만 조회
gcube workload list --owner [e-mail]

# 특정 워크로드 상세 + JSON 출력
gcube -o json workload describe my-train-job

# 실시간 로그 스트리밍 (단일 pod/컨테이너)
gcube workload logs 2041

# 멀티 pod/컨테이너 — 목록 확인 후 지정
gcube workload logs 2095
gcube workload logs 2095 --pod 0 --container 1

# 워크로드 중지 후 삭제
gcube workload stop my-train-job
gcube workload delete my-train-job

리소스 모니터링

# 워크로드 리소스 사용량 (시간 평균)
gcube resource workload my-train-job

# JSON 출력
gcube -o json resource workload my-train-job

사용자 및 크레덴셜 관리

# 사용자 검색
gcube user list --keyword kim

# 사용자 생성
gcube user create --email [e-mail] --name "Kim Gildong" --role user

# 크레덴셜 발급
gcube user credentials create [e-mail] --name "dev-key"

# 플랫폼 토큰 발급 (다른 도구 연동용)
gcube user token [e-mail]

CI/CD 파이프라인

# 환경변수로 인증 (토큰 사전 발급)
export GCUBE_ACCESS_TOKEN="eyJ..."
export GCUBE_OUTPUT=json

# 파이프라인에서 워크로드 등록 후 상태 확인
gcube workload register -f pipeline.yaml
gcube workload describe pipeline-job-001 | jq '.state'

GAI / AstraGo 백엔드

# GAI 네임스페이스 워크로드 목록
gcube workload list --namespace gai

# AstraGo 백엔드 워크로드 상세
gcube workload describe my-job --backend astrago

---

Development

# 소스 클론 및 개발 환경 설치
git clone https://github.com/data-alliance/gcube-cli.git
cd gcube-cli
pip install -e ".[dev]"

# 테스트
pytest --cov=gcube_cli --cov-report=term-missing

# 빌드
python -m build

---

Contributing

버그 리포트 및 기능 요청은 GitHub Issues를 이용한다.

---

License

Apache License 2.0 — LICENSE 참조