Command Reference

1. Global Options​

$ 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​

Wizard Steps​

Esempi ​

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

Steps Performed​

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

Esempi ​

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

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.

Esempi ​

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

Values Safety Pipeline​

1. Stuck release detection -- if the release is in pending-install, pending-upgradeo 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 --valori-di-riutilizzo 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.

Esempi ​

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

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-datao --delete-namespace is passed (without --yes), the user must type the release name to confirm.

Esempi ​

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

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

Esempi ​

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

Auto-detect vs Direct Mode​

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.

Esempi ​

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

Esempi ​

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

Esempi ​

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

Source Modes​

Esempi ​

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

Esempi ​

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

Options​

Esempi ​

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

Options​

Esempi ​

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

Options​

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

Esempi ​

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

Checks Table​

Phase Gating​

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

Esempi ​

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

Esempi ​

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

Esempi ​

$ 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​

Esempi ​

$ 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​

Options​

Esempi ​

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

Options​

Esempi ​

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

Esempi ​

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

Esempi ​

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

Esempi ​

$ ilum config set active_profile staging

12.3 ilum config path​

Print the configuration file path.

Synopsis​

ilum config path

Esempi ​

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

Esempi ​

# 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

Esempi ​

$ EDITOR=nano ilum config edit

12.6 ilum config use​

Switch the active profile.

Synopsis​

ilum config use PROFILE

Arguments​

Esempi ​

$ ilum config use staging
$ ilum config use production

12.7 ilum config list-profiles​

List all configured profiles.

Synopsis​

ilum config list-profiles

Esempi ​

$ ilum config list-profiles

12.8 ilum config validate​

Validate the configuration file for correctness.

Synopsis​

ilum config validate

Esempi ​

$ ilum config validate

12.9 ilum config backup​

Create a backup copy of the configuration file.

Synopsis​

ilum config backup

Esempi ​

$ ilum config backup

12.10 ilum config export​

Export a profile for team sharing.

Synopsis​

ilum config export PROFILE [OPTIONS]

Arguments​

Options​

Esempi ​

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

Options​

Esempi ​

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

Presets Table​

Esempi ​

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

Esempi ​

$ ilum cluster delete ilum-dev

13.3 ilum cluster list​

List tracked local Kubernetes clusters.

Synopsis​

ilum cluster list

Esempi ​

$ ilum cluster list

14. ilum preset list​

List all available deployment presets.

Synopsis​

ilum preset list

Descrizione ​

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​

Esempi ​

# List all presets
$ ilum preset list

15. ilum airgap images​

List container images required by selected modules.

Synopsis​

ilum airgap images [OPTIONS]

Descrizione ​

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​

Esempi ​

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

Descrizione ​

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​

Options​

Esempi ​

# 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

Descrizione ​

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​

Options​

Esempi ​

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

Esempi ​

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

Options​

Esempi ​

# 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

Esempi ​

$ 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​

Esempi ​

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

Esempi ​

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

Esempi ​

# Disable ingress
$ ilum access ingress disable --yes

ilum access ingress show​

Show the current ingress configuration.

Synopsis​

ilum access ingress show [OPTIONS]

Options​

Esempi ​

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

Esempi ​

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

Options​

Esempi ​

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

Esempi ​

# Disable OAuth
$ ilum auth disable --yes

ilum auth status​

Show the current authentication configuration from live Helm values.

Synopsis​

ilum auth status [OPTIONS]

Options​

Esempi ​

# 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

Esempi ​

$ 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 installe ilum upgrade.

Required Tools​

Cluster Providers (optional)​

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

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:

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 non 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​

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 Prerequisiti per ILUM-001e ILUM-002):

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​

Infrastructure​

Immagazzinamento ​

Taccuino ​

SQL ​

Orchestrazione ​

Analytics​

AI​

Monitoraggio ​

Sicurezza ​

Enable/Disable Flags Reference​

23. Doctor Checks​

24. Error Reference​

25. Exit Codes​

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