Skip to content

Commit dcc8bbb

Browse files
adhikjoshiadhikjoshi
committed
initial commit
1 parent b4eccc2 commit dcc8bbb

30 files changed

Lines changed: 3915 additions & 0 deletions

‎.goreleaser.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
version: 2
2+
3+
builds:
4+
- main: ./cmd/gpulab
5+
binary: gpulab
6+
env:
7+
- CGO_ENABLED=0
8+
goos:
9+
- darwin
10+
- linux
11+
goarch:
12+
- amd64
13+
- arm64
14+
ldflags:
15+
- -s -w
16+
- -X main.version={{.Version}}
17+
- -X main.commit={{.Commit}}
18+
- -X main.date={{.Date}}
19+
20+
archives:
21+
- format: tar.gz
22+
name_template: "gpulab_{{ .Os }}_{{ .Arch }}"
23+
24+
checksum:
25+
name_template: "checksums.txt"
26+
27+
changelog:
28+
sort: asc
29+
filters:
30+
exclude:
31+
- "^docs:"
32+
- "^test:"

‎Makefile‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
2+
COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo "none")
3+
DATE ?= $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
4+
LDFLAGS = -s -w -X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(DATE)
5+
6+
.PHONY: build install clean test lint
7+
8+
build:
9+
CGO_ENABLED=0 go build -ldflags "$(LDFLAGS)" -o bin/gpulab ./cmd/gpulab
10+
11+
install: build
12+
cp bin/gpulab /usr/local/bin/gpulab
13+
14+
clean:
15+
rm -rf bin/
16+
17+
test:
18+
go test ./...
19+
20+
lint:
21+
go vet ./...
22+
23+
# Cross-compile for all platforms
24+
build-all:
25+
GOOS=darwin GOARCH=amd64 CGO_ENABLED=0 go build -ldflags "$(LDFLAGS)" -o bin/gpulab-darwin-amd64 ./cmd/gpulab
26+
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -ldflags "$(LDFLAGS)" -o bin/gpulab-darwin-arm64 ./cmd/gpulab
27+
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags "$(LDFLAGS)" -o bin/gpulab-linux-amd64 ./cmd/gpulab
28+
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -ldflags "$(LDFLAGS)" -o bin/gpulab-linux-arm64 ./cmd/gpulab

