# ilum

CLI tool for deploying and managing the [Ilum Data Lakehouse](https://ilum.cloud) platform on Kubernetes.

Manage Helm-based Ilum deployments with module dependency resolution, values safety, interactive wizards, health checks, and structured output — all from a single command.

## Install

```bash
pip install ilum
```

Requires Python 3.12+.

## Quick Start

```bash
# Interactive setup — walks you through cluster selection and module configuration
ilum init
ilum install

# Or one command — detects/creates a cluster and installs with defaults
ilum quickstart

# Check release status
ilum status

# Enable an optional module (resolves dependencies automatically)
ilum module enable sql
```

## Key Features

- **Install and upgrade** — `ilum install` / `ilum upgrade` with module resolution, stuck-release recovery, and breaking-change warnings
- **32 optional modules** — enable/disable with automatic dependency resolution (`ilum module enable langfuse` pulls in postgresql + clickhouse)
- **Values safety** — every upgrade detects external drift, computes a diff, and shows it for confirmation before applying
- **Health checks** — `ilum doctor` runs 13 checks covering binaries, cluster connectivity, pod health, RBAC, PVCs, and endpoints
- **Deployment presets** — `--preset production`, `--preset data-engineering`, `--preset air-gapped`
- **Local clusters** — `ilum cluster create` spins up k3d/minikube/kind with preset resource profiles
- **Log streaming** — `ilum logs core --follow` tails pod logs by module name
- **Resource monitoring** — `ilum top` shows per-module CPU/memory usage
- **Shell access** — `ilum exec core` opens an interactive shell in any module pod
- **Configuration profiles** — named profiles with cross-platform config (Linux, macOS, Windows)
- **Machine-readable output** — `--output json|yaml|csv` on all query commands for CI/CD pipelines
- **Shell completion** — `ilum --install-completion bash/zsh/fish`

## Commands

| Command | Description |
|---------|-------------|
| `ilum init` | Interactive setup wizard |
| `ilum quickstart` | One-command install with defaults |
| `ilum install` | Install the platform |
| `ilum upgrade` | Upgrade an existing installation |
| `ilum status` | Release info, pod readiness, modules |
| `ilum module enable/disable` | Manage modules with dependency resolution |
| `ilum module list` | List all 32 available modules |
| `ilum doctor` | Run health checks |
| `ilum logs <module>` | Stream pod logs |
| `ilum exec <module>` | Shell into a pod |
| `ilum top` | Resource usage per module |
| `ilum values` | View live Helm values |
| `ilum diff` | Compare values across sources |
| `ilum rollback` | Roll back to a previous revision |
| `ilum config` | Manage CLI configuration and profiles |
| `ilum connect` | Attach to an existing Ilum release |
| `ilum cleanup` | Tiered full-environment teardown |

## Prerequisites

`ilum` wraps Helm and kubectl — these must be available on your machine:

| Tool | Minimum Version |
|------|-----------------|
| Helm | 3.12+ |
| kubectl | 1.28+ |
| Docker | 24.0+ (for local clusters) |

Missing tools? `ilum deps install` will install them for you.

## Links

- [Documentation](https://github.com/ilum-cloud/ilum)
- [Ilum Platform](https://ilum.cloud)
- [Changelog](https://github.com/ilum-cloud/ilum/blob/master/CHANGELOG.md)
