Managing Configuration
The Ilum CLI stores all of its state in a YAML configuration file. On Linux/macOS this is ~/.config/ilum/config.yaml; on Windows it is %APPDATA%\ilum\config.yaml. Run ilum config path to see the exact location on your system. This file holds profile definitions, cluster records, and the active profile pointer. You never need to edit it by hand -- the ilum config sub-commands and ilum init wizard handle everything -- but the format is straightforward YAML if you want to inspect or version-control it.
Profiles
Profiles let you manage multiple Ilum environments (dev, staging, production) from a single machine. Each profile stores a release name, Kubernetes context, namespace, chart version, enabled modules, and communication settings.
The profile data structure:
profiles:
افتراضي:
اسم: افتراضي
release_name: إيلوم
عنقود:
kubecontext: k3d-إيلوم-ديف
Namespace: افتراضي
chart_version: "6.7.0"
chart_repo: https://charts.ilum.cloud
enabled_modules:
- لب
- جيتا
- جوبيتر
- مينيو
- mongodb
- postgresql
- واجهة المستخدم
communication_type: جي بي سي
auth_type: داخلي
custom_values_path: ""
Create a new profile using the init wizard:
$ ilum init --profile staging
The wizard walks you through context selection, namespace, module selection, and saves a new profile named staging. The newly created profile automatically becomes the active profile.
Switch between profiles:
$ ilum config جبر active_profile staging
✓ active_profile = staging
After switching, all commands (ilum status, ilum upgrade, ilum logs, etc.) operate against the staging release without needing extra flags.
View the active profile:
$ ilum config show active_profile
staging
View all profiles in the full configuration:
$ ilum config show
╭─ ilum config ────────────────────────────────────────────╮
│ active_profile: staging │
│ profiles: │
│ default: │
│ name: default │
│ release_name: ilum │
│ cluster: │
│ kubecontext: k3d-ilum-dev │
│ namespace: default │
│ chart_version: '6.7.0' │
│ chart_repo: https://charts.ilum.cloud │
│ enabled_modules: │
│ - core │
│ - gitea │
│ - jupyter │
│ - minio │
│ - mongodb │
│ - postgresql │
│ - ui │
│ communication_type: grpc │
│ auth_type: internal │
│ custom_values_path: '' │
│ staging: │
│ name: staging │
│ release_name: ilum-staging │
│ cluster: │
│ kubecontext: arn:aws:eks:eu-central-1:123456:... │
│ namespace: staging │
│ chart_version: '6.7.0' │
│ chart_repo: https://charts.ilum.cloud │
│ enabled_modules: │
│ - core │
│ - mongodb │
│ - postgresql │
│ - ui │
│ communication_type: grpc │
│ auth_type: internal │
│ custom_values_path: '' │
│ clusters: [] │
╰──────────────────────────────────────────────────────────╯
Override the profile on any command by passing --release, --namespaceو --context flags directly. These flags take precedence over the active profile:
$ ilum status --release ilum-staging --namespace staging --context my-eks-cluster
Profile Management
Beyond creating profiles with ilum init and switching with config set, the CLI provides dedicated commands for managing profiles:
List all profiles:
$ ilum config list-profiles
Switch the active profile:
$ ilum config use staging
✓ Switched to profile 'staging'.
Export a profile for team sharing:
$ ilum config export production --out prod-profile.yaml
✓ Profile 'production' exported to prod-profile.yaml
Import a shared profile:
$ ilum config استورد prod-profile.yaml --اسم production
✓ Profile 'production' imported.
Validate the configuration file:
$ ilum config validate
✓ Configuration is valid.
Back up the configuration:
$ ilum config backup
✓ Backup saved to /home/user/.config/ilum/config.yaml.bak
Export and import are useful for onboarding team members: one person configures the environment, exports the profile, and others import it to get identical settings without running through the wizard.
Config Get / Set / Edit
ال ilum config sub-commands give you programmatic and interactive access to the configuration file.
Show the entire config:
$ ilum config show
Read a specific key using dot-notation:
$ ilum config show active_profile
افتراضي
$ ilum config show profiles.default.cluster.namespace
افتراضي
$ ilum config show profiles.staging.enabled_modules
['core', 'mongodb', 'postgresql', 'ui']
If the key does not exist, the CLI exits with code 1:
$ ilum config show nonexistent.key
✗ Key not found: nonexistent.key
Set a specific key:
$ ilum config جبر active_profile production
✓ active_profile = production
$ ilum config جبر profiles.default.cluster.namespace ilum-system
✓ profiles.default.cluster.namespace = ilum-system
The set command validates the new value against the Pydantic configuration model. If the value is invalid for the field type, you get an error with a suggestion.
Print the config file path:
$ ilum config path
/home/user/.config/ilum/config.yaml
This is useful in scripts that need to back up or version-control the config file:
$ cp "$(ilum config path)" ~/ilum-config-backup.yaml
Create a default config file:
$ ilum config init
✓ Created config: /home/user/.config/ilum/config.yaml
If a config file already exists, the command warns you and does nothing. Pass --force to overwrite:
$ ilum config init --force
✓ Created config: /home/user/.config/ilum/config.yaml
Open the config in your editor:
$ ilum config edit
This opens the config file in $EDITOR (falling back to $VISUAL, then vi on Linux/macOS or notepad on Windows). After you save and close the editor, the changes take effect immediately -- there is no separate "apply" step.
The configuration file uses platform-native file locking (fcntl on Linux/macOS, msvcrt on Windows) to prevent concurrent writes from corrupting the YAML. This means you can safely run CLI commands in parallel (for example, from multiple terminal tabs or CI jobs targeting different profiles) without worrying about write races.
Connecting to Existing Installations
If you already have Ilum running on a cluster (deployed manually with helm install or by another team member), the ilum connect command imports that release into the CLI's configuration without reinstalling anything.
Auto-detect mode (recommended). Run ilum connect without arguments to scan all namespaces for Ilum Helm releases:
$ ilum connect
⠋ Scanning من أجل Ilum releases...
ℹ Found 1 Ilum release:
Release: ilum
Namespace: default
Version: 6.7.0
Status: deployed
? Connect this release to profile 'default'? [Y/n] y
✓ Profile 'default' updated with release 'ilum' في Namespace 'default'.
✓ 7 modules synced to config.
✓ Values snapshot saved (drift detection enabled).
ℹ
ℹ Next steps:
ℹ ilum status Show release status
ℹ ilum upgrade Upgrade to a newer version
ℹ ilum module enable Enable additional modules
The connect command:
- Scans for Helm releases whose chart name is
إيلوم. - Detects which modules are currently enabled by inspecting the computed values.
- Saves the release, namespace, context, chart version, and enabled modules to a CLI profile.
- Takes a values snapshot so that future operations can detect drift.
Multiple releases. When the scan finds more than one Ilum release, you get a numbered table to choose from:
$ ilum connect
⠋ Scanning من أجل Ilum releases...
╭─ Found Ilum Releases ─────────────────────────────────────────╮
│ # Release Namespace Version Status │
├────────────────────────────────────────────────────────────────┤
│ 1 ilum default 6.7.0 deployed │
│ 2 ilum-staging staging 6.6.1 deployed │
╰────────────────────────────────────────────────────────────────╯
? Select release [1-2]: 2
✓ Profile 'default' updated with release 'ilum-staging' في Namespace 'staging'.
✓ 4 modules synced to config.
✓ Values snapshot saved (drift detection enabled).
Direct mode. If you know the exact release name and namespace, skip the scan entirely:
$ ilum connect --release ilum-staging --namespace staging --profile staging
✓ Profile 'staging' updated with release 'ilum-staging' في Namespace 'staging'.
✓ 4 modules synced to config.
✓ Values snapshot saved (drift detection enabled).
Connect to a specific Kubernetes context:
$ ilum connect --context arn:aws:eks:eu-central-1:123456:cluster/production --profile production
Non-interactive mode for scripts:
$ ilum connect --yes
في --yes mode, if multiple releases are found, the CLI auto-selects the first one. If a single release is found, it connects without prompting.
Stuck release warning. If the discovered release is in a stuck state (pending-install, pending-upgradeأو pending-rollback), the connect command still imports it but prints a warning:
⚠ Release 'ilum' هل في 'pending-upgrade' state. Run 'ilum upgrade --force-rollback' to recover.
ال ilum connect command is read-only with respect to the cluster. It does not install, upgrade, or modify the Helm release in any way. It only writes to the local CLI configuration file.