Installation
One-Line Installer
The fastest way to install the Ilum CLI is the bootstrap script. It uses a tiered fallback strategy: it tries pipx first, then uv, and finally downloads a standalone binary if neither Python package manager is available.
Linux / macOS:
$ curl -fsSL https://get.ilum.cloud/cli | bash
Detecting package manager...
Found pipx 1.7.1
Installing ilum via pipx...
installed package ilum 0.1.0
Done. Run 'ilum --version' to verify.
You can pin a specific version by setting the ILUM_VERSION environment variable before running the installer:
$ ILUM_VERSION=0.1.0 curl -fsSL https://get.ilum.cloud/cli | bash
Windows (PowerShell):
PS> irm https://get.ilum.cloud/cli/windows | iex
The Windows installer tries winget first, then pip, and finally downloads a standalone .exe binary. You can pin a version with $env:ILUM_VERSION = "0.1.0" before running.
The installers never modify files outside of your user-local package directories. They do not require administrator/root access.
Package Managers
If you prefer explicit control, install directly with your Python package manager of choice. The CLI requires Python 3.12 or later.
pipx (recommended for CLI tools):
$ pipx install ilum
uv:
$ uv tool install ilum
pip (into a virtual environment):
$ pip install ilum
Verifying the Installation
After installing, confirm the CLI is on your PATH and print its version:
$ ilum --version
ilum 0.1.0
Then run a quick health check to verify that your environment has the required tools:
$ ilum doctor
Doctor checks for helm (>= 3.12), kubectl (>= 1.28), and docker (>= 24.0). If any tool is missing, the output tells you exactly what to install. See Running Doctor for full details.
Shell Completion
The ilum CLI supports shell completion for Bash, Zsh, and Fish:
# Bash
ilum --install-completion bash
# Zsh
ilum --install-completion zsh
# Fish
ilum --install-completion fish
After installing completion, restart your shell. Tab completion works for:
- Module names (
ilum module show <TAB>) - Profile names (
ilum config use <TAB>) - Doctor check names (
ilum doctor --check <TAB>)
Prerequisites (helm, kubectl, docker)
The Ilum CLI requires three tools to be installed on your system:
| 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 |
If you plan to create a local Kubernetes cluster, you also need one cluster provider:
| Provider | Description |
|---|---|
k3d | Lightweight k3s clusters in Docker containers (default) |
minikube | Full Kubernetes in a VM or container |
kind | Kubernetes-in-Docker for testing |
Standalone installation with ilum deps. The fastest way to install all prerequisites is the ilum deps install command. It works in both interactive and non-interactive mode (no TTY required), making it ideal for CI pipelines and scripted setups:
$ ilum deps install
ℹ Installing helm...
✓ helm installed successfully (helm 3.16.3)
✓ kubectl already installed (kubectl 1.30.0)
✓ docker already installed (docker 27.3.1)
ℹ Installing k3d...
✓ k3d installed successfully (k3d 5.7.1)
ℹ Summary: 2 installed, 2 already present.
You can also install specific tools, choose a different cluster provider, or preview what would be installed:
# Install only helm and kubectl
$ ilum deps install helm kubectl
# Install with kind instead of the default k3d
$ ilum deps install --provider kind
# Preview without executing
$ ilum deps install --dry-run
To check the status of all dependencies without installing anything, use ilum deps list:
$ ilum deps list
Automatic installation (interactive mode). When you run ilum init or ilum quickstart in an interactive terminal, the CLI checks for each required tool during the preflight step. If a tool is missing or outdated, it offers to install it for you:
$ ilum quickstart
╭─ ilum quickstart ────────────────────────────────────────╮
│ Ilum Quickstart │
╰──────────────────────────────────────────────────────────╯
ℹ Step 1/4: Checking prerequisites...
✓ helm 3.16.3
✗ kubectl not found
? Install kubectl now? Yes
ℹ Installing kubectl via direct download...
✓ kubectl installed successfully
✓ docker 27.3.1
✓ All prerequisites met.
...
The CLI installs tools using platform-appropriate methods:
| Platform | Install Method |
|---|---|
| Linux | Official install scripts or direct binary downloads to /usr/local/bin/ |
| macOS | Homebrew (brew install) |
| Windows | winget (winget install) |
After installation, the CLI re-checks the tool version to confirm success. If the automatic install fails, the error message includes a link to the tool's manual installation page.
Non-interactive mode (CI/scripts). Auto-installation is only available in interactive terminals. In non-interactive environments (CI pipelines, scripts, cron jobs, or when piping output), the CLI raises an error if a required tool is missing:
$ ilum install --yes 2>&1
Error: kubectl is required but not available
Suggestion: Install manually: https://kubernetes.io/docs/tasks/tools/
In CI/CD pipelines, install prerequisites before running the CLI. See GitHub Actions Example Workflow for a complete example.
Cluster provider auto-install. When you run ilum cluster create --provider k3d or select a provider in the ilum init wizard, the CLI checks for the provider binary and offers to install it if missing (interactive mode only). This applies to k3d, minikube, and kind.
Checking prerequisites without installing. Use ilum doctor to check all tool versions without triggering any installation:
$ ilum doctor --check helm --check kubectl --check docker
See Running Doctor for full details on the doctor command.
After ilum cleanup --deps: If you previously removed dependencies with ilum cleanup --deps and need to reinstall them, run ilum deps install to restore all required tools non-interactively. Alternatively, run ilum init interactively or install tools manually using the commands shown below.
Manual installation (all platforms):
# Linux — helm
curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
# Linux — kubectl
curl -fsSLo /tmp/kubectl \
"https://dl.k8s.io/release/$(curl -fsSL https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x /tmp/kubectl && sudo mv /tmp/kubectl /usr/local/bin/kubectl
# Linux — docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER && newgrp docker
# Linux — k3d
curl -fsSL https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
# macOS — all tools via Homebrew
brew install helm kubectl k3d
brew install --cask docker