Metadata-Version: 2.4
Name: kubeguard-cli
Version: 0.1.8
Summary: KubeGuard AI — command-line interface for installation, inspection, and operation
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-mock>=3; extra == "dev"

# 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:

```bash
pip install kubeguard-cli
```

Verify:

```bash
kubeguard --help
```

Development install (from repository root):

```bash
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:

```bash
kubeguard --context kind-kubeguard status
```

---

## Command Details & Usage Examples

### 1. Installation & Status

```bash
# 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

```bash
# Basic health check
kubeguard health

# Full platform diagnostics
kubeguard diagnostics
kubeguard diagnostics --json
```

### 3. Pod Risk Scores & Telemetry

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# View auto-healing status and safeguards
kubeguard healing status

# View auto-healing action history
kubeguard healing history
```

### 7. Backup & Disaster Recovery

```bash
# 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

```bash
# List registered clusters in fleet
kubeguard fleet list

# View fleet cluster status and heartbeats
kubeguard fleet status
```

### 9. Uninstall

```bash
# Uninstall KubeGuard Helm release
kubeguard uninstall --yes
```

---

## Multi-Context Usage

```bash
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.
