umkim CLI

Experimental: install from the git repo; fleet operations use the hub API after platform install.

After greenfield hub install, operators use umkim for sites, ingress, clusters, storage, platform, VMs, and charts — not git inventory or flow playbooks for day-2 changes. Git retains install pins, vault, and examples.

Phase	Tool	Source of truth
Hub install	Ansible (`install-hub.sh`, `fleet-deploy.yml`)	Git `inventory/`
Fleet operations	`umkim` CLI / console	Hub CRDs (`FleetSite`, `FleetClusterJoin`, …)
Derived runtime	Controllers	Per-cluster Ansible inventory ConfigMaps, secrets, jobs

Site seed from inventory/group_vars/all/fleet_sites.yml remains a one-time install bootstrap; ongoing site changes go through umkim site create or the console.

Authentication

All mutations go through fleet-console-auth (same as the console):

Method	Use
`umkim login`	Interactive; session cookie in `~/.config/umkim/`
`UMKIM_TOKEN` / `--token`	`Bearer fleet_sa_…` service account (automation)
Hub-local lab	Direct fleet-site with `UMKIM_DEV=1` (lab only)

Public URL shape (via console nginx):

Fleet API: {base}/fleet/api/v1alpha1
Auth API: {base}/fleet/auth/v1alpha1

Configure with UMKIM_API_URL, UMKIM_AUTH_URL, or umkim config set.

Commands overview

umkim login | logout | whoami
umkim config show

umkim site list | get | create | patch
umkim site ingress list|add|set|delete SITE …
umkim site host list|get|provision|cluster-apply SITE …
umkim site provision get|set|run|status|actions|yaidap-sync SITE …
umkim site inventory get|files list|get|put|delete|migrate|revisions|sync|import preview|apply SITE …

umkim cluster list [--require gpu,kvm] | candidates [--require …] [--site SITE]
umkim cluster create|get|patch|bootstrap|provision|wait|delete NAME …
umkim cluster storage enable-local|status NAME …
umkim cluster platform enable-kubevirt|status NAME …

umkim vm list|get|start|stop|restart|console NAME --cluster CLUSTER …

umkim chart list|get|add|delete
umkim node list|add|remove|replace --cluster NAME
umkim node-op history|logs --cluster NAME

Sites and ingress

Site ingress entries are port_forward / reverse_proxy rows under FleetSite.spec.edge.ingress[]. Clusters bind with --ingress-id. hubGateway is a separate site toggle, not an ingress row.

umkim site ingress list SITE
umkim site ingress add SITE --id site-pf --method port_forward \
  --address 203.0.113.50 --zone site.example.com
umkim cluster patch CLUSTER --ingress-id site-pf

Site provisioner and inventory

Optional metal/VM provision before enroll. Setup checklist: YAIDAP operator guide. API reference: YAIDAP integration. Runbook: Site provisioning.

# Bind YAIDAP connector
umkim site provision set SITE --provider yaidap \
  --jumphost linux@jump.example:22 \
  --ssh-secret fleet-site-SITE-provision-ssh \
  --inventory /path/on/jumphost/to/inventory \
  --yaidap-root /path/on/jumphost/to/yaidap

# Inventory files and sync
umkim site inventory files list|get|put|delete SITE …
umkim site inventory migrate|sync|revisions SITE …
umkim site inventory import preview|apply SITE …

# YAIDAP checkout on jumphost (after yaidapRepo is set)
umkim site provision yaidap-sync SITE [--wait]

# Provision actions and cluster apply
umkim site provision run SITE --action create_vm --subject guest01 [--wait]
umkim site host provision SITE guest01 --wait
umkim site host cluster-apply SITE guest01

Destructive actions (install_bm, destroy, discover_pxe) require --confirm.

Clusters

cluster candidates --require filters Ready clusters by reported capabilities (gpu, kvm, ha_topology, storage.rwx, network.multus_l2, …). It does not schedule workloads — you still set FleetApp.spec.clusterName explicitly.

umkim cluster bootstrap NAME [--ssh-user linux] [--jumphost user@host:port]
umkim cluster provision NAME
umkim cluster wait NAME --phase Ready [--timeout 90m]   # HA: up to 90m
umkim cluster delete NAME [--cleanup-kubernetes]        # default: detach

cluster bootstrap resolves jumphost as cluster override, then site default.

Storage and KubeVirt platform

umkim cluster storage enable-local CLUSTER [--dir /path] [--wait 10m]
umkim cluster platform enable-kubevirt CLUSTER [--lan-bridge] [--wait 45m]
umkim cluster platform status CLUSTER

Storage configure and KubeVirt install are mutually exclusive with node lifecycle jobs. See cluster storage and Fleet KubeVirt platform.

Virtual machines

umkim vm list --cluster CLUSTER
umkim vm stop NAME --cluster CLUSTER [--force]
umkim vm start|restart NAME --cluster CLUSTER [--force]
umkim vm console NAME --cluster CLUSTER [--type serial|vnc]

Console UI: Clusters → Virtual machines. Serial is default; VNC opens on demand.

FleetApps and charts

umkim chart list | get | add | delete
umkim app list | get NAME | create [--cluster C --chart CHART …] [-f app.json]
umkim app update NAME [--version V] [--values-file F] [--route-mode …] [--llm-backend true|false]
umkim app create … --llama-profile qwen35-2b-ud-4g [--llm-backend true|false]
umkim app delete NAME

chart add mirrors console Apps → Library. See FleetApp.

LLM platform

umkim llm get | set [--hub-enabled] [--public-host H] [--backends-file F]
umkim llm backends sync-from-apps
umkim llm reconcile [--wait] [--timeout SEC]
umkim llm profile list|get|create|update|delete|values NAME
umkim llm profile verify NAME --cluster C [--extended] [--wait]
umkim llm profile test list|get|end|chat ID --message "…"

See fleet-llm and Fleet Llama profiles.

GPU clusters

umkim cluster gpu status NAME
umkim cluster gpu host-prep NAME [--force] [--wait 45m]
umkim cluster gpu enable NAME [--wait 30m]
umkim cluster gpu discover NAME

See GPU host prep.

Charts and node ops

umkim chart add --origin oci://… [--version V] [--image-policy external|proxy|copy]
umkim node add --cluster NAME --address IP [--hostname HN]
umkim node-op history --cluster NAME
umkim node-op logs --cluster NAME --id ID

Output formats

List commands default to a table. Use -o table (default), wide, or json.

Install

cd cmd/umkim && go build -o umkim .
export UMKIM_API_URL=https://<hub-host>/fleet/api/v1alpha1
export UMKIM_AUTH_URL=https://<hub-host>/fleet/auth/v1alpha1
umkim login

Roadmap (post v0.2)

umkim cluster up — create + bootstrap + provision + wait
umkim site export / cluster export — optional YAML backup
OCI-published binary in Harbor

Full command reference, flags, and examples live in the umkim repository docs/components/umkim-cli.md.