README.md

Hyperstack CLI Client

Minimal PSR-compliant PHP 8.3 CLI project for managing Hyperstack virtual machines through the Infrahub API.

Features

• List virtual machines with optional local filtering.
• Create one or more virtual machines from a JSON payload or CLI options.
• Delete virtual machines by ID.
• List available Hyperstack flavors.

Requirements

• PHP 8.3 with ext-curl and ext-json
• A Hyperstack API key in HYPERSTACK_API_KEY

API references

• Hyperstack API reference: https://docs.hyperstack.cloud/docs/api-reference/
• Infrahub base URL: https://infrahub-api.nexgencloud.com/v1
• Virtual machines: GET/POST/DELETE /core/virtual-machines
• Flavors: GET /core/flavors

Usage

export HYPERSTACK_API_KEY=your-api-key
chmod +x bin/hyperstack-client

Show help:

bin/hyperstack-client help

List virtual machines:

bin/hyperstack-client vms:list
bin/hyperstack-client vms:list --status=ACTIVE --environment-name=my-env
bin/hyperstack-client vms:list --json

Create a virtual machine from the included example payload:

bin/hyperstack-client vms:create --payload=examples/create-vm.json

Create a virtual machine directly from CLI flags:

bin/hyperstack-client vms:create \
  --name=a100-trainer \
  --environment-name=my-env \
  --flavor-name=n3-A100x1 \
  --image-name="Ubuntu Server 22.04 LTS R535 CUDA 12.2" \
  --key-name=my-key \
  --assign-floating-ip

Delete a virtual machine:

bin/hyperstack-client vms:delete --id=<vm-id>

List flavors:

bin/hyperstack-client flavors:list
bin/hyperstack-client flavors:list --gpu=A100
bin/hyperstack-client flavors:list --json

Notes

• examples/create-vm.json is a starter payload that mirrors the Hyperstack VM creation schema used by this client.
• Hyperstack environments are required for VM creation, and keypairs are environment-scoped.
• Some advanced Hyperstack fields can still be passed through the JSON payload even when no dedicated CLI flag exists.