gcube-cli 0.1.1

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 · websockets

---

Installation

pip install gcube-cli

---

Quick Start

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

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

# 3. 상태 확인
gcube workload list

# 4. 로그 조회
gcube workload logs <ser>

---

Configuration

토큰 발급 및 설정

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

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

설정 파일

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

platform_url: https://api.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
GCUBE_ACCESS_TOKEN	Bearer 토큰 직접 지정 (CI/CD용)
GCUBE_OUTPUT	기본 출력 형식 (table|json|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 <ser>	워크로드 상세 조회
gcube workload start <ser>	워크로드 시작
gcube workload stop <ser>	워크로드 중지
gcube workload delete <ser>	워크로드 삭제
gcube workload logs <ser>	컨테이너 로그 실시간 스트리밍
gcube workload logs <ser> --pod <idx> --container <idx>	특정 컨테이너 로그 스트리밍
gcube workload pods <ser>	Pod 목록 조회

주요 플래그

플래그	설명
-f, --file <path>	워크로드 YAML 파일 경로
--image <image>	컨테이너 이미지
--gpu <code>	GPU 코드 (gcube gpu list의 CODE 컬럼)
--cuda <version>	CUDA 버전 코드
--category <type>	워크로드 유형: infer|learn
--owner <email>	워크로드 소유자 (list 필터)
--pod <idx>	Pod 인덱스 (logs용, 0-based)
--container <idx>	컨테이너 인덱스 (logs용, 0-based)
-y, --yes	확인 프롬프트 건너뛰기 (stop/delete)

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 컬럼 표시)

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

---

Resource

워크로드의 CPU·GPU·메모리 사용량을 조회한다.

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

---

Point

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

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

---

Credential

컨테이너 이미지 저장소 인증정보를 관리한다.

명령	설명
gcube credential list	등록된 크레덴셜 목록
gcube credential create --repo <type> --username <name> --token <token>	크레덴셜 등록
gcube credential delete --repo <type>	크레덴셜 삭제

--repo 지원 유형: docker, github, harbor, aws, huggingface, quay

---

Output Formats

-o 플래그로 출력 형식을 선택한다.

gcube workload list              # table (기본값)
gcube -o json workload list      # JSON
gcube -o yaml workload list      # YAML

---

Global Options

플래그	설명	기본값
-o, --output <format>	출력 형식: table|json|yaml	table
-V, --version	버전 출력	—
--help	도움말 출력	—

---

Exit Codes

코드	의미
0	성공
1	잘못된 인수 또는 상태 오류
2	gcube API 오류
3	인증 실패 또는 토큰 만료
4	네트워크 오류

---

Examples

워크로드 등록 및 관리

# GPU 목록 확인 (CODE 컬럼 참고)
gcube gpu list

# YAML 파일로 워크로드 등록
gcube workload register -f workload.yaml

# 인라인 플래그로 등록 (단일 컨테이너 및 레플리카만 가능)
gcube workload register \
  --description "inference service" \
  --image ollama/ollama:latest \
  --gpu 029

# 워크로드 목록 및 상세
gcube workload list
gcube workload describe 2212
gcube -o json workload describe 2212

# 시작 / 중지 / 삭제
gcube workload start 2212
gcube workload stop 2212
gcube workload delete 2212

로그 스트리밍

# 싱글 컨테이너 — 바로 스트리밍
gcube workload logs 2212

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

리소스 모니터링

gcube resource workload 2212
gcube -o json resource workload 2212

CI/CD 파이프라인

# 환경변수로 인증
export GCUBE_ACCESS_TOKEN="eyJ..."
export GCUBE_OUTPUT=json

gcube workload register -f pipeline.yaml
gcube workload describe 2212 | jq '.state'

---

License

Apache License 2.0