pivirtctl Reference & Resource Kinds

Host CLIDeclarative GitOpsUnix Socket gRPCapiVersion: pivirt.hu/v1

pivirtctl is the direct host-level command-line tool for managing the pivirtd hypervisor runtime. It talks directly to pivirtd over a private Unix domain socket (/var/run/pivirt/pivirtd.sock or $PIVIRTD_SOCKET), providing both a declarative Kubernetes-style GitOps engine (apply, get, describe, delete) and imperative operational commands (vm, disk, snapshot, device).

Scope: pivirtctl vs. pvcli

• pivirtctl is host-local: It interacts with the local pivirtd daemon via Unix domain socket. It requires zero network connectivity, no Director, and no cluster consensus.
• pvcli is cluster-aware: It communicates with the Node Agent or the Director over ConnectRPC/gRPC with mTLS and OAuth2 authentication. See the pvcli Reference.

---

Global Syntax & Flags

pivirtctl [command] [flags]

Global Flags

Flag	Shorthand	Description	Default
--socket		Path to the pivirtd Unix domain socket	/var/run/pivirt/pivirtd.sock or $PIVIRTD_SOCKET
--output	-o	Output format: table, json, yaml, wide	table
--help	-h	Display help for command or subcommand

---

Part 1: Declarative Resource Management

PiVirt features a declarative resource engine that mirrors Kubernetes YAML workflows for virtualization infrastructure. All resources belong to the apiVersion: pivirt.hu/v1 group.

Dependency Graph & Cascade Ordering

When multiple resources are processed together, pivirtctl automatically resolves dependencies:

• Apply Order (Creation): StoragePool → Network / OverlayNetwork → ExternalIP → VirtualDisk → VirtualMachine → Snapshot.
• Delete Order (Teardown): Reverse dependency order (Snapshot → VirtualMachine → VirtualDisk → ExternalIP → Network → StoragePool), preventing orphaned mounts, lingering firewall rules, or hanging router namespaces.

---

pivirtctl apply

Applies one or more declarative resource manifests to the host hypervisor. If the resource does not exist, it is created. If it already exists and its specification has changed, it is updated and the host generation is incremented.

pivirtctl apply -f <path> [flags]

Flags

Flag	Shorthand	Description	Default
--filename	-f	Path to a YAML file, directory, or - for stdin	Required
--recursive	-R	Process directories recursively	false
--dry-run		Run decode, admission, validation, and interlocks without persisting	false

Examples

Single Manifest

# Apply a single VirtualMachine manifest
pivirtctl apply -f vm-web-01.yaml

Output:

virtualmachine/web-01 created

Directory (Recursive)

# Apply an entire directory of mixed manifests in dependency order
pivirtctl apply -f ./cluster-infra/ -R

Output:

storagepool/fast-nvme created
network/frontend-net created
virtualdisk/db-data unchanged
virtualmachine/db-01 updated
virtualmachine/web-01 created

Standard Input (Pipe)

# Pipe generated or templated YAML directly
cat <<EOF | pivirtctl apply -f -
apiVersion: pivirt.hu/v1
kind: StoragePool
metadata:
  name: backups
spec:
  type: dir
  path: /mnt/backups
EOF

Dry-Run Validation

# Validate manifests against admission and spec validators without applying
pivirtctl apply -f production-stack.yaml --dry-run

Output:

virtualmachine/prod-api (dry-run): valid (would be created)

---

pivirtctl get

Lists or retrieves declarative resources from the local host store.

pivirtctl get <kind> [name] [flags]
pivirtctl get <kind>/<name> [flags]

Supported Kind Names & Aliases

pivirtctl accepts singular names, plurals, short names, and multi-word names interchangeably:

Canonical Kind	Accepted Aliases & Plurals
VirtualMachine	vm, vms, virtualmachine, virtualmachines, virtual-machine, virtual-machines
StoragePool	pool, pools, storagepool, storagepools, storage-pool, storage-pools, storage
VirtualDisk	disk, disks, virtualdisk, virtualdisks, virtual-disk, virtual-disks
Network	net, nets, network, networks, bridge, bridges, hostbridge
NetworkSegment	segment, segments, networksegment, networksegments, network-segment
DHCPLease	lease, leases, dhcplease, dhcpleases, dhcp-lease
OverlayNetwork	overlay, overlays, overlaynetwork, overlaynetworks, overlay-network
ExternalIP	ippool, ippools, ip-pool, externalip, externalips, extip, ip, ips
Snapshot	snap, snaps, snapshot, snapshots

