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

Official command-line tool for the [gcube AI GPU cloud platform](https://gcube.ai).
Manage GPU workloads, monitor resources, and stream container logs — all from your terminal.

---

## Overview

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

| Feature | Description |
|---|---|
| Easy install | `pip install gcube-cli`, Python 3.10+ |
| AWS CLI style | `gcube <service> <operation>` with `--output table\|json\|yaml` |
| Token auth | Set your token from the gcube web console once, then use all commands |
| Key dependencies | click · httpx · rich · pyyaml · websockets |

---

## Installation

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

---

## Quick Start

```bash
# 1. Set your API token (copy from gcube web console)
gcube configure set --token "eyJ..."

# 2. Register a GPU workload
gcube workload register -f workload.yaml

# 3. Check status
gcube workload list

# 4. Stream logs
gcube workload logs <ser>
```

---

## Configuration

### Get a Token

1. Log in to the [gcube web console](https://gcube.ai)
2. Go to **API Token** menu and copy your token
3. Set it in the CLI:

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

### Config File

Generated automatically at `~/.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
```

### Configure Commands

```
gcube configure                              # Interactive setup
gcube configure set --token <token>          # Set API token
gcube configure set --platform-url <url>     # Set platform URL
gcube configure set --ws-url <url>           # Set WebSocket URL (for log streaming)
gcube configure set --output <format>        # Set default output format
gcube configure get <key>                    # Get a config value (token, platform-url, ws-url, output)
gcube configure status                       # Show current config and token validity
```

### Environment Variables

Environment variables take precedence over the config file.

| Variable | Description |
|---|---|
| `GCUBE_PLATFORM_URL` | Platform base URL |
| `GCUBE_ACCESS_TOKEN` | Bearer token (useful for CI/CD) |
| `GCUBE_OUTPUT` | Default output format (`table`\|`json`\|`yaml`) |

---

## Command Reference

### Workload

Manage the full lifecycle of GPU workloads.

| Command | Description |
|---|---|
| `gcube workload register -f <yaml>` | Register a workload from a YAML file |
| `gcube workload register --image <img> ...` | Register a workload with inline flags |
| `gcube workload update <ser> -f <yaml>` | Update a stopped workload |
| `gcube workload list` | List workloads |
| `gcube workload describe <ser>` | Show workload details |
| `gcube workload start <ser>` | Start a workload |
| `gcube workload stop <ser>` | Stop a workload |
| `gcube workload delete <ser>` | Delete a workload |
| `gcube workload logs <ser>` | Stream container logs in real time |
| `gcube workload logs <ser> --pod <idx> --container <idx>` | Stream a specific container's logs |
| `gcube workload pods <ser>` | List pods |

**Key Flags**

| Flag | Description |
|---|---|
| `-f, --file <path>` | Workload YAML file path |
| `--image <image>` | Container image |
| `--gpu <code>` | GPU code (from `gcube gpu list` CODE column) |
| `--cuda <version>` | CUDA version code |
| `--category <type>` | Workload type: `infer`\|`learn` |
| `--owner <email>` | Filter by owner (list only) |
| `--pod <idx>` | Pod index for log streaming (0-based) |
| `--container <idx>` | Container index for log streaming (0-based) |
| `-y, --yes` | Skip confirmation prompt (stop/delete) |

**CUDA Version Codes** (format: major×1000 + minor×10)

| Code | 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 |

**Workload YAML Format** (for `register -f` and `update -f`)

```yaml
# workload.yaml
description: "My ML training job"  # required, 2-80 chars
cuda: "12020"                      # optional CUDA version code
sharedMemory: 1                    # GB

containers:
  - containerImage: "pytorch/pytorch:2.0"  # required
    repo: docker.io
    port: 0                        # 0 = auto-detect
    maxConnection: 4
    containerCommand: "python train.py"
    isCredential: false
    containerEnvs:
      - EPOCHS: "100"
      - BATCH_SIZE: "32"

gpuSpecs:
  - gpuCode: "029"                 # required — CODE from 'gcube gpu list'
  # add more entries for multiple replicas:
  # - gpuCode: "029"
```

> Run `gcube workload register --skeleton` to print a blank template.
> Run `gcube workload update <ser> --skeleton > workload.yaml` to export the current config, then fill in `gpuCode` and pass it with `-f`.

---

### GPU

List available GPUs with specs and pricing.

| Command | Description |
|---|---|
| `gcube gpu list` | Available GPUs (CODE, specs, hourly price range) |
| `gcube gpu list --all` | All GPUs including unavailable ones |

> The CODE column is a zero-padded sequence number (001, 002, ...) used when registering workloads.

---

### Resource

Monitor CPU, GPU, and memory usage of a workload.

| Command | Description |
|---|---|
| `gcube resource workload <ser>` | Workload resource usage (time average) |

---

### Point

Check point balance and spending history.

| Command | Description |
|---|---|
| `gcube point status` | Balance, total charged/spent, low-balance warning |
| `gcube point spending` | Daily spending for the current month |
| `gcube point spending --month 2026-03` | Daily spending for a specific month |
| `gcube point spending --workload <ser>` | Filter by workload |

---

### Credential

Manage container registry credentials.

| Command | Description |
|---|---|
| `gcube credential list` | List saved credentials |
| `gcube credential create --repo <type> --username <name> --token <token>` | Save a credential |
| `gcube credential delete --repo <type>` | Delete a credential |

Supported `--repo` types: `docker`, `github`, `harbor`, `aws`, `huggingface`, `quay`

---

## Output Formats

```bash
gcube workload list              # table (default)
gcube -o json workload list      # JSON
gcube -o yaml workload list      # YAML
```

---

## Global Options

| Flag | Description | Default |
|---|---|---|
| `-o, --output <format>` | Output format: `table`\|`json`\|`yaml` | `table` |
| `-V, --version` | Show version | — |
| `--help` | Show help | — |

---

## Exit Codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Invalid argument or state error |
| `2` | gcube API error |
| `3` | Authentication failure or token expired |
| `4` | Network error |

---

## Examples

### Register and Manage Workloads

```bash
# Check available GPUs (note the CODE column)
gcube gpu list

# Register from a YAML file
gcube workload register -f workload.yaml

# Register with inline flags
gcube workload register \
  --description "inference service" \
  --image ollama/ollama:latest \
  --gpu 029

# List and inspect
gcube workload list
gcube workload describe 2212
gcube -o json workload describe 2212

# Start / stop / delete
gcube workload start 2212
gcube workload stop 2212
gcube workload delete 2212
```

### Stream Logs

```bash
# Single container — streams immediately
gcube workload logs 2212

# Multi-container — shows selection list first
gcube workload logs 2226
gcube workload logs 2226 --pod 0 --container 1
```

### Resource Monitoring

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

### CI/CD Pipeline

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