# Ilum CLI Reference

---

## 1. Global Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--output` | `-o` | `table` | Output format: `table`, `json`, `yaml`, `csv`. |
| `--quiet` | `-q` | `False` | Suppress informational output (errors still shown). |
| `--verbose` | `-v` | `False` | Enable verbose/debug output. |
| `--no-headers` | — | `False` | Omit column headers from table and CSV output. |
| `--field-selector` | — | `None` | Comma-separated list of fields to include in output (e.g. `name,status`). |
| `--version` | `-V` | — | Print version and exit. |

```bash
$ ilum --version
$ ilum -v install
$ ilum --output json status
$ ilum --quiet --output json module list
```

---

## 2. `ilum init`

Interactive setup wizard for the Ilum CLI.

### Synopsis

```
ilum init [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--yes` | `-y` | `False` | Non-interactive mode with defaults. |
| `--profile` | `-p` | `default` | Profile name to create. |

### Wizard Steps

| Step | Action |
|------|--------|
| 1. Preflight | Check for helm (>= 3.12), kubectl (>= 1.28), and docker (>= 24.0). In interactive mode, offers to install any missing or outdated tool automatically using platform-appropriate methods (see [Prerequisites](#20-prerequisites)). In non-interactive mode (`--yes`), raises an error if a tool is missing. |
| 2. Cluster | Detect kubecontexts or create a local cluster (k3d, minikube, kind). If creating a cluster, also checks for the cluster provider binary and offers to install it. |
| 3. Profile | Prompt for profile name, release name, namespace. |
| 4. Modules | Interactive checkbox grouped by category with dependency resolution. |
| 5. Confirm | Display summary table and ask for confirmation. |
| 6. Save | Write the profile to `config.yaml`. |

### Examples

```bash
# Interactive wizard
$ ilum init

# Non-interactive with defaults
$ ilum init --yes

# Create a named profile
$ ilum init --profile staging
```

---

## 3. `ilum quickstart`

Install Ilum in one command with sensible defaults.

### Synopsis

```
ilum quickstart [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--provider` | — | `minikube` | Local cluster provider if a new cluster is needed (`minikube`, `k3d`, `kind`). |
| `--profile` | `-p` | `default` | Profile name to create. |
| `--module` | `-m` | `None` | Additional module to enable (repeatable). |
| `--preset` | — | `None` | Deployment preset to apply (e.g. `minimal`, `full`, `analytics`). |
| `--timeout` | — | `15m` | Helm install timeout. |

### Steps Performed

| Step | Action |
|------|--------|
| 1. Preflight | Check for helm (>= 3.12), kubectl (>= 1.28), docker (>= 24.0). In interactive mode, offers to install missing tools automatically (see [Prerequisites](#20-prerequisites)). In non-interactive mode, raises an error if a tool is missing. |
| 2. Cluster | Probe current kubecontext. If unreachable, create a local cluster with the `dev` preset (4 CPUs, 8 GB). Also checks for the cluster provider binary and offers to install it. |
| 3. Profile | Create a profile with default modules plus any extras from `--module`. |
| 4. Install | Run `helm install` with `--atomic`, auto-resolve NodePort conflicts. |

### Cluster Auto-Detection

Quickstart probes the current kubeconfig context by listing namespaces. If the API server responds within 5 seconds, the existing cluster is used. Otherwise, a new local cluster is created using the provider specified by `--provider` (default: `minikube`).

### Examples

```bash
# Install with all defaults (detects cluster, default modules)
$ ilum quickstart

# Create a k3d cluster instead of minikube
$ ilum quickstart --provider k3d

# Enable additional modules beyond defaults
$ ilum quickstart -m sql -m airflow

# Use a named profile
$ ilum quickstart --profile staging

# Increase Helm install timeout
$ ilum quickstart --timeout 20m
```

---

## 4. `ilum install`

Install the Ilum platform via Helm.

### Synopsis

```
ilum install [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--version` | — | `""` (latest) | Chart version to install. |
| `--values` | `-f` | `None` | Values file (repeatable). |
| `--set` | — | `None` | Helm `--set` flag (repeatable). |
| `--module` | `-m` | `None` | Module to enable (repeatable). |
| `--preset` | — | `None` | Deployment preset to apply (e.g. `minimal`, `full`, `analytics`). |
| `--atomic` | — | `True` | Use `--atomic` for Helm install. |
| `--yes` | `-y` | `False` | Skip confirmation prompt. |
| `--dry-run` | — | `False` | Preview without executing. |
| `--timeout` | — | `10m` | Helm timeout. |

### Module Priority Rule

Modules are resolved in this order:

1. Modules passed via `--module` flags.
2. Modules saved in the active profile (`get_enabled_modules`).
3. Default-enabled modules from the module registry.

### NodePort Conflict Resolution

Before Helm install, the CLI checks for NodePort conflicts on the cluster. If a default NodePort (e.g. 31777 for ilum-ui) is already allocated, the user is prompted to select a free port. In `--yes` mode, a free port is auto-assigned.

### Examples

```bash
# Install with defaults
$ ilum install

# Install a specific version with modules
$ ilum install --version 6.7.0 --module jupyter --module sql

# Install into a custom namespace, non-interactive
$ ilum install -n ilum-prod -r ilum-prod --yes

# Dry-run preview
$ ilum install --dry-run

# Install with custom values file and overrides
$ ilum install -f custom-values.yaml --set ilum-core.replicaCount=3
```

---

## 5. `ilum upgrade`

Upgrade an existing Ilum installation.

### Synopsis

```
ilum upgrade [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--version` | — | `""` (latest) | Chart version to upgrade to. |
| `--values` | `-f` | `None` | Values file (repeatable). |
| `--set` | — | `None` | Helm `--set` flag (repeatable). |
| `--module` | `-m` | `None` | Module to enable (repeatable). |
| `--atomic` | — | `True` | Use `--atomic` for Helm upgrade. |
| `--force-rollback` | — | `False` | Rollback a stuck release before upgrading. |
| `--reset-defaults` | — | `False` | Reset to new chart defaults before applying user values. Use when upgrading across chart versions with breaking changes (uses Helm's `--reset-then-reuse-values`). |
| `--yes` | `-y` | `False` | Skip confirmation prompt. |
| `--dry-run` | — | `False` | Preview without executing. |
| `--timeout` | — | `10m` | Helm timeout. |

### Values Safety Pipeline

1. **Stuck release detection** -- if the release is in `pending-install`, `pending-upgrade`, or `pending-rollback` state, the CLI blocks unless `--force-rollback` is passed.
2. **Drift detection** -- external changes made since the last CLI operation are displayed as a diff table and preserved during upgrade.
3. **Breaking change warnings** -- version transitions are checked for known breaking changes.
4. **No-op detection** -- if the target version matches the current version and there are no value changes or new modules, the CLI exits early with a success message.

### Examples

```bash
# Upgrade to latest
$ ilum upgrade

# Upgrade to a specific version
$ ilum upgrade --version 6.8.0

# Recover a stuck release and upgrade
$ ilum upgrade --force-rollback

# Upgrade with additional modules
$ ilum upgrade --module airflow --module superset

# Dry-run preview
$ ilum upgrade --dry-run
```

---

## 6. `ilum uninstall`

Uninstall the Ilum platform.

### Synopsis

```
ilum uninstall [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--yes` | `-y` | `False` | Skip confirmation prompt. |
| `--dry-run` | — | `False` | Preview without executing. |
| `--delete-data` | — | `False` | Delete PersistentVolumeClaims after uninstall. |
| `--delete-namespace` | — | `False` | Delete the namespace after uninstall. |

### Idempotent Behavior

If the release does not exist, `ilum uninstall` exits with code 0 and prints an informational message. It does not fail.

### Destructive Flag Confirmation

When `--delete-data` or `--delete-namespace` is passed (without `--yes`), the user must type the release name to confirm.

### Examples

```bash
# Standard uninstall
$ ilum uninstall

# Uninstall and delete all data
$ ilum uninstall --delete-data

# Uninstall, delete data, and delete namespace
$ ilum uninstall --delete-data --delete-namespace --yes

# Dry-run preview
$ ilum uninstall --dry-run
```

---

## 6b. `ilum cleanup`

Full environment teardown with tiered, opt-in destructiveness. Combines uninstall, cluster deletion, config removal, dependency removal, and CLI self-uninstall into a single command.

### Synopsis

```
ilum cleanup [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--cluster` | — | `False` | Also delete CLI-managed local k8s cluster. |
| `--config` | — | `False` | Also remove CLI config/state/cache directories. |
| `--deps` | — | `False` | Also remove dependencies (helm, kubectl, minikube, k3d, kind, docker). |
| `--self` | — | `False` | Also uninstall the CLI itself (always last, never included in `--all`). |
| `--all` | — | `False` | Shorthand for `--cluster --config --deps`. |
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--yes` | `-y` | `False` | Skip all confirmations. |
| `--dry-run` | — | `False` | Preview without executing. |

### Tiers

The command executes in order:

1. **Tier 1** (always): Uninstall Helm release + delete PVCs + delete namespace. Requires typing release name to confirm.
2. **Tier 2** (`--cluster`): Delete CLI-managed local cluster. Requires typing cluster name.
3. **Tier 3** (`--config`): Remove CLI directories and Helm repo. Requires typing `DELETE`.
4. **Tier 4** (`--deps`): Remove dependencies. Requires typing `REMOVE` per tool (or `REMOVE DOCKER` for Docker).
5. **Tier 5** (`--self`): Uninstall the CLI itself. Requires typing `UNINSTALL`.

Each tier is independent -- if one fails, the next still runs.

### Examples

```bash
# Preview what would be removed
$ ilum cleanup --all --dry-run

# Uninstall release only (Tier 1)
$ ilum cleanup --yes

# Full teardown: release + cluster + config + dependencies
$ ilum cleanup --all --yes

# Full teardown including CLI itself
$ ilum cleanup --all --self --yes

# Just release + cluster, skip deps
$ ilum cleanup --cluster --yes
```

---

## 7. `ilum connect`

Connect the CLI to an existing Ilum installation.

### Synopsis

```
ilum connect [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | `None` | Helm release name (skips auto-detection). |
| `--namespace` | `-n` | `None` | Kubernetes namespace (scans all if omitted). |
| `--context` | — | `None` | Kubernetes context. |
| `--profile` | `-p` | `default` | Profile name to create or update. |
| `--yes` | `-y` | `False` | Skip confirmation prompts. |
| `--no-switch` | — | `False` | Don't switch active profile after connecting. |

### Auto-detect vs Direct Mode

| Condition | Mode | Behavior |
|-----------|------|----------|
| `--release` and `--namespace` both set | Direct | Validate the specific release in the given namespace. |
| `--release` set, `--namespace` omitted | Scan | Scan all namespaces for the named release. |
| Neither set | Scan | Scan all namespaces for any Ilum releases. |

When multiple releases are found in scan mode, a table is displayed and the user selects one. In `--yes` mode, the first release is auto-selected.

### Post-connect Actions

- Enabled modules are detected from live Helm values and synced to the profile.
- A values snapshot is saved for drift detection.
- Stuck releases produce a warning with recovery instructions.

### Examples

```bash
# Auto-detect
$ ilum connect

# Direct mode
$ ilum connect --release ilum --namespace production

# Connect to a named profile
$ ilum connect --profile staging

# Non-interactive
$ ilum connect --yes
```

---

## 8. `ilum status`

Show the status of an Ilum installation.

### Synopsis

```
ilum status [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--pods/--no-pods` | — | `True` | Show pod readiness. |
| `--modules/--no-modules` | — | `True` | Show enabled modules. |
| `--wait` | `-w` | `False` | Block until all pods are ready. |
| `--wait-timeout` | — | `300` | Seconds to wait when `--wait` is used (0 = unlimited). |
| `--events` | — | `False` | Include recent Kubernetes events in output. |
| `--events-type` | — | `None` | Filter events by type: `Normal`, `Warning`. |
| `--events-since` | — | `5m` | Show events newer than this duration (e.g. `10m`, `1h`). |

### Examples

```bash
# Full status
$ ilum status

# Status without pod details
$ ilum status --no-pods

# Status for a specific release
$ ilum status -r my-ilum -n staging

# Wait for all pods to become ready (up to 5 minutes)
$ ilum status --wait

# Wait with a custom timeout
$ ilum status --wait --wait-timeout 600

# Include recent warning events
$ ilum status --events --events-type Warning

# Show events from the last hour
$ ilum status --events --events-since 1h
```

---

## 8b. `ilum values`

View or export live Helm values for the current release.

### Synopsis

```
ilum values [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--path` | — | `None` | Dot-notation path to a specific key (e.g. `ilum-core.replicaCount`). |
| `--all` | `-a` | `False` | Show all computed values (chart defaults + overrides), not just user-supplied. |
| `--diff` | — | `False` | Show a diff between user-supplied values and chart defaults. |
| `--revision` | — | `None` | Show values from a specific Helm revision number. |
| `--export` | — | `None` | Export values to a file path instead of printing to stdout. |

### Examples

```bash
# Show user-supplied values
$ ilum values

# Show a specific key
$ ilum values --path ilum-core.replicaCount

# Show all computed values
$ ilum values --all

# Show values from a previous revision
$ ilum values --revision 3

# Diff user values against chart defaults
$ ilum values --diff

# Export values to a file
$ ilum values --export my-values.yaml

# Combine path filter with JSON output
$ ilum values --path mongodb --output json
```

---

## 8c. `ilum diff`

Compare Helm values across different sources.

### Synopsis

```
ilum diff [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--source` | `-s` | `defaults` | Source to compare live values against: `defaults`, `file`, `revision`, `snapshot`. |
| `--values-file` | `-f` | `None` | Values file to compare against (required when `--source file`). |
| `--revision` | — | `None` | Helm revision number to compare against (required when `--source revision`). |
| `--path` | — | `None` | Dot-notation path to limit comparison scope (e.g. `ilum-core`). |

### Source Modes

| Source | Description |
|--------|-------------|
| `defaults` | Compare live values against chart default values. |
| `file` | Compare live values against a local values file. |
| `revision` | Compare live values against a previous Helm revision. |
| `snapshot` | Compare live values against the last CLI snapshot (drift detection). |

### Examples

```bash
# Diff live values against chart defaults
$ ilum diff

# Diff against a local values file
$ ilum diff --source file --values-file custom-values.yaml

# Diff against a specific revision
$ ilum diff --source revision --revision 2

# Diff against the last CLI snapshot (detect drift)
$ ilum diff --source snapshot

# Limit diff to a specific path
$ ilum diff --path ilum-core
```

---

## 8d. `ilum rollback`

Roll back the Ilum release to a previous Helm revision.

### Synopsis

```
ilum rollback [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--revision` | — | `None` | Target revision number (defaults to previous revision if omitted). |
| `--dry-run` | — | `False` | Preview the rollback without executing. |
| `--yes` | `-y` | `False` | Skip confirmation prompt. |
| `--timeout` | — | `10m` | Helm timeout. |

### Examples

```bash
# Rollback to the previous revision
$ ilum rollback

# Rollback to a specific revision
$ ilum rollback --revision 3

# Dry-run preview
$ ilum rollback --dry-run

# Non-interactive rollback
$ ilum rollback --revision 5 --yes

# Rollback with a longer timeout
$ ilum rollback --timeout 15m
```

---

## 8e. `ilum exec`

Open an interactive shell session inside a module's pod.

### Synopsis

```
ilum exec MODULE [OPTIONS]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `MODULE` | Yes | Module name (e.g. `core`, `jupyter`, `sql`). |

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--shell` | — | `/bin/sh` | Shell binary to use (e.g. `/bin/bash`). |
| `--container` | `-c` | `None` | Container name (auto-detected if omitted). |
| `--pod` | — | `None` | Specific pod name (auto-detected if omitted). |
| `--command` | — | `None` | Run a single command instead of opening an interactive shell. |

### Examples

```bash
# Open a shell in the core pod
$ ilum exec core

# Use bash instead of sh
$ ilum exec core --shell /bin/bash

# Exec into a specific container
$ ilum exec jupyter --container ilum-jupyter

# Run a single command
$ ilum exec core --command "cat /opt/ilum/conf/application.conf"

# Exec into a specific pod
$ ilum exec core --pod ilum-core-0
```

---

## 8f. `ilum top`

Show resource usage (CPU and memory) for module pods.

### Synopsis

```
ilum top [MODULE] [OPTIONS]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `MODULE` | No | Module name to filter (shows all modules if omitted). |

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--sort-by` | — | `cpu` | Sort column: `cpu`, `memory`, `name`. |
| `--watch` | `-w` | `False` | Continuously refresh the display. |
| `--interval` | — | `5` | Refresh interval in seconds when `--watch` is used. |

### Examples

```bash
# Show resource usage for all modules
$ ilum top

# Show resource usage for a specific module
$ ilum top core

# Sort by memory usage
$ ilum top --sort-by memory

# Watch mode with 10-second refresh
$ ilum top --watch --interval 10

# JSON output for scripting
$ ilum top --output json
```

---

## 9. `ilum logs`

Show logs for an Ilum module's pod.

### Synopsis

```
ilum logs MODULE [OPTIONS]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `MODULE` | Yes | Module name (e.g. `core`, `jupyter`, `sql`). |

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--follow` | `-f` | `False` | Stream logs in real time. |
| `--tail` | — | `100` | Number of lines to show (0 for all). |
| `--container` | `-c` | `None` | Container name (auto-detected if omitted). |
| `--previous` | `-p` | `False` | Show logs from previously terminated container. |
| `--max-duration` | — | `0` | Stop `--follow` after N seconds (0 = unlimited). |

### Piping Note

Output is written to stdout via `typer.echo`, so logs can be piped to other tools:

```bash
$ ilum logs core --tail 0 | grep ERROR
$ ilum logs core -f | tee /tmp/core.log
```

### Examples

```bash
# Last 100 lines from core
$ ilum logs core

# Stream jupyter logs
$ ilum logs jupyter --follow

# All logs from a specific container
$ ilum logs core --tail 0 --container ilum-core

# Previous container logs (after restart)
$ ilum logs core --previous
```

---

## 10. `ilum doctor`

Run health checks on the Ilum installation.

### Synopsis

```
ilum doctor [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--release` | `-r` | from profile | Helm release name. |
| `--check` | `-c` | `None` | Run a single check by name. |
| `--failures-only` | — | `False` | Only show failed and warning checks. |
| `--fix` | — | `False` | Auto-fix simple issues (e.g., add missing Helm repo). |

### Checks Table

| Check Name | Phase | What it verifies |
|------------|-------|------------------|
| `helm` | 1 - Binaries | Helm is installed and version >= 3.12 |
| `kubectl` | 1 - Binaries | kubectl is installed and version >= 1.28 |
| `docker` | 1 - Binaries | Docker is installed and version >= 24.0 |
| `helm-repo` | 2 - Helm repo | The `ilum` Helm repo is configured (charts.ilum.cloud) |
| `cluster` | 3 - Connectivity | Kubernetes cluster is reachable |
| `namespace` | 4 - Cluster-dependent | Target namespace exists |
| `pods` | 4 - Cluster-dependent | All pods are healthy (detects CrashLoopBackOff) |
| `pvcs` | 4 - Cluster-dependent | All PVCs are bound (detects Pending PVCs) |
| `rbac` | 4 - Cluster-dependent | Required RBAC permissions are granted |
| `release` | 4 - Cluster-dependent | Helm release exists and is not stuck or failed |
| `compatibility` | 4 - Cluster-dependent | Kubernetes version >= 1.28 |
| `service-endpoints` | 4 - Cluster-dependent | Service endpoints have ready addresses |
| `health-endpoints` | 4 - Cluster-dependent | Health check endpoints respond for core, airflow, superset, minio |

### Phase Gating

If the `cluster` check fails (phase 3), all phase-4 checks are skipped with status `SKIP`.

### Examples

```bash
# Run all checks
$ ilum doctor

# Run a single check
$ ilum doctor --check pods

# Check against a specific release
$ ilum doctor -r my-ilum -n staging
```

---

## 11. `ilum module`

Manage Ilum platform modules.

### 11.1 `ilum module list`

List all available Ilum modules.

#### Synopsis

```
ilum module list [OPTIONS]
```

#### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--category` | `-c` | `None` | Filter by category. |
| `--enabled/--disabled` | — | `None` | Filter by default-enabled status. |
| `--search` | `-s` | `None` | Search modules by name or description. |

#### Examples

```bash
# List all modules
$ ilum module list

# List only notebook modules
$ ilum module list --category notebook

# List only default-enabled modules
$ ilum module list --enabled

# Search for modules matching a term
$ ilum module list --search kafka
```

### 11.2 `ilum module show`

Show detailed information about a module.

#### Synopsis

```
ilum module show NAME
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `NAME` | Yes | Module name to inspect. |

#### Examples

```bash
$ ilum module show sql
$ ilum module show hive-metastore
```

### 11.3 `ilum module tree`

Show the dependency tree for a module with resource estimates.

#### Synopsis

```
ilum module tree NAME
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `NAME` | Yes | Module name to display tree for. |

#### Examples

```bash
$ ilum module tree sql
$ ilum module tree langfuse
```

### 11.4 `ilum module enable`

Enable one or more modules on a running Ilum release.

#### Synopsis

```
ilum module enable MODULES... [OPTIONS]
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `MODULES` | Yes | Modules to enable (one or more). |

#### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--set` | — | `None` | Additional Helm `--set` flag (repeatable). |
| `--reset-defaults` | — | `False` | Reset to new chart defaults before applying user values. Use when upgrading across chart versions with breaking changes. |
| `--yes` | `-y` | `False` | Skip confirmation prompt. |
| `--dry-run` | — | `False` | Preview without executing. |
| `--timeout` | — | `10m` | Helm timeout. |

#### Examples

```bash
# Enable a single module
$ ilum module enable jupyter

# Enable multiple modules
$ ilum module enable airflow superset

# Enable with additional Helm overrides
$ ilum module enable sql --set ilum-sql.replicaCount=2

# Dry-run preview
$ ilum module enable trino --dry-run
```

### 11.5 `ilum module disable`

Disable one or more modules on a running Ilum release.

#### Synopsis

```
ilum module disable MODULES... [OPTIONS]
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `MODULES` | Yes | Modules to disable (one or more). |

#### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--set` | — | `None` | Additional Helm `--set` flag (repeatable). |
| `--reset-defaults` | — | `False` | Reset to new chart defaults before applying user values. Use when upgrading across chart versions with breaking changes. |
| `--yes` | `-y` | `False` | Skip confirmation prompt. |
| `--dry-run` | — | `False` | Preview without executing. |
| `--timeout` | — | `10m` | Helm timeout. |

#### Examples

```bash
# Disable a module
$ ilum module disable zeppelin

# Disable multiple modules
$ ilum module disable airflow superset

# Dry-run preview
$ ilum module disable kafka --dry-run
```

### 11.6 `ilum module status`

Show live module status on a running Ilum release.

#### Synopsis

```
ilum module status [OPTIONS]
```

#### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--release` | `-r` | from profile | Helm release name. |
| `--namespace` | `-n` | from profile | Kubernetes namespace. |
| `--context` | — | from profile | Kubernetes context. |
| `--category` | `-c` | `None` | Filter by module category. |
| `--timeout` | — | `10m` | Helm timeout. |

#### Examples

```bash
# Show all module statuses
$ ilum module status

# Filter by category
$ ilum module status --category orchestration
```

---

## 12. `ilum config`

Manage Ilum CLI configuration.

### 12.1 `ilum config show`

Show the current configuration (or a specific key).

#### Synopsis

```
ilum config show [KEY]
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `KEY` | No | Dot-notation key to display (e.g. `active_profile`). |

#### Examples

```bash
# Show full config
$ ilum config show

# Show a specific key
$ ilum config show active_profile
```

### 12.2 `ilum config set`

Set a configuration value.

#### Synopsis

```
ilum config set KEY VALUE
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `KEY` | Yes | Dot-notation key (e.g. `active_profile`). |
| `VALUE` | Yes | Value to set. |

#### Examples

```bash
$ ilum config set active_profile staging
```

### 12.3 `ilum config path`

Print the configuration file path.

#### Synopsis

```
ilum config path
```

#### Examples

```bash
# Linux / macOS
$ ilum config path
/home/user/.config/ilum/config.yaml

# Windows
PS> ilum config path
C:\Users\user\AppData\Roaming\ilum\config.yaml
```

### 12.4 `ilum config init`

Create a default configuration file.

#### Synopsis

```
ilum config init [OPTIONS]
```

#### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--force` | `-f` | `False` | Overwrite existing config. |

#### Examples

```bash
# Create config if it doesn't exist
$ ilum config init

# Overwrite existing config
$ ilum config init --force
```

### 12.5 `ilum config edit`

Open the configuration file in `$EDITOR` (falls back to `vi` on Linux/macOS, `notepad` on Windows).

#### Synopsis

```
ilum config edit
```

#### Examples

```bash
$ EDITOR=nano ilum config edit
```

### 12.6 `ilum config use`

Switch the active profile.

#### Synopsis

```
ilum config use PROFILE
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `PROFILE` | Yes | Profile name to switch to. |

#### Examples

```bash
$ ilum config use staging
$ ilum config use production
```

### 12.7 `ilum config list-profiles`

List all configured profiles.

#### Synopsis

```
ilum config list-profiles
```

#### Examples

```bash
$ ilum config list-profiles
```

### 12.8 `ilum config validate`

Validate the configuration file for correctness.

#### Synopsis

```
ilum config validate
```

#### Examples

```bash
$ ilum config validate
```

### 12.9 `ilum config backup`

Create a backup copy of the configuration file.

#### Synopsis

```
ilum config backup
```

#### Examples

```bash
$ ilum config backup
```

### 12.10 `ilum config export`

Export a profile for team sharing.

#### Synopsis

```
ilum config export PROFILE [OPTIONS]
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `PROFILE` | Yes | Profile name to export. |

#### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--out` | `-o` | `<profile>.yaml` | Output file path. |

#### Examples

```bash
# Export to default filename
$ ilum config export production

# Export to a specific file
$ ilum config export production --out prod-profile.yaml
```

### 12.11 `ilum config import`

Import a profile from a file.

#### Synopsis

```
ilum config import FILE [OPTIONS]
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `FILE` | Yes | Path to the profile file to import. |

#### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--name` | `-n` | from file | Profile name to use. |

#### Examples

```bash
# Import with the name from the file
$ ilum config import prod-profile.yaml

# Import with a custom name
$ ilum config import prod-profile.yaml --name production
```

---

## 13. `ilum cluster`

Manage local Kubernetes clusters.

### 13.1 `ilum cluster create`

Create a local Kubernetes cluster.

#### Synopsis

```
ilum cluster create [OPTIONS]
```

#### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--provider` | — | `k3d` | Cluster provider: `minikube`, `k3d`, `kind`. |
| `--preset` | — | `dev` | Resource preset: `dev`, `full`. |
| `--name` | — | `""` (from preset) | Cluster name. |

#### Presets Table

| Preset | CPUs | Memory | Default Name |
|--------|------|--------|--------------|
| `dev` | 6 | 12g | `ilum-dev` |
| `full` | 8 | 18g | `ilum` |

#### Examples

```bash
# Create with defaults (k3d, dev preset)
$ ilum cluster create

# Create a minikube cluster with full resources
$ ilum cluster create --provider minikube --preset full

# Create with a custom name
$ ilum cluster create --name my-ilum-cluster
```

### 13.2 `ilum cluster delete`

Delete a local Kubernetes cluster.

#### Synopsis

```
ilum cluster delete NAME
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `NAME` | Yes | Cluster name to delete. |

#### Examples

```bash
$ ilum cluster delete ilum-dev
```

### 13.3 `ilum cluster list`

List tracked local Kubernetes clusters.

#### Synopsis

```
ilum cluster list
```

#### Examples

```bash
$ ilum cluster list
```

---

## 14. `ilum preset list`

List all available deployment presets.

### Synopsis

```
ilum preset list
```

### Description

Lists all available deployment presets with their names, descriptions, and module counts. Presets are curated collections of modules designed for common deployment scenarios. The output is a Rich table with three columns: Name, Description, and Modules.

### Output Columns

| Column | Description |
|--------|-------------|
| Name | Preset identifier used with `--preset` flags. |
| Description | Short summary of the preset's purpose. |
| Modules | Number of modules included in the preset. |

### Examples

```bash
# List all presets
$ ilum preset list
```

---

## 15. `ilum airgap images`

List container images required by selected modules.

### Synopsis

```
ilum airgap images [OPTIONS]
```

### Description

Lists all container images required by the selected modules. Image references are extracted by running `helm template` against the chart and parsing the rendered manifests for container image fields. This is useful for pre-pulling images or preparing air-gapped environments.

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--preset` | — | `None` | Deployment preset to select modules from. |
| `--module` | `-m` | `None` | Module to include (repeatable). |
| `--version` | — | `""` (latest) | Chart version to template. |
| `--format` | — | `table` | Output format: `table` or `plain`. |

### Examples

```bash
# List images for default modules
$ ilum airgap images

# List images for a preset
$ ilum airgap images --preset full

# List images for specific modules
$ ilum airgap images -m core -m jupyter -m mongodb

# Plain output for scripting
$ ilum airgap images --preset minimal --format plain

# List images for a specific chart version
$ ilum airgap images --version 6.7.0
```

---

## 16. `ilum airgap export`

Export images and chart into a portable air-gapped bundle.

### Synopsis

```
ilum airgap export OUTPUT_DIR [OPTIONS]
```

### Description

Exports the Helm chart and all required container images into a portable bundle directory. The bundle includes a `manifest.json` file describing the contents, chart version, and image list. This bundle can be transferred to an air-gapped environment and imported with `ilum airgap import`.

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `OUTPUT_DIR` | Yes | Directory to write the bundle to. Created if it does not exist. |

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--preset` | — | `None` | Deployment preset to select modules from. |
| `--module` | `-m` | `None` | Module to include (repeatable). |
| `--version` | — | `""` (latest) | Chart version to export. |

### Examples

```bash
# Export default modules
$ ilum airgap export ./bundle

# Export a specific preset
$ ilum airgap export ./bundle --preset analytics

# Export specific modules and version
$ ilum airgap export ./bundle -m core -m jupyter --version 6.7.0
```

---

## 17. `ilum airgap import`

Import an air-gapped bundle into a private container registry.

### Synopsis

```
ilum airgap import BUNDLE_DIR --registry URL
```

### Description

Imports a previously exported air-gapped bundle into a private container registry. Reads the `manifest.json` from the bundle directory, loads the container images, re-tags them for the target registry, and pushes them. The Helm chart is also made available for installation from the bundle.

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `BUNDLE_DIR` | Yes | Path to the bundle directory created by `ilum airgap export`. |

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--registry` | — | **required** | Target container registry URL (e.g. `registry.internal:5000`). |

### Examples

```bash
# Import bundle into a private registry
$ ilum airgap import ./bundle --registry registry.internal:5000

# Import from an absolute path
$ ilum airgap import /mnt/usb/ilum-bundle --registry harbor.corp.local/ilum
```

---

## 18. `ilum history`

View the operation audit log.

### Synopsis

```
ilum history [OPTIONS]
```

### Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--last` | `-n` | `20` | Number of recent operations to show. |
| `--operation` | — | `None` | Filter by operation type (`install`, `upgrade`, `enable`, `disable`, `uninstall`). |
| `--release` | `-r` | from profile | Filter by Helm release name. |

### Examples

```bash
# Show recent operations
$ ilum history

# Show last 5 operations
$ ilum history --last 5

# Filter by operation type
$ ilum history --operation upgrade

# JSON output for CI/CD
$ ilum history --last 10 --output json
```

---

## 19. `ilum deps`

Manage CLI dependencies (helm, kubectl, docker, k3d, etc.).

### `ilum deps install`

Install missing CLI dependencies.

#### Synopsis

```
ilum deps install [TOOL...] [OPTIONS]
```

#### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `TOOL` | No | One or more tool names to install. If omitted, installs all core tools (helm, kubectl, docker) plus the selected provider. |

#### Options

| Flag | Default | Description |
|------|---------|-------------|
| `--provider` | `k3d` | Cluster provider to install: `k3d`, `minikube`, `kind`. |
| `--dry-run` | `False` | Preview what would be installed without executing. |

#### Examples

```bash
# Install all missing core tools + default provider (k3d)
$ ilum deps install

# Install only specific tools
$ ilum deps install helm kubectl

# Install with a different provider
$ ilum deps install --provider kind

# Preview without executing
$ ilum deps install --dry-run
```

### `ilum deps list`

List CLI dependencies and their status.

#### Synopsis

```
ilum deps list
```

#### Examples

```bash
$ ilum deps list
```

---

## 20. Prerequisites

The CLI requires the following tools to be installed on your system. These are checked during the preflight step of `ilum init`, `ilum quickstart`, and before operations like `ilum install` and `ilum upgrade`.

### Required Tools

| Tool | Minimum Version | Purpose |
|------|----------------|---------|
| `helm` | >= 3.12 | Deploys and manages the Ilum Helm chart |
| `kubectl` | >= 1.28 | Communicates with the Kubernetes cluster |
| `docker` | >= 24.0 | Container runtime for local clusters and image operations |

### Cluster Providers (optional)

One of these is required only if creating a local cluster via `ilum cluster create`:

| Provider | Description |
|----------|-------------|
| `k3d` | Lightweight k3s clusters in Docker containers (default provider) |
| `minikube` | Full Kubernetes in a VM or container |
| `kind` | Kubernetes-in-Docker for testing |

### Automatic Installation

When running in an **interactive terminal** (TTY connected to stdin), the CLI offers to install missing or outdated tools automatically. This applies to:

- `ilum init` (wizard preflight step)
- `ilum quickstart` (preflight step)
- `ilum cluster create` (cluster provider check)
- Any command that calls `ensure_tool()` internally

The install methods are platform-specific:

| Platform | Method | Example |
|----------|--------|---------|
| **Linux** | Official install scripts or direct binary downloads | `curl -fsSL https://get.docker.com \| sh` |
| **macOS** | Homebrew | `brew install helm` |
| **Windows** | winget | `winget install --id Helm.Helm` |

After installation, the CLI re-checks the tool version. If the check fails, it displays the tool's manual install URL.

### Non-Interactive Behavior

In **non-interactive environments** (CI/CD, scripts, piped output, `--yes` mode without TTY), the CLI does **not** offer auto-installation. Instead, it raises a `PrerequisiteError` (error code `ILUM-001`) with a manual install link:

```
Error: kubectl is required but not available [ILUM-001]
  Suggestion: Install manually: https://kubernetes.io/docs/tasks/tools/
```

For CI/CD pipelines, install all required tools before invoking the CLI. See the guide's [CI/CD section](guide.md#64-github-actions-example-workflow) for an example GitHub Actions workflow.

### Supported Tools and Install URLs

| Tool | Manual Install URL |
|------|-------------------|
| `helm` | https://helm.sh/docs/intro/install/ |
| `kubectl` | https://kubernetes.io/docs/tasks/tools/ |
| `docker` | https://docs.docker.com/get-docker/ |
| `minikube` | https://minikube.sigs.k8s.io/docs/start/ |
| `k3d` | https://k3d.io/ |
| `kind` | https://kind.sigs.k8s.io/docs/user/quick-start/#installation |

### Docker Post-Install (Linux)

On Linux, after installing Docker the CLI automatically:
1. Adds the current user to the `docker` group (requires sudo)
2. Starts the Docker daemon via `systemctl`
3. Warns that a logout/login (or `newgrp docker`) may be required for group permissions

If passwordless sudo is not available, the CLI prints the manual commands instead.

---

## 21. Error Codes

Structured error codes for programmatic error handling (see also [Prerequisites](#20-prerequisites) for `ILUM-001` and `ILUM-002`):

| Code | Category | Title |
|------|----------|-------|
| ILUM-001 | prerequisite | Tool not found |
| ILUM-002 | prerequisite | Tool version too old |
| ILUM-010 | cluster | Cluster unreachable |
| ILUM-011 | cluster | Namespace not found |
| ILUM-020 | helm | Helm command failed |
| ILUM-021 | helm | Helm timeout |
| ILUM-022 | helm | Release stuck |
| ILUM-023 | helm | Release not found |
| ILUM-024 | helm | Release already exists |
| ILUM-030 | config | Config file invalid |
| ILUM-031 | config | Config key not found |
| ILUM-040 | module | Unknown module |
| ILUM-041 | module | Module conflict |
| ILUM-050 | values | Values parse error |
| ILUM-051 | values | Values drift detected |
| ILUM-070 | exec | Exec failed / No pods found |
| ILUM-071 | events | Events query failed |
| ILUM-072 | metrics | Metrics unavailable |
| ILUM-073 | helm | Rollback failed |

Error codes appear in both human-readable output and structured JSON/YAML output, enabling CI/CD pipelines to handle specific error conditions programmatically.

---

## 22. Module Registry

All 31 modules registered in `MODULE_REGISTRY`, grouped by category.

### Core

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `core` | Ilum backend API (Spring Boot on Spark) | Yes | — | — |
| `ui` | Ilum web frontend (React + Nginx reverse proxy) | Yes | `core` | — |
| `livy-proxy` | Livy-compatible Spark session proxy | No | `core` | — |

### Infrastructure

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `mongodb` | MongoDB document store for metadata | Yes | — | — |
| `kafka` | Apache Kafka event bus | No | `core` | — |
| `postgresql` | PostgreSQL relational database | Yes | — | — |
| `clickhouse` | ClickHouse columnar analytics database | No | — | — |
| `gitea` | Gitea self-hosted Git service | Yes | `postgresql` | — |

### Storage

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `minio` | MinIO S3-compatible object storage | Yes | — | — |

### Notebook

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `jupyter` | Jupyter notebook server with Sparkmagic | Yes | `core` | — |
| `jupyterhub` | Multi-user JupyterHub (Kubernetes >= 1.28) | No | `core` | — |
| `zeppelin` | Apache Zeppelin notebook server | No | `core` | — |

### SQL

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `sql` | Ilum SQL engine (Kyuubi) | No | `postgresql`, `core` | — |
| `trino` | Trino distributed SQL query engine | No | `hive-metastore` | — |
| `hive-metastore` | Hive Metastore service | No | `postgresql`, `core` | `nessie` |
| `nessie` | Nessie versioned data catalog | No | `postgresql` | `hive-metastore` |
| `unity-catalog` | Unity Catalog for data governance | No | `postgresql` | — |

### Orchestration

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `airflow` | Apache Airflow workflow orchestration | No | `postgresql` | — |
| `kestra` | Kestra declarative orchestration engine | No | `postgresql` | — |
| `n8n` | n8n workflow automation platform | No | — | — |
| `nifi` | Apache NiFi data integration | No | — | — |
| `mageai` | Mage.ai data pipeline tool | No | `postgresql` | — |

### Analytics

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `superset` | Apache Superset BI dashboards | No | `postgresql` | — |
| `streamlit` | Streamlit interactive data applications | No | — | — |
| `marquez` | Marquez data lineage tracking | No | — | — |

### AI

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `mlflow` | MLflow experiment tracking and model registry | No | — | — |
| `langfuse` | Langfuse LLM observability platform | No | `postgresql`, `clickhouse` | — |

### Monitoring

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `monitoring` | Prometheus + Grafana monitoring stack | No | — | — |
| `loki` | Grafana Loki log aggregation | No | — | — |
| `graphite` | Graphite metrics exporter | No | — | — |

### Security

| Name | Description | Default | Dependencies | Conflicts |
|------|-------------|---------|--------------|-----------|
| `openldap` | OpenLDAP directory service | No | — | — |

### Enable/Disable Flags Reference

| Module | Enable Flags | Disable Flags |
|--------|-------------|---------------|
| `core` | `ilum-core.enabled=true` | `ilum-core.enabled=false` |
| `ui` | `ilum-ui.enabled=true` | `ilum-ui.enabled=false` |
| `livy-proxy` | `ilum-livy-proxy.legacy.enabled=true` | `ilum-livy-proxy.legacy.enabled=false` |
| `mongodb` | `mongodb.enabled=true` | `mongodb.enabled=false` |
| `kafka` | `kafka.enabled=true`, `ilum-core.communication.type=kafka` | `kafka.enabled=false` |
| `postgresql` | `postgresql.enabled=true` | `postgresql.enabled=false` |
| `clickhouse` | `clickhouse.enabled=true` | `clickhouse.enabled=false` |
| `gitea` | `gitea.enabled=true` | `gitea.enabled=false` |
| `minio` | `minio.enabled=true` | `minio.enabled=false` |
| `jupyter` | `ilum-jupyter.enabled=true` | `ilum-jupyter.enabled=false` |
| `jupyterhub` | `ilum-jupyterhub.enabled=true` | `ilum-jupyterhub.enabled=false` |
| `zeppelin` | `ilum-zeppelin.enabled=true` | `ilum-zeppelin.enabled=false` |
| `sql` | `ilum-sql.enabled=true`, `ilum-core.sql.enabled=true` | `ilum-sql.enabled=false`, `ilum-core.sql.enabled=false` |
| `trino` | `trino.enabled=true` | `trino.enabled=false` |
| `hive-metastore` | `ilum-hive-metastore.enabled=true`, `ilum-core.metastore.enabled=true`, `ilum-core.metastore.type=hive` | `ilum-hive-metastore.enabled=false`, `ilum-core.metastore.enabled=false` |
| `nessie` | `nessie.enabled=true`, `ilum-core.metastore.enabled=true`, `ilum-core.metastore.type=nessie` | `nessie.enabled=false`, `ilum-core.metastore.enabled=false` |
| `unity-catalog` | `ilum-unity-catalog.enabled=true` | `ilum-unity-catalog.enabled=false` |
| `airflow` | `airflow.enabled=true` | `airflow.enabled=false` |
| `kestra` | `kestra.enabled=true` | `kestra.enabled=false` |
| `n8n` | `ilum-n8n.enabled=true` | `ilum-n8n.enabled=false` |
| `nifi` | `nifi.enabled=true` | `nifi.enabled=false` |
| `mageai` | `mageai.enabled=true` | `mageai.enabled=false` |
| `superset` | `superset.enabled=true` | `superset.enabled=false` |
| `streamlit` | `streamlit.enabled=true` | `streamlit.enabled=false` |
| `marquez` | `global.lineage.enabled=true` | `global.lineage.enabled=false` |
| `mlflow` | `mlflow.enabled=true` | `mlflow.enabled=false` |
| `langfuse` | `langfuse.enabled=true` | `langfuse.enabled=false` |
| `monitoring` | `kube-prometheus-stack.enabled=true` | `kube-prometheus-stack.enabled=false` |
| `loki` | `global.logAggregation.enabled=true`, `global.logAggregation.loki.enabled=true`, `global.logAggregation.promtail.enabled=true` | `global.logAggregation.enabled=false`, `global.logAggregation.loki.enabled=false`, `global.logAggregation.promtail.enabled=false` |
| `graphite` | `graphite-exporter.graphite.enabled=true` | `graphite-exporter.graphite.enabled=false` |
| `openldap` | `openldap.enabled=true` | `openldap.enabled=false` |

---

## 23. Doctor Checks

| Check Name | Phase | What it verifies |
|------------|-------|------------------|
| `helm` | 1 - Binaries | Helm is on PATH and version >= 3.12 |
| `kubectl` | 1 - Binaries | kubectl is on PATH and version >= 1.28 |
| `docker` | 1 - Binaries | Docker is on PATH and version >= 24.0 |
| `helm-repo` | 2 - Helm repo | The `ilum` chart repository (charts.ilum.cloud) is configured |
| `cluster` | 3 - Connectivity | Kubernetes cluster is reachable via current kubeconfig |
| `namespace` | 4 - Cluster-dependent | The target namespace exists on the cluster |
| `pods` | 4 - Cluster-dependent | All pods in the namespace are healthy; detects CrashLoopBackOff (>5 restarts) |
| `pvcs` | 4 - Cluster-dependent | All PersistentVolumeClaims are Bound; detects Pending PVCs |
| `rbac` | 4 - Cluster-dependent | Required RBAC permissions are granted to the current user |
| `release` | 4 - Cluster-dependent | Helm release exists and is not in stuck (`pending-*`) or `failed` state |
| `compatibility` | 4 - Cluster-dependent | Kubernetes server version >= 1.28 |
| `service-endpoints` | 4 - Cluster-dependent | Service endpoints have ready addresses |
| `health-endpoints` | 4 - Cluster-dependent | Health check endpoints respond for core, airflow, superset, minio |

---

## 24. Error Reference

| Class | Parent | When Raised | Typical Suggestion |
|-------|--------|-------------|-------------------|
| `IlumError` | `Exception` | Base exception for all Ilum CLI errors. | — |
| `PrerequisiteError` | `IlumError` | A required tool or resource (helm, kubectl, docker) is missing. | Install the missing tool. |
| `ClusterConnectionError` | `IlumError` | Cannot connect to the Kubernetes cluster. | Check kubeconfig: `kubectl cluster-info`. |
| `HelmError` | `IlumError` | A Helm operation failed. | Check `helm` output for details. |
| `HelmTimeoutError` | `HelmError` | A Helm operation timed out. | Increase `--timeout` or check cluster resources. |
| `HelmReleaseError` | `HelmError` | A Helm release is in a bad state (e.g. `pending-install`, `pending-upgrade`). | Use `ilum upgrade --force-rollback` to recover. |
| `ConfigError` | `IlumError` | Configuration is missing or invalid. | Run `ilum config init` or `ilum init`. |
| `ValuesError` | `IlumError` | Problem with Helm values files. | Validate your values YAML syntax. |
| `ModuleError` | `IlumError` | Module dependency or conflict error. | Check `ilum module show <name>` for dependencies. |
| `ReleaseExistsError` | `IlumError` | A Helm release already exists when a fresh install was requested. | Use `ilum upgrade` instead, or `ilum uninstall` first. |
| `ReleaseNotFoundError` | `IlumError` | A Helm release was expected but does not exist. | Use `ilum install` to create the release, or `ilum connect` to attach to an existing one. |

---

## 25. Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success. |
| `1` | Error (any `IlumError`, invalid input, failed check, or failed Helm operation). |
| `130` | Interrupted by user (`Ctrl+C` during `ilum init`). |

`ilum uninstall` exits with code `0` even when the release does not exist (idempotent behavior).
