gpu-cli

GPU CLI

GPU CLI runs local commands on remote NVIDIA GPUs by prefixing with gpu. It provisions a pod, syncs your code, streams logs, and syncs outputs back: uv run python train.py becomes gpu run uv run python train.py.

Quick diagnostics

gpu doctor --json       # Check if setup is healthy (daemon, auth, provider keys)
gpu status --json       # See running pods and costs
gpu inventory --json    # See available GPUs and pricing

Command families

Getting started

Command	Purpose
gpu login	Browser-based authentication
gpu logout [-y]	Remove session
gpu init [--gpu-type T] [--force]	Initialize project config
gpu upgrade	Open subscription upgrade page

Running code

Command	Purpose
gpu run <command>	Execute on remote GPU (main command)
gpu run -d <command>	Run detached (background)
gpu run -a <job_id>	Reattach to running job
gpu run --cancel <job_id>	Cancel a running job
gpu status [--json]	Show project status, pods, costs
gpu logs [-j JOB] [-f] [--tail N] [--json]	View job output
gpu attach <job_id>	Reattach to job output stream
gpu stop [POD_ID] [-y]	Stop active pod

Key gpu run flags: --gpu-type, --gpu-count <1-8>, --min-vram, --rebuild, -o/--output, --no-output, --sync, -p/--publish <PORT>, -e <KEY=VALUE>, -i/--interactive.

GPU inventory

Command	Purpose
gpu inventory [--available] [--min-vram N] [--max-price P] [--json]	List GPUs with pricing

Volumes

Command	Purpose
gpu volume list [--detailed] [--json]	List network volumes
gpu volume create [--name N] [--size GB] [--datacenter DC]	Create volume
gpu volume delete <VOL> [--force]	Delete volume
gpu volume extend <VOL> --size <GB>	Increase size
gpu volume set-global <VOL>	Set default volume
gpu volume status [--volume V] [--json]	Volume usage
gpu volume migrate <VOL> --to <DC>	Migrate to datacenter
gpu volume sync <SRC> <DEST>	Sync between volumes

Vault (encrypted storage)

Command	Purpose
gpu vault list [--json]	List encrypted output files
gpu vault export <PATH> <DEST>	Export decrypted file
gpu vault stats [--json]	Storage usage stats

Configuration

Command	Purpose
gpu config show [--json]	Show merged config
gpu config validate	Validate against schema
gpu config schema	Print JSON schema
gpu config set <KEY> <VALUE>	Set global config option
gpu config get <KEY>	Get global config value

Authentication

Command	Purpose
gpu auth login [--profile P]	Authenticate with cloud provider
gpu auth logout	Remove credentials
gpu auth status	Show auth status
gpu auth add <HUB>	Add hub credentials (hf, civitai)
gpu auth remove <HUB>	Remove hub credentials
gpu auth hubs	List configured hubs

Organizations

Command	Purpose
gpu org list	List organizations
gpu org create <NAME>	Create organization
gpu org switch [SLUG]	Set active org context
gpu org invite <EMAIL>	Invite member
gpu org service-account create --name N	Create service token
gpu org service-account list	List service accounts
gpu org service-account revoke <ID>	Revoke token

LLM inference

Command	Purpose
gpu llm run [--ollama|--vllm] [--model M] [-y]	Launch LLM inference
gpu llm info [MODEL] [--url URL] [--json]	Show model info

ComfyUI workflows

Command	Purpose
gpu comfyui list [--json]	Browse available workflows
gpu comfyui info <WORKFLOW> [--json]	Show workflow details
gpu comfyui validate <WORKFLOW> [--json]	Pre-flight checks
gpu comfyui run <WORKFLOW>	Run workflow on GPU
gpu comfyui generate "<PROMPT>"	Text-to-image generation
gpu comfyui stop [WORKFLOW] [--all]	Stop ComfyUI pod

Notebooks

Command	Purpose
gpu notebook [FILE] [--run] [--new NAME]	Run Marimo notebook on GPU

Alias: gpu nb

Serverless endpoints

Command	Purpose
gpu serverless deploy [--template T] [--json]	Deploy endpoint
gpu serverless status [ENDPOINT] [--json]	Endpoint status
gpu serverless logs [ENDPOINT]	View request logs
gpu serverless list [--json]	List all endpoints
gpu serverless delete [ENDPOINT]	Delete endpoint
gpu serverless warm [--cpu|--gpu]	Pre-warm endpoint

Templates

Command	Purpose
gpu template list [--json]	Browse official templates
gpu template clear-cache	Clear cached templates

Daemon control

Command	Purpose
gpu daemon status [--json]	Show daemon health
gpu daemon start	Start daemon
gpu daemon stop	Stop daemon
gpu daemon restart	Restart daemon
gpu daemon logs [-f] [-n N]	View daemon logs

Tools and utilities

Command	Purpose
gpu dashboard	Interactive TUI for pods and jobs
gpu doctor [--json]	Diagnostic checks
gpu agent-docs	Print agent reference to stdout
gpu update [--check]	Update CLI
gpu changelog [VERSION]	View release notes
gpu issue ["desc"]	Report issue
gpu desktop	Desktop app management
gpu support	Open community Discord

Common workflows

1. Setup: gpu login then gpu init
2. Run job: gpu run python train.py --epochs 10
3. With specific GPU: gpu run --gpu-type "RTX 4090" python train.py
4. Detached job: gpu run -d python long_training.py then gpu status --json
5. Check status: gpu status --json
6. View logs: gpu logs --json
7. Stop pods: gpu stop -y
8. LLM inference: gpu llm run --ollama --model llama3 -y
9. ComfyUI: gpu comfyui run flux_schnell
10. Diagnose issues: gpu doctor --json

gpu run is pod-reuse oriented: after a command completes, the next gpu run reuses the existing pod until you gpu stop or cooldown ends.

JSON output

Most commands support --json for machine-readable output. Structured data goes to stdout; human-oriented status and progress messages go to stderr.

Commands with --json: status, logs, doctor, inventory, config show, daemon status, volume list, volume status, vault list, vault stats, comfyui list, comfyui info, comfyui validate, serverless deploy, serverless status, serverless list, template list, llm info.

Exit codes

Code	Meaning	Recovery
0	Success	Proceed
1	General error	Read stderr
2	Usage error	Fix command syntax
10	Auth required	gpu auth login
11	Quota exceeded	gpu upgrade or wait
12	Not found	Check resource ID
13	Daemon unavailable	gpu daemon start, retry
14	Timeout	Retry
15	Cancelled	Re-run if needed
130	Interrupted	Re-run if needed

Configuration

• Project config: gpu.toml, gpu.jsonc, or pyproject.toml [tool.gpu]
• Global config: ~/.gpu-cli/config.toml (via gpu config set/get)
• Sync model: .gitignore controls upload; outputs patterns control download
• Secrets and credentials must stay in the OS keychain, never plaintext project files
• CI env vars: GPU_RUNPOD_API_KEY, GPU_SSH_PRIVATE_KEY, GPU_SSH_PUBLIC_KEY

References

• Project generation and task setup: references/create.md
• Debugging and common failures: references/debug.md
• Config schema and field examples: references/config.md
• Cost and GPU selection guidance: references/optimize.md
• Persistent storage and volumes: references/volumes.md