Kcli

kcli User Guide

kcli is a unified CLI for managing virtual infrastructure across multiple providers (Libvirt/KVM, AWS, GCP, Azure, vSphere, KubeVirt, OpenStack, oVirt, Proxmox, Hetzner, IBM Cloud).

Remote Host Optimization

When the user asks to run a kcli command against a specific host that is not defined as a client in ~/.kcli/config.yml, run the command directly on that host via SSH instead of trying to use -C:

# Host not in config — run via SSH
ssh root@myhost "kcli create vm -i centos9stream myvm"
ssh root@myhost "kcli list vm"
ssh root@myhost "kcli create plan -f plan.yml myplan"

This is both faster (libvirt calls stay local on the host) and avoids needing to add a client entry.

Important Behavior

• Always run commands directly. When the user asks to create/deploy/manage something, execute the command immediately — don't show it and wait for confirmation.

Quick Reference

# VM Operations
kcli create vm -i <image> <name>      # Create VM
kcli list vm                          # List VMs
kcli ssh <name>                       # SSH into VM
kcli console <name>                   # Graphical console
kcli start/stop/restart vm <name>     # Control VM state
kcli delete vm <name>                 # Delete VM

# Plans (Infrastructure as Code)
kcli create plan -f plan.yml <name>   # Deploy plan
kcli list plan                        # List plans
kcli delete plan <name>               # Delete plan and resources

# Kubernetes Clusters
kcli create kube <type> <name>        # Deploy cluster
kcli list kube                        # List clusters
kcli delete kube <name>               # Delete cluster

# Images
kcli list available-images            # Show downloadable images
kcli download image <name>            # Download cloud image
kcli list image                       # List local images

# Infrastructure
kcli list network / pool / host       # List resources
kcli create network -c <cidr> <name>  # Create network
kcli create pool -p <path> <name>     # Create storage pool

Creating VMs

Basic VM Creation

# From cloud image (downloads if needed)
kcli create vm -i fedora40 myvm

# Create multiple VMs at once
kcli create vm -c 3 myvm             # Creates myvm-0, myvm-1, myvm-2

# Shorthand (kcli remembers last VM)
kcli ssh                              # SSH to last created VM

With Custom Resources

kcli create vm -i centos9stream \
  -P memory=4096 \
  -P numcpus=4 \
  -P disks=[20,50] \
  myvm

Common VM Parameters

Advanced VM Examples

# With static IP
kcli create vm -i centos9stream \
  -P nets=['{"name":"default","ip":"192.168.122.100"}'] \
  myvm

# With post-boot commands
kcli create vm -i fedora40 \
  -P cmds=['dnf -y install nginx','systemctl enable --now nginx'] \
  webserver

# From profile
kcli create vm -p myprofile myvm

# Multiple disks with options
kcli create vm -i ubuntu2204 \
  -P disks=['{"size":20}','{"size":100,"pool":"data"}'] \
  myvm

VM Management

# List VMs
kcli list vm                          # Table format
kcli list vm -o yaml                  # YAML output
kcli list vm -o json                  # JSON output

# VM Information
kcli info vm myvm                     # Full details
kcli info vm myvm -f ip               # Just IP address

# State Control
kcli start vm myvm
kcli stop vm myvm
kcli restart vm myvm

# Access
kcli ssh myvm                         # SSH as default user
kcli ssh -u root myvm                 # SSH as root
kcli console myvm                     # VNC/SPICE console
kcli console myvm --serial            # Serial console

# Modify
kcli update vm myvm -P memory=8192    # Change memory
kcli update vm myvm -P numcpus=8      # Change CPUs
kcli create disk -s 50 myvm           # Add 50GB disk

# Snapshots
kcli create snapshot myvm snap1
kcli list snapshot myvm
kcli revert snapshot myvm snap1
kcli delete snapshot myvm snap1

# Delete
kcli delete vm myvm                   # With confirmation
kcli delete vm myvm --yes             # Skip confirmation

Plans (Infrastructure as Code)

Plans are YAML files with Jinja2 templating for deploying complete environments.

Basic Plan Structure

# myplan.yml
parameters:
  base_image: centos9stream
  domain: lab.local

# Network (created first)
labnet:
  type: network
  cidr: 192.168.100.0/24
  dhcp: true

# VM (uses the network)
webserver:
  image: {{ base_image }}
  memory: 2048
  numcpus: 2
  nets:
    - labnet
  cmds:
    - dnf -y install nginx
    - systemctl enable --now nginx

Plan Commands

# Deploy
kcli create plan -f myplan.yml myplan

# Deploy with parameter overrides
kcli create plan -f myplan.yml -P base_image=fedora40 myplan

