Metadata-Version: 2.4
Name: gcube-cli
Version: 0.1.1
Summary: Official command-line tool for the gcube AI GPU cloud platform
Author-email: Data Alliance <support@data-alliance.com>
License: Apache-2.0
Project-URL: Homepage, https://gcube.ai
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click<8.3,>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: websockets>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"

# gcube CLI

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

---

## Overview

```
gcube <service> <operation> [options]
```

`gcube`는 [gcube 플랫폼](https://gcube.ai)의 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

```bash
pip install gcube-cli
```

---

## Quick Start

```bash
# 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 웹 프론트](https://gcube.ai)에 로그인
2. "API 토큰 발급" 메뉴에서 토큰 복사
3. CLI에서 토큰 설정:

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

### 설정 파일

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

```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` 공통)

```yaml
# 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` 플래그로 출력 형식을 선택한다.

```bash
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

### 워크로드 등록 및 관리

```bash
# 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
```

### 로그 스트리밍

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

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

### 리소스 모니터링

```bash
gcube resource workload 2212
gcube -o json resource workload 2212
```

### CI/CD 파이프라인

```bash
# 환경변수로 인증
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
