Command 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.

$ 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). 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

# 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. tiny, default, data-engineering, production).
--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). 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

# 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. tiny, default, data-engineering, production).
--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

# 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 (uses Helm's --reset-then-reuse-values). Enabled automatically when the chart version changes.
--reuse-values	—	False	Force reuse of previous values even when chart version changes. Overrides the automatic --reset-defaults behavior.
--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. Auto-reset chart defaults -- when the chart version changes, the CLI automatically uses --reset-then-reuse-values so new chart defaults (e.g. updated image tags) take effect. Pass --reuse-values to opt out.
3. Drift detection -- external changes made since the last CLI operation are displayed as a diff table and preserved during upgrade.
4. Breaking change warnings -- version transitions are checked for known breaking changes.
5. 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

Examples

# 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

# 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

# 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

$ 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

$ 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

# 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

# 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

# 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

# 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

$ ilum config set active_profile staging

12.3 ilum config path

Print the configuration file path.

Synopsis

ilum config path

Examples

# 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

# 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

$ 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

$ ilum config use staging
$ ilum config use production

12.7 ilum config list-profiles

List all configured profiles.

Synopsis

ilum config list-profiles

Examples

$ ilum config list-profiles

12.8 ilum config validate

Validate the configuration file for correctness.

Synopsis

ilum config validate

Examples

$ ilum config validate

12.9 ilum config backup

Create a backup copy of the configuration file.

Synopsis

ilum config backup

Examples

$ 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

# 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

# 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

# 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

$ ilum cluster delete ilum-dev

13.3 ilum cluster list

List tracked local Kubernetes clusters.

Synopsis

ilum cluster list

Examples

$ 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

# 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

# List images for default modules
$ ilum airgap images

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

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

# Plain output for scripting
$ ilum airgap images --preset tiny --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

# Export default modules
$ ilum airgap export ./bundle

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

# 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

# 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

# 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

# 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

$ ilum deps list

---

19b. ilum access

Manage access to the Ilum UI via port-forward, NodePort, or ingress.

ilum access open

Open the Ilum UI in a browser.

Synopsis

ilum access open [OPTIONS]

Options

Flag	Short	Default	Description
--release	-r	from profile	Helm release name.
--namespace	-n	from profile	Kubernetes namespace.
--context	—	from profile	Kubernetes context.
--access	-a	from profile	Access method: nodeport, port-forward, or ingress.
--port	-p	9777	Local port to forward to (port-forward mode).
--address	—	127.0.0.1	Local address to bind to (port-forward mode).
--no-browser	—	False	Don't open a browser automatically.

Examples

# Open UI with default access method (from profile)
$ ilum access open

# Open via port-forward on a custom port
$ ilum access open --access port-forward --port 8080

# Open via NodePort without launching browser
$ ilum access open --access nodeport --no-browser

# Open via ingress
$ ilum access open --access ingress

ilum access ingress enable

Enable ingress for the Ilum UI via Helm upgrade.

Synopsis

ilum access ingress enable --host HOSTNAME [OPTIONS]

Options

Flag	Short	Default	Description
--host	—	required	Ingress hostname.
--tls	—	False	Enable TLS.
--tls-secret	—	""	TLS secret name.
--class	—	""	Ingress class name.
--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).
--yes	-y	False	Skip confirmation prompt.
--dry-run	—	False	Preview without executing.
--timeout	—	10m	Helm timeout.

Examples

# Enable ingress with a hostname
$ ilum access ingress enable --host ilum.example.com

# Enable ingress with TLS
$ ilum access ingress enable --host ilum.example.com --tls

# Enable with a specific ingress class
$ ilum access ingress enable --host ilum.example.com --class nginx

ilum access ingress disable

Disable ingress for the Ilum UI.

Synopsis

ilum access ingress disable [OPTIONS]

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).
--yes	-y	False	Skip confirmation prompt.
--dry-run	—	False	Preview without executing.
--timeout	—	10m	Helm timeout.

Examples

# Disable ingress
$ ilum access ingress disable --yes

ilum access ingress show

Show the current ingress configuration.

Synopsis

ilum access ingress show [OPTIONS]

Options

Flag	Short	Default	Description
--release	-r	from profile	Helm release name.
--namespace	-n	from profile	Kubernetes namespace.
--context	—	from profile	Kubernetes context.

Examples

# Show ingress config
$ ilum access ingress show

# JSON output
$ ilum access ingress show --output json

---

19c. ilum auth

Manage authentication and OAuth configuration.

ilum auth setup

Interactive authentication setup wizard. Guides you through selecting an auth mode (internal Hydra, external OAuth2, or disable), choosing a provider, and collecting required parameters.