Flags

Flag	Shorthand	Description	Default
--selector	-l	Label selector query to filter resources
--output	-o	Output format: table, yaml, json, wide	table

Label Selector Syntax (-l)

The label selector supports full Kubernetes-compatible query syntax:

• Equality: environment=production, tier=frontend
• Inequality: environment!=staging
• Set Membership: tier in (frontend, api)
• Set Exclusion: environment notin (dev, test)
• Key Existence: backup-policy
• Key Non-Existence: !temporary
• Conjunction (AND): Comma-separated: environment=production,tier=frontend

Examples

List All of a Kind

# List all virtual machines
pivirtctl get vms

# List all storage pools (multi-word alias supported)
pivirtctl get storage pools

# List all networks
pivirtctl get networks

Output:

NAME       KIND              STATUS   AGE
web-01     VirtualMachine    Running  2h
db-01      VirtualMachine    Stopped  1d

Query Single Resource

# Query by kind and name
pivirtctl get vm web-01

# Query using kind/name syntax
pivirtctl get vm/web-01

# Output full manifest YAML
pivirtctl get vm/web-01 -o yaml

Filter by Labels

# Find all production frontend VMs
pivirtctl get vms -l "environment=production,tier=frontend"

# Find disks not in the dev environment
pivirtctl get disks -l "env notin (dev, test)"

---

pivirtctl describe

Displays detailed runtime inspection, specification fields, observed generation, metadata, and status for a specific resource.

pivirtctl describe <kind> <name>
pivirtctl describe <kind>/<name>

Example

pivirtctl describe vm web-01

Output:

Name:         web-01
Kind:         VirtualMachine
API Version:  pivirt.hu/v1
Generation:   2
Observed Gen: 2
UID:          8f3a9e21-bc14-41d3-a55b-4395b0c9a128
Labels:
  environment: production
  tier: frontend
  pivirt.hu/owner-org: acme-corp
  pivirt.hu/generation: 7
Spec:
  CPU:        2 Cores (host-passthrough)
  Memory:     4 GiB (4294967296 bytes)
  Disks:
    - Name:   root-disk (size: 20 GiB, format: qcow2, bus: virtio)
  Interfaces:
    - Name:   eth0 (bridge: virbr0, model: virtio)
Status:
  Phase:      Running
  PID:        41209
  QMP Socket: /var/lib/pivirt/vms/web-01/run/qmp.sock

---

pivirtctl delete

Deletes one or more declarative resources from the host. Deletions execute cascading teardowns (removing associated child resources like attached disks or local snapshots) and clean up host-level constructs (bridges, TAP devices, mounts, firewall chains).

pivirtctl delete <kind> <name>...
pivirtctl delete <kind>/<name>
pivirtctl delete -f <filename|directory> [-R]
pivirtctl delete <kind> -l <selector>
pivirtctl delete <kind> --all

Flags

Flag	Shorthand	Description	Default
--filename	-f	File or directory containing resources to delete
--recursive	-R	Process directory recursively with -f	false
--selector	-l	Selector (label query) to filter resources to delete
--all		Delete all resources of the specified kind	false

Examples

By Name

# Delete single resource
pivirtctl delete vm web-01

# Delete multiple resources at once
pivirtctl delete vm web-01 web-02 db-01

# Delete using kind/name syntax
pivirtctl delete vm/web-01

Output:

virtualmachine/web-01 deleted

By File (Reverse Ordering)

# Delete all resources defined in a stack file in reverse dependency order
pivirtctl delete -f stack.yaml

Output:

virtualmachine/app-server deleted
virtualdisk/app-data deleted
network/app-net deleted
storagepool/local-storage deleted

By Label Selector

# Delete all test VMs matching a selector
pivirtctl delete vms -l "environment=test"

---

Part 2: Resource Kinds Reference

Every declarative manifest adheres to the Kubernetes-style apiVersion: pivirt.hu/v1 envelope. To keep documentation organized and deep, each Kind has a dedicated reference sub-page with comprehensive field specifications, architectural notes, and copy-pasteable YAML examples:

