KubeGuard CLI

Command-line interface for installing, inspecting, diagnosing, and operating KubeGuard AI.

---

Requirements

Tool	Minimum	Purpose
Python	3.9+	Runtime
kubectl	Any	Kubernetes cluster access
Helm	v3+	Chart installation
KubeGuard repo	—	Helm chart at helm/kubeguard/
kube-prometheus-stack	—	Prometheus + Alertmanager backing

---

Installation

Install from PyPI:

pip install kubeguard-cli

Verify:

kubeguard --help

Development install (from repository root):

cd cli
pip install -e ".[dev]"

---

Commands Summary

Command	Description
kubeguard version	Show CLI and application version
kubeguard install	Install KubeGuard into a Kubernetes cluster using Helm
kubeguard status	Show current KubeGuard installation status
kubeguard health	Report health of KubeGuard API and core dependencies
kubeguard diagnostics	Perform detailed diagnostic checks across all platform components
kubeguard pods	Display pod risk scores and feature telemetry
kubeguard alerts	Display active KubeGuard alerts from Alertmanager
kubeguard incidents	Inspect correlated incident contexts, timelines, and alert signals
kubeguard healing	Inspect auto-healing configuration, status, and execution history
kubeguard model	Inspect model registry, active version, history, and trigger rollback
kubeguard backup	Create, verify, and restore KubeGuard database and ML model backups
kubeguard fleet	Inspect multi-cluster fleet registry, cluster heartbeats, and aggregated incidents
kubeguard uninstall	Remove the KubeGuard Helm release

---

Global Options

These options apply to every command:

Option	Default	Description
--context TEXT	current-context	Kubernetes context (KUBEGUARD_CONTEXT)
--namespace TEXT, -n	kubeguard	KubeGuard namespace (KUBEGUARD_NAMESPACE)
--token TEXT	None	API authentication token (KUBEGUARD_API_TOKEN)

Example:

kubeguard --context kind-kubeguard status

---

Command Details & Usage Examples

1. Installation & Status

# Default install
kubeguard install

# Custom interval and namespaces
kubeguard install --interval 60 --namespaces demo,kubeguard-test

# Check status
kubeguard status
kubeguard status --json

2. Diagnostics & Health

# Basic health check
kubeguard health

# Full platform diagnostics
kubeguard diagnostics
kubeguard diagnostics --json

3. Pod Risk Scores & Telemetry

# View all monitored pods
kubeguard pods

# Filter by namespace or risk level
kubeguard pods --namespace demo --risk high
kubeguard pods --json

4. Active Alerts & Incidents

# View active alerts
kubeguard alerts

# View incident timeline and correlated signals
kubeguard incidents list
kubeguard incidents detail --incident-id INC-20261010-001

5. ML Model Registry Management

# View active ML model status (version, algorithm, checksum, persistence status)
kubeguard model status

# List model version history
kubeguard model list

# Rollback active model to a target version
kubeguard model rollback --target-version 55

6. Auto-Healing Controls

# View auto-healing status and safeguards
kubeguard healing status

# View auto-healing action history
kubeguard healing history

7. Backup & Disaster Recovery

# Create atomic database and ML model backup
kubeguard backup create --output-dir /data/backups

# Verify backup archive integrity
kubeguard backup verify --archive /data/backups/kubeguard-backup.zip

# Restore from backup archive
kubeguard backup restore --archive /data/backups/kubeguard-backup.zip --force

8. Multi-Cluster Fleet Management

# List registered clusters in fleet
kubeguard fleet list

# View fleet cluster status and heartbeats
kubeguard fleet status

9. Uninstall

# Uninstall KubeGuard Helm release
kubeguard uninstall --yes

---

Multi-Context Usage

kubeguard --context kind-kubeguard status
kubeguard --context kind-kubeguard pods
kubeguard --context kind-kubeguard alerts

The --context flag only affects the duration of the command. Your default context is never permanently changed.

---

API Access

The CLI does not require a public endpoint. All API access uses transient kubectl port-forward tunnels:

• kubeguard status / health → svc/kubeguard:8000 (/health)
• kubeguard pods → svc/kubeguard:8000 (/metrics)
• kubeguard model → svc/kubeguard:8000 (/model/active, /model/history)
• kubeguard incidents → svc/kubeguard:8000 (/incidents)
• kubeguard alerts → svc/kube-prometheus-stack-alertmanager:9093 (/api/v2/alerts)

Tunnels are opened automatically for the duration of the command and closed cleanly afterward.

---

License

MIT License — Copyright (c) KubeGuard AI Team.