Synopsis

ilum auth setup [OPTIONS]

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).
--yes	-y	False	Skip confirmation prompt.
--dry-run	—	False	Preview without executing.
--timeout	—	10m	Helm timeout.

Examples

# Launch the interactive auth wizard
$ ilum auth setup

# Dry-run preview of auth changes
$ ilum auth setup --dry-run

ilum auth enable

Enable authentication with a specific provider non-interactively.

Synopsis

ilum auth enable PROVIDER [OPTIONS]

Arguments

Argument	Required	Description
PROVIDER	Yes	Provider name (e.g. google, hydra, oidc, okta, gitlab, keycloak, cognito, azure).

Options

Flag	Short	Default	Description
--client-id	—	None	OAuth2 Client ID.
--client-secret	—	None	OAuth2 Client Secret.
--domain	—	None	Domain (Hydra UI domain or Okta domain).
--protocol	—	None	Protocol — Hydra: http or https.
--url	—	None	Provider URL (GitLab, Keycloak).
--realm	—	None	Keycloak realm name.
--region	—	None	AWS region (Cognito).
--user-pool-id	—	None	Cognito User Pool ID.
--tenant-id	—	None	Azure AD Tenant ID.
--issuer-uri	—	None	OIDC Issuer URI.
--scope	—	None	OAuth2 scopes.
--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).
--yes	-y	False	Skip confirmation prompt.
--dry-run	—	False	Preview without executing.
--timeout	—	10m	Helm timeout.

Examples

# Enable Hydra (internal) auth
$ ilum auth enable hydra --domain ilum.example.com --yes

# Enable Google OAuth2
$ ilum auth enable google --client-id MY_ID --client-secret MY_SECRET --yes

# Enable a generic OIDC provider
$ ilum auth enable oidc --issuer-uri https://auth.example.com --client-id MY_ID --client-secret MY_SECRET

ilum auth disable

Disable OAuth and revert to internal authentication.

Synopsis

ilum auth disable [OPTIONS]

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).
--yes	-y	False	Skip confirmation prompt.
--dry-run	—	False	Preview without executing.
--timeout	—	10m	Helm timeout.

Examples

# Disable OAuth
$ ilum auth disable --yes

ilum auth status

Show the current authentication configuration from live Helm values.

Synopsis

ilum auth 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.

Examples

# Show auth status
$ ilum auth status

# JSON output
$ ilum auth status --output json

ilum auth list

List all available authentication providers.

Synopsis

ilum auth list

Examples

$ ilum auth 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 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 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 32 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	—
api	Ilum REST API for module management	Yes	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
rustfs	RustFS S3-compatible object storage (bundled, opt-in; planned default in 6.8.0)	No	—	minio (when both flagged as the active provider)
minio	MinIO S3-compatible object storage (bundled default in 6.7.x)	Yes	—	rustfs (when both flagged as the active provider)

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)	Yes	postgresql, core	—
trino	Trino distributed SQL query engine	No	hive-metastore, sql	—
hive-metastore	Hive Metastore service	Yes	postgresql, core	nessie, unity-catalog
nessie	Nessie versioned data catalog	No	postgresql	hive-metastore, unity-catalog
unity-catalog	Unity Catalog for data governance	No	postgresql	hive-metastore, nessie

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	postgresql	—
nifi	Apache NiFi data integration	No	core	—
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	core	—
marquez	Marquez data lineage tracking	Yes	postgresql	—

AI

Name	Description	Default	Dependencies	Conflicts
mlflow	MLflow experiment tracking and model registry	No	postgresql	—
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, ilum-core.communication.type=grpc
postgresql	postgresql.enabled=true	postgresql.enabled=false
clickhouse	clickhouse.enabled=true	clickhouse.enabled=false
gitea	gitea.enabled=true	gitea.enabled=false
rustfs	rustfs.enabled=true	rustfs.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, ilum-sql.config.trino.enabled=true	trino.enabled=false, ilum-sql.config.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, ilum-core.metastore.type=hive
nessie	nessie.enabled=true, ilum-core.metastore.enabled=true, ilum-core.metastore.type=nessie	nessie.enabled=false, ilum-core.metastore.enabled=false, ilum-core.metastore.type=hive
unity-catalog	ilum-unity-catalog.enabled=true, ilum-core.metastore.enabled=true, ilum-core.metastore.type=unity	ilum-unity-catalog.enabled=false, ilum-core.metastore.enabled=false, ilum-core.metastore.type=hive
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, ilum-core.job.graphite.enabled=true	graphite-exporter.graphite.enabled=false, ilum-core.job.graphite.enabled=false
api	ilum-api.enabled=true	ilum-api.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).