Kind	Accepted Aliases	Key Capabilities	Specification Guide
VirtualMachine	vm, vms, virtualmachine	vCPU topology, RAM, disks, NICs, UEFI/TPM, cloud-init	VirtualMachine Reference →
StoragePool	pool, pools, storagepool	Local and networked storage mounts (dir, zfs, lvm, nfs)	StoragePool Reference →
VirtualDisk	disk, disks, virtualdisk	Standalone disks or dynamic VM attachments (qcow2, raw)	VirtualDisk Reference →
Network	net, nets, bridge	Linux bridges, isolated networks, NAT routing, VLAN trunks	Network Reference →
NetworkSegment	segment, segments	Host bridge binding and delegated host DHCP range	NetworkSegment Reference →
DHCPLease	lease, leases, dhcplease	Active host DHCP leases and declarative static IP reservations	DHCPLease Reference →
OverlayNetwork	overlay, overlays	Multi-host tunnel meshes using OVS VXLAN or Geneve	OverlayNetwork Reference →
ExternalIP	ippool, ippools, extip	Public IP bindings, 1:1 NAT, and port forwarding	ExternalIP Reference →
IPAllocation	ipam, allocation	Cluster IPAM pool management and port bindings	IPAllocation Reference →
Snapshot	snap, snaps, snapshot	Point-in-time VM disk and memory state checkpoints	Snapshot Reference →

VirtualMachine

Guest CPU, memory, disks, NICs, UEFI, TPM 2.0, and cloud-init.

View Specification →

DHCPLease & Reservations

Host-level dynamic leases and static IP reservations.

View Specification →

StoragePool

Filesystem pools, ZFS datasets, LVM volume groups, and NFS mounts.

View Specification →

VirtualDisk

Standalone disk volumes and live VM attachments.

View Specification →

Network & Overlay

Host bridges, NAT routers, VLAN trunks, and VXLAN meshes.

View Specification →

Cluster IPAM

Cluster-wide IPPools and VM network port IPAllocations.

View Specification →

Snapshot

Live QMP VM memory and disk state checkpoints.

View Specification →

---

Part 3: Imperative Host Operations

In addition to declarative YAML manifests, pivirtctl provides imperative commands for day-to-day diagnostics and power operations.

pivirtctl vm

Manages virtual machine power states, live consoles, and logs.

Power & Lifecycle Commands

# Start a virtual machine
pivirtctl vm start web-01

# Graceful shutdown (ACPI)
pivirtctl vm stop web-01

# Forceful power off
pivirtctl vm stop web-01 --force

# Reboot a virtual machine
pivirtctl vm restart web-01

# Pause and resume guest execution
pivirtctl vm pause web-01
pivirtctl vm resume web-01

# View QEMU console logs
pivirtctl vm logs web-01 --tail 50

Create via CLI Flags (Imperative)

pivirtctl vm create web-01 \
  --vcpus 4 \
  --memory 8192 \
  --disk size=40GB,format=qcow2 \
  --net type=bridge,br=virbr0

---

pivirtctl disk

Performs live disk operations on running or stopped virtual machines.

# List all disks attached to a VM
pivirtctl disk list web-01

# Live disk expansion (via QMP block_resize without restarting VM)
pivirtctl disk resize web-01 root-disk 50GB

# Inspect virtual disk image properties
pivirtctl disk info /var/lib/pivirt/vms/web-01/disks/disk0.qcow2

---

pivirtctl snapshot

Manages live snapshot trees and rollbacks.

# List snapshots for a VM
pivirtctl snapshot list web-01

# Create a snapshot with description
pivirtctl snapshot create web-01 snap-1 --description "Clean install"

# Revert VM to a previous snapshot
pivirtctl snapshot revert web-01 snap-1

# Delete a snapshot
pivirtctl snapshot delete web-01 snap-1

---

pivirtctl monitor & top

Streams live hardware metrics and resource consumption directly from hypervisor cgroups and QMP.

# Stream live hypervisor CPU, memory, and disk I/O metrics
pivirtctl top

# Stream detailed stats for a single VM
pivirtctl monitor web-01

---

Related Documentation

System Architecture

Learn how pivirtd decouples from the agent and director in the System Architecture.

pvcli Reference

Explore the multi-node, cluster-wide operator CLI in the pvcli Guide.

YAML Schema Guide

Inspect daemon configuration schemas in the YAML Reference.