‎README.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# GPULab CLI
2+
3+
Command-line interface for [GPULab](https://gpulab.ai) — deploy, manage, and interact with GPU containers from your terminal.
4+
5+
## Install
6+
7+
```bash
8+
# macOS / Linux
9+
curl -fsSL https://gpulab.ai/cli.sh | sh
10+
11+
# Or build from source
12+
go install github.com/gpulab/gpulab-cli/cmd/gpulab@latest
13+
14+
# Or clone and build
15+
git clone https://github.com/gpulab/gpulab-cli.git
16+
cd gpulab-cli
17+
make install
18+
```
19+
20+
## Quick Start
21+
22+
```bash
23+
# Authenticate
24+
gpulab auth login --api-key gpulab_xxx
25+
26+
# List containers
27+
gpulab ls
28+
29+
# Deploy a container
30+
gpulab deploy --name my-project --template pytorch --gpu-type "RTX 4090" --wait
31+
32+
# Execute commands
33+
gpulab exec <uuid> -- nvidia-smi
34+
gpulab exec <uuid> -- python train.py
35+
36+
# View logs
37+
gpulab logs <uuid> --follow
38+
39+
# SSH into container
40+
gpulab ssh <uuid>
41+
42+
# Stop and delete
43+
gpulab stop <uuid>
44+
gpulab rm <uuid> --force
45+
```
46+
47+
## Deploy
48+
49+
The `deploy` command supports Docker-style syntax for ports, environment variables, and commands.
50+
51+
### Ports
52+
53+
```bash
54+
# Comma-separated list
55+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
56+
--ports "8080,3000,6006"
57+
58+
# Docker-style repeatable flag
59+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
60+
-p 8080 -p 3000 -p 6006
61+
62+
# host:container syntax (host port is auto-assigned by GPULab)
63+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
64+
-p 8080:80 -p 3000:3000
65+
66+
# Both styles can be combined
67+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
68+
--ports "8080" -p 3000 -p 6006
69+
```
70+
71+
### Startup Command
72+
73+
```bash
74+
# Using --command flag
75+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
76+
--command "python train.py"
77+
78+
# Docker-style — everything after -- becomes the command
79+
# Useful when the command has its own flags
80+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
81+
--wait -- python train.py --epochs 100 --lr 0.001
82+
83+
gpulab deploy --name sglang --template pytorch --gpu-type "RTX 4090" \
84+
-- sglang.deploy --model meta-llama/Llama-3-8B --tp 4
85+
```
86+
87+
### Environment Variables
88+
89+
```bash
90+
# Set variables explicitly (Docker-style)
91+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
92+
-e HF_TOKEN=hf_xxx \
93+
-e WANDB_API_KEY=abc123 \
94+
-e MODEL_NAME=meta-llama/Llama-3-8B
95+
96+
# Inherit from host environment (just pass the key name)
97+
export HF_TOKEN=hf_xxx
98+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
99+
-e HF_TOKEN -e WANDB_API_KEY
100+
101+
# Load from an env file
102+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
103+
--env-file .env
104+
105+
# Combine all three — -e flags override --env-file values
106+
gpulab deploy --name test --template pytorch --gpu-type "RTX 4090" \
107+
--env-file .env \
108+
-e HF_TOKEN=hf_override \
109+
-e WANDB_API_KEY
110+
```
111+
112+
The `--env-file` format supports standard `.env` syntax:
113+
114+
```bash
115+
# .env
116+
HF_TOKEN=hf_xxx
117+
WANDB_API_KEY=abc123
118+
MODEL_NAME="meta-llama/Llama-3-8B"
119+
export CUDA_VISIBLE_DEVICES=0,1
120+
# Comments and blank lines are ignored
121+
```
122+
123+
### Full Deploy Example
124+
125+
```bash
126+
gpulab deploy \
127+
--name training-run \
128+
--template pytorch \
129+
--gpu-type "RTX 4090" \
130+
--memory 32 \
131+
--ports "8080,6006" \
132+
--env-file .env \
133+
-e HF_TOKEN \
134+
-e RUN_ID=experiment-42 \
135+
--volume my-volume-uuid \
136+
--wait \
137+
-- python train.py --epochs 100 --lr 0.001 --batch-size 32
138+
```
139+
140+
## Commands
141+
142+
| Command | Description |
143+
|---------|-------------|
144+
| `gpulab auth login` | Authenticate with API key |
145+
| `gpulab auth whoami` | Show current user |
146+
| `gpulab ls` | List all containers |
147+
| `gpulab inspect <uuid>` | Show container details |
148+
| `gpulab deploy` | Deploy a new container |
149+
| `gpulab stop <uuid>` | Stop a container |
150+
| `gpulab start <uuid>` | Start a stopped container |
151+
| `gpulab restart <uuid>` | Restart a container |
152+
| `gpulab redeploy <uuid>` | Redeploy a container |
153+
| `gpulab rm <uuid>` | Delete a container |
154+
| `gpulab logs <uuid>` | View container logs |
155+
| `gpulab stats <uuid>` | View resource usage |
156+
| `gpulab exec <uuid> -- <cmd>` | Execute a command |
157+
| `gpulab ssh <uuid>` | Interactive terminal |
158+
| `gpulab templates` | List templates |
159+
| `gpulab gpus types` | List GPU types |
160+
| `gpulab volumes` | List volumes |
161+
162+
## Global Flags
163+
164+
| Flag | Description |
165+
|------|-------------|
166+
| `--json` | Output in JSON format (for scripting/AI agents) |
167+
| `-q, --quiet` | Quiet output (UUIDs only) |
168+
| `--api-key` | Override API key |
169+
| `--debug` | Debug mode (show HTTP requests) |
170+
171+
## Configuration
172+
173+
Config is stored at `~/.gpulab/config.json`. API key priority:
174+
175+
1. `--api-key` flag
176+
2. `GPULAB_API_KEY` environment variable
177+
3. Config file
178+
179+
## AI Agent Usage
180+
181+
The CLI is designed for AI agent integration (Claude Code, Cursor, etc.):
182+
183+
```bash
184+
export GPULAB_API_KEY=gpulab_xxx
185+
186+
# Deploy with env vars and capture UUID
187+
UUID=$(gpulab deploy \
188+
--name ai-test \
189+
--template pytorch \
190+
--gpu-type "RTX 4090" \
191+
-e HF_TOKEN -e WANDB_API_KEY \
192+
--wait --json | jq -r '.container_id')
193+
194+
# Run commands
195+
gpulab exec $UUID -- nvidia-smi
196+
gpulab exec $UUID -- python -c "print('hello')"
197+
198+
# Write and run a script
199+
gpulab exec $UUID -- sh -c 'echo "print(42)" > /workspace/test.py'
200+
gpulab exec $UUID -- python /workspace/test.py
201+
202+
# JSON output for parsing
203+
gpulab ls --json
204+
gpulab stats $UUID --json
205+
206+
# Cleanup
207+
gpulab stop $UUID
208+
gpulab rm $UUID --force
209+
```

‎bin/gpulab‎

10.8 MB
Binary file not shown.

0 commit comments

Comments
 (0)