pvcli — Command Line Interface

pvcli is the primary CLI tool for interacting with PiVirt clusters. It provides a unified interface for managing VMs, storage, networks, and clusters across multiple pivirtd instances.

Technical Specifications

Property	Value
Language	Go 1.22+
Protocol	gRPC/ConnectRPC (via agent)
Auth	mTLS (PiTrust PKI), OIDC
Config	~/.config/pvcli/config.yaml
Shell Completion	bash, zsh, fish, powershell

Key Features

Unified Cluster Management

• Multi-cluster support: Manage multiple PiVirt clusters from a single CLI
• Context switching: Seamlessly switch between dev, staging, production
• Namespace awareness: Built-in Kubernetes-style namespace support

Comprehensive Resource Coverage

• Virtual Machines: Full lifecycle (create, start, stop, migrate, snapshot, console)
• Storage: Pools, volumes, snapshots, iSCSI targets
• Networks: VXLAN, bridge, VLAN, SR-IOV
• Clusters: Node management, scaling, drain/cordon

Developer Experience

• Multiple output formats: table, wide, json, yaml, custom columns
• Watch mode: Real-time updates for long-running operations
• Shell completion: Full tab completion for all shells
• Scripting friendly: JSON/YAML output for automation

Architecture

flowchart TB
    subgraph Pvcli["pvcli Architecture"]
        subgraph Cmd["Command Layer"]
            CMD_LIST["vm | disk | network | image | storage | cluster"]
        end

        subgraph Client["API Client Layer"]
            CRPC["ConnectRPC"]
            GRPC["gRPC"]
            REST["REST (fallback)"]
        end

        subgraph Auth["Auth & Config Layer"]
            PITRUST["PiTrust mTLS"]
            OIDC["OIDC"]
            CTX["Config Contexts"]
        end

        Cmd --> Client
        Client --> Auth
    end

Configuration

pvcli uses a hierarchical configuration system with multiple sources:

~/.config/pvcli/config.yaml

current_context: "production"

contexts:
  - name: "development"
    endpoint: "localhost:9001"
    tls:
      insecure: true

  - name: "production"
    endpoint: "pivirtd-prod.pilab.hu:9001"
    tls:
      ca_file: "~/.config/pvcli/ca.crt"
      cert_file: "~/.config/pvcli/client.crt"
      key_file: "~/.config/pvcli/client.key"

output: "table"
namespace: "default"

aliases:
  vm: "virtual-machine"
  svc: "service"
  ns: "namespace"

Configuration Precedence

1. --config flag
2. $PVCLI_CONFIG environment variable
3. ~/.config/pvcli/config.yaml
4. /etc/pvcli/config.yaml

Authentication

Certificate-Based (mTLS)

# Generate client cert
pvcli cert generate --cn "admin@pilab.hu" --org "PiLab"

# Configure context with certificates
pvcli config set-context production \
  --ca-file /path/to/ca.crt \
  --cert-file /path/to/client.crt \
  --key-file /path/to/client.key

Token-Based (OIDC)

# Login via OIDC (opens browser)
pvcli auth login --oidc

# Or with device code (headless)
pvcli auth login --oidc --device-code

# Check token status
pvcli auth status

# Refresh token
pvcli auth refresh

Command Reference

For the complete command reference including all flags, subcommands, and examples, see the pvcli CLI Reference.

Quick Command Overview

Command Group	Description
pvcli auth	Authentication and session management
pvcli vm	Virtual machine lifecycle operations
pvcli disk	Storage disk management
pvcli network	Virtual network management
pvcli image	Cloud image management
pvcli config	Configuration context management
pvcli storage	Storage pools and volumes
pvcli cluster	Cluster and node management

Output Formats

# Table (default)
pvcli vm list

# Wide table (more columns)
pvcli vm list -o wide

# JSON
pvcli vm list -o json

# YAML
pvcli vm list -o yaml

# Custom columns
pvcli vm list -o custom=NAME,STATUS,IP,CPU,MEMORY

# Watch mode (real-time updates)
pvcli vm list -w

Shell Completion

# Bash
pvcli completion bash > /etc/bash_completion.d/pvcli

# Zsh
pvcli completion zsh > "${fpath[1]}/_pvcli"

# Fish
pvcli completion fish > ~/.config/fish/completions/pvcli.fish

# PowerShell
pvcli completion powershell > pvcli.ps1

Global Flags

pvcli [command] --help              # Help for command
pvcli --config string               # Config file path
pvcli --context string              # Override current context
pvcli --namespace string            # Override namespace
pvcli --output string               # Output format (table|json|yaml|wide|custom)
pvcli --kubeconfig string           # Kubernetes config (for cluster commands)
pvcli --insecure-skip-tls-verify    # Skip TLS verification
pvcli --v int                       # Log verbosity (0-10)

Related Documentation

CLI Reference

Complete command reference with all flags and examples.
View CLI Reference

VM Lifecycle Guide

Operational workflows for VM lifecycle, snapshots, and metrics.
View VM Guide

Storage Guide

Storage pools, volumes, and snapshots.
View Storage Guide

Networking Guide

VXLAN, bridge, VLAN, and SR-IOV configuration.
View Networking Guide

Authentication

PiTrust PKI, OIDC, and RBAC authentication setup.
View Authentication