Metadata-Version: 2.4
Name: gcube-cli
Version: 0.1.0
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.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 |

---

## Installation

### pip 설치 (권장)

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

### 소스 설치

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

---

## Quick Start

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

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

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

### 설정 파일

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

```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 등)을 전환한다.

```bash
# 개발 환경 토큰 설정
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` 공통)

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

```bash
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":"user@example.com","category":"learn","gpu":"RTX4090","gpuCount":2,"state":"running"},
  {"ser":"def456","owner":"admin@example.com","category":"infer","gpu":"A100","gpuCount":1,"state":"stopped"}
]
```

### yaml

```
$ gcube -o yaml workload list

- ser: abc123
  owner: user@example.com
  category: learn
  gpu: RTX4090
  gpuCount: 2
  state: running
- ser: def456
  owner: admin@example.com
  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.` |

스크립트에서 활용:

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

### 토큰 설정

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

# 설정 상태 확인
gcube configure status

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

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

```bash
# 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 me@example.com

# 특정 워크로드 상세 + 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
```

### 리소스 모니터링

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

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

### 사용자 및 크레덴셜 관리

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

# 사용자 생성
gcube user create --email new@example.com --name "Kim Gildong" --role user

# 크레덴셜 발급
gcube user credentials create kim@example.com --name "dev-key"

# 플랫폼 토큰 발급 (다른 도구 연동용)
gcube user token kim@example.com
```

### CI/CD 파이프라인

```bash
# 환경변수로 인증 (토큰 사전 발급)
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 백엔드

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

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

---

## Development

```bash
# 소스 클론 및 개발 환경 설치
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](https://github.com/data-alliance/gcube-cli/issues)를 이용한다.

---

## License

Apache License 2.0 — [LICENSE](LICENSE) 참조