# List and manage
kcli list plan
kcli info plan myplan
kcli delete plan myplan               # Deletes all resources

# Update existing plan
kcli update plan -f myplan.yml myplan

Multi-VM Plan with Loop

parameters:
  cluster_name: web
  node_count: 3

{% for i in range(node_count) %}
{{ cluster_name }}-node-{{ i }}:
  image: centos9stream
  memory: 2048
  nets:
    - default
{% endfor %}

Resource Types in Plans

Kubernetes Clusters

Supported Types

• generic / kubeadm - Standard Kubernetes
• openshift / okd - OpenShift
• k3s - Lightweight K3s
• rke2 - Rancher RKE2
• microshift - Edge MicroShift
• hypershift - Hosted control planes
• aks / eks / gke - Cloud managed

Deploy Clusters

# Generic Kubernetes
kcli create kube generic -P ctlplanes=1 -P workers=2 myk8s

# K3s (lightweight)
kcli create kube k3s -P ctlplanes=1 -P workers=2 myk3s

# OpenShift (requires pull secret)
kcli create kube openshift \
  -P pull_secret=~/pull-secret.json \
  -P ctlplanes=3 \
  -P workers=2 \
  myocp

Cluster Management

# List clusters
kcli list kube

# Get kubeconfig
kcli get kubeconfig mycluster
export KUBECONFIG=~/.kcli/clusters/mycluster/kubeconfig

# Scale workers
kcli scale kube generic -P workers=5 mycluster

# Delete
kcli delete kube mycluster

Images

# List available cloud images
kcli list available-images

# Download image
kcli download image fedora40
kcli download image centos9stream
kcli download image ubuntu2204

# List downloaded images
kcli list image

# Delete image
kcli delete image fedora40

Common images: fedora40, centos9stream, ubuntu2204, rhel9, debian12, rocky9, almalinux9

Networks and Storage

Networks

# Create network
kcli create network -c 192.168.100.0/24 mynet
kcli create network -c 10.0.0.0/24 --dhcp --nat privatenet

# List and delete
kcli list network
kcli info network mynet
kcli delete network mynet

Storage Pools

# Create pool
kcli create pool -p /var/lib/libvirt/images default
kcli create pool -p /home/vms myvms

# List and delete
kcli list pool
kcli delete pool myvms

Provider/Client Management

# List configured clients
kcli list client

# Switch default client
kcli switch mykvm

# Use specific client for command
kcli -C aws list vm
kcli -C gcp create vm -i ubuntu2204 myvm

# List VMs from all clients
kcli -C all list vm

# Host information
kcli info host
kcli list host

Profiles

Profiles are reusable VM templates defined in ~/.kcli/profiles.yml:

# ~/.kcli/profiles.yml
small:
  numcpus: 1
  memory: 1024
  disks:
    - 10

webserver:
  image: centos9stream
  numcpus: 2
  memory: 4096
  cmds:
    - dnf -y install nginx
    - systemctl enable --now nginx

Usage:

kcli create vm -p webserver myweb

Debug and Troubleshooting

# Debug mode (verbose output)
kcli -d create vm -i fedora40 myvm
kcli -d list vm

# Check VM details
kcli info vm myvm

# Check cloud-init logs (after SSH)
kcli ssh myvm
cat /var/log/cloud-init.log

# Verify provider connectivity
kcli list host
kcli info host

Common Issues

No IP address: Check DHCP on network, wait for cloud-init

kcli info network default

SSH fails: Verify key injection worked

kcli ssh -l myvm                      # Show SSH command

Permission denied (libvirt): Add user to groups

sudo usermod -aG qemu,libvirt $(id -un)
newgrp libvirt

Configuration Files

~/.kcli/
├── config.yml      # Client/provider configuration
├── profiles.yml    # VM profiles
├── id_rsa          # SSH private key (auto-used)
└── clusters/       # Cluster state files

Minimal config.yml

default:
  client: local

local:
  type: kvm
  host: 127.0.0.1
  pool: default

Container Mode

Run kcli without installation:

# With libvirt socket
alias kcli='podman run --rm -it \
  -v ~/.kcli:/root/.kcli:z \
  -v /var/run/libvirt:/var/run/libvirt:z \
  quay.io/karmab/kcli'

# Then use normally
kcli list vm

Useful Tips

1. Last VM shortcut: Many commands work without VM name (uses last created)

   kcli ssh                            # SSH to last VM
   kcli console                        # Console of last VM
   

2. Output formats: Most list commands support -o yaml or -o json

3. Parameter files: Use kcli_parameters.yml alongside plans for defaults

4. Render plans: Preview templated plans before deploying

   kcli render -f myplan.yml
   

5. Export VMs: Create images from running VMs

   kcli export vm myvm