pvcli Reference

Client CLIConnectRPC / gRPCOAuth2 & Contexts

pvcli is the primary command-line tool for managing virtual machines, storage volumes, images, networks, and organizations across PiVirt clusters. It communicates with the PiVirt Agent via ConnectRPC / gRPC.

---

Global Syntax & Flags

pvcli [command] [subcommand] [flags]

Global Flags

Flag	Shorthand	Description	Default
--context	-c	Name of the context to use from ~/.config/pvcli/config.yaml	Current context
--output	-o	Output format: table, json, yaml, wide	table
--insecure		Disable TLS verification (development mode only)	false
--help	-h	Display help and flag details

---

Command Reference

pvcli auth

Manage user sessions and authentication tokens.

# Login via OAuth2 Device Code flow
pvcli auth login

# Login targeting a specific organization
pvcli auth login --organization dev-team

# Display current authenticated user profile
pvcli auth whoami

# Invalidate session token and clean up local credentials
pvcli auth logout

---

pvcli context

Manage connection targets, credentials, and default organizations.

# List all configured contexts
pvcli context list

# Display active context
pvcli context current

# Add a new context
pvcli context add prod agent.prod.pilab.hu 5001
pvcli context add dev localhost 5001 --insecure

# Switch active context
pvcli context switch prod

# Modify context parameters
pvcli context set dev --insecure=true

# Remove context
pvcli context remove staging

---

pvcli vm (Virtual Machines)

Create and manage VM lifecycles.

List & Inspect

# List all virtual machines
pvcli vm list
pvcli vm ls

# Get VM details in table, JSON, or YAML
pvcli vm get <vm-id-or-name>
pvcli vm get web-server -o json
pvcli vm get web-server -o yaml

Create & Configure

# Create a VM with flags
pvcli vm create \
  --name web-01 \
  --image ubuntu-24.04 \
  --cpus 4 \
  --memory 8G \
  --disk 50G \
  --network tenant-net

# Update VM resource allocations
pvcli vm set web-01 --cpus 8 --memory 16G

# Autostart configuration
pvcli vm autostart list
pvcli vm autostart enable web-01
pvcli vm autostart disable web-01

Power & Lifecycle

# Power operations
pvcli vm start web-01
pvcli vm stop web-01
pvcli vm restart web-01
pvcli vm pause web-01
pvcli vm unpause web-01

# Clone an existing VM
pvcli vm clone web-01 --name web-02

# Rebuild VM with a clean OS image
pvcli vm rebuild web-01 --image debian-12

# Export / Import VM packages
pvcli vm export web-01 --output /backup/web-01.ova
pvcli vm import --file /backup/web-01.ova --name web-restored

# Delete VM
pvcli vm delete web-01 --force

---

pvcli disk (Disks & Volumes)

Manage storage volumes and VM attachments.

# List all disks
pvcli disk list

# Create a storage volume
pvcli disk create --name db-data --size 200G --pool default

# Attach / Detach disk
pvcli disk attach <disk-id> --vm <vm-id>
pvcli disk detach <disk-id> --vm <vm-id>

# Online capacity extension
pvcli disk extend <disk-id> --size 400G

# Update disk metadata
pvcli disk update <disk-id> --description "Production database volume"

# Delete disk
pvcli disk delete <disk-id>

---

pvcli image (Image Catalog)

Manage OS images and custom templates.

# List OS images available in osinfodb catalog
pvcli image list

# Inspect image details
pvcli image get ubuntu-24.04

# Pull image from official registry
pvcli image pull ubuntu-24.04

# Upload custom QCOW2 or RAW image
pvcli image upload --file ./app-server.qcow2 --name app-server-v1

# Delete custom image
pvcli image delete <image-id>

---

pvcli network (Virtual Networks)

Manage SDN bridges, subnets, and VM network interfaces.

# List virtual networks
pvcli network list

# Inspect network details and IP allocations
pvcli network get tenant-net

# Create virtual network
pvcli network create \
  --name tenant-net \
  --subnet 10.100.0.0/24 \
  --gateway 10.100.0.1 \
  --dhcp

# List interfaces on a VM
pvcli network interfaces <vm-id>

# Add interface to VM
pvcli network add-interface <vm-id> --network tenant-net

# Remove interface by MAC
pvcli network remove-interface <vm-id> --mac 52:54:00:12:34:56

# Delete virtual network
pvcli network delete tenant-net

---

pvcli snapshot (Snapshots & Rollbacks)

Point-in-time state capture for VMs and attached storage.

# List snapshots for a VM
pvcli snapshot list <vm-id>

# Create snapshot (including memory state if running)
pvcli snapshot create <vm-id> --name pre-migration-snapshot

# Revert VM to a snapshot
pvcli snapshot restore <vm-id> --snapshot pre-migration-snapshot

# Delete snapshot
pvcli snapshot delete <vm-id> --snapshot pre-migration-snapshot

---

pvcli org (Organizations & Tenancy)

Manage multi-tenant organizations and quotas.

# List organizations
pvcli org list

# Get organization details & resource usage
pvcli org get <org-id>

# Create organization
pvcli org create --name engineering-team --quota-cpus 64 --quota-ram 256G

# Update organization quotas
pvcli org update engineering-team --quota-cpus 128

# Delete organization
pvcli org delete engineering-team

---

pvcli ui (Interactive Terminal UI)

Launch the interactive BubbleTea-powered Terminal UI (TUI) for real-time monitoring and dashboard navigation:

pvcli ui