cilium-cli: the operator side tool for installing and debugging Cilium

cilium install does the chart work after detecting your cluster

The headline capability is a single command that installs Cilium into whatever cluster you happen to be pointing at. The README shows the command and the sequence of work it performs.

    cilium install

Behind that one line the tool detects the environment, runs environment specific validation checks, picks a Cilium version when you have not set one, reuses an existing certificate authority from the cilium-ca secret when it finds one, generates the Hubble certificates, and then creates the objects the deployment needs: service accounts, cluster roles, a ConfigMap, the agent DaemonSet and the operator Deployment. The detection step is the part that saves the most time, since the same Helm invocation differs between a local kind cluster, a managed Kubernetes service and a self-managed one. The supported environments are listed as minikube, kind, EKS, self-managed, GKE, AKS BYOCNI and k3s, with Rancher appearing in the same list but left unchecked, which reads as a known gap rather than an oversight in the documentation. The takeaway for an evaluator is that the environment support is broad for the common cases and explicitly incomplete for one.

Context, status and Hubble are separate commands, not one workflow

The tool is organised as a set of independent verbs rather than one guided flow, and each of them maps to something you would otherwise do by hand with kubectl and Helm. Context management reports which cluster you are pointed at.

    cilium context

The output shows the context name, the cluster name, the auth method, the API server host, the TLS server name and the CA path. That last field is worth pausing on, because it tells you which trust anchor the tool is using, which matters when you move between clusters with different certificate authorities. Status reporting is a second verb.

    cilium status

The status output is a per-component health summary covering Cilium, the operator, the Envoy DaemonSet, Hubble Relay and ClusterMesh, followed by desired and ready replica counts for the DaemonSets and Deployments, container states, and the exact image versions pulled from quay.io for the agent, the Envoy sidecar, the operator and the relay. That image list is the part operators actually use, since a mismatch between agent and operator versions is a common source of confusing failures. Enabling Hubble is a third verb, `cilium hubble enable`, which generates the Relay certificates and deploys the Relay.

The connectivity test is the part that actually finds the fault

The connectivity test is the most useful command in the set, and it comes in two forms. The plain form runs without flow validation.

    cilium connectivity test --single-node

It waits for deployments to become ready, tries to enable the Hubble telescope, and then validates a series of paths: from a client pod to another pod on the same node, from a client pod to the outside of the cluster, from a client pod to the local host, and from a client pod to a service. When Hubble is not reachable the tool says so and tells you how to expose the relay.

    cilium hubble port-forward&
    cilium connectivity test --single-node

With the relay port forwarded, the same test adds flow validation and prints the individual flow log lines for each connection, showing the source and destination addresses, the verdict such as FORWARDED, and the TCP flags. That difference matters in practice. The non-flow version answers whether traffic works, and the flow version answers why, since the verdict on each flow is what tells you whether a packet was forwarded, dropped, or delivered to a different identity. This is the difference between a connectivity checker and a debugging tool, and it is why the test is the command worth running when something is broken rather than only when you want to know that it is not.

Building from source and installing a release binary

Building is a Makefile operation, and the install target is the one to use.

make install

The Makefile sets BINDIR to /usr/local/bin by default, and the README documents overriding it to put the binary somewhere else.

BINDIR=~/.local/bin make install

The release route downloads a tarball for your platform, and the README gives the full sequence, including the checksum verification step and the cleanup.

CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
GOOS=$(go env GOOS)
GOARCH=$(go env GOARCH)
curl -L --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-${GOOS}-${GOARCH}.tar.gz{,.sha256sum}
sha256sum --check cilium-${GOOS}-${GOARCH}.tar.gz.sha256sum
sudo tar -C /usr/local/bin -xzvf cilium-${GOOS}-${GOARCH}.tar.gz
rm cilium-${GOOS}-${GOARCH}.tar.gz{,.sha256sum}

Note that the version comes from stable.txt on the main branch rather than from a hardcoded tag, so a fresh install tracks whatever the project has marked as stable at that moment, and the sha256sum check is part of the documented sequence rather than an optional extra. The release list also ships an action.yaml at the top level, so the CLI is usable as a GitHub Action step as well as a local binary.

The go.mod replace directives are the real compatibility story

The Go module file is where the coupling between the CLI and Cilium itself becomes visible, and it is more informative than the release table. The module declares go 1.26.0, and it requires github.com/cilium/cilium at a pre-release commit of v1.21.0, pinned to a specific hash and dated pseudo-version. It also carries replace directives with a comment telling maintainers to keep them in sync when updating Cilium, including a private fork of controller-tools at v0.22.0-1, used because of reasons explained in a commit message, and a controller-runtime replace at v0.24.1 with a pseudo-version, with a comment noting that controller-runtime v0.25, which would match the Kubernetes libraries in use, is not yet released. The build tooling is pinned with equal care. The Dockerfile uses a golang builder image pinned by digest and produces a distroless static image, and the Makefile pins its own container image by digest and a golangci-lint version. The practical consequence is that the CLI is not independent of Cilium's own dependency graph, which is why the README ties a CLI release to a range of compatible Cilium versions rather than promising loose coupling.

Release compatibility, and what the tool does not cover

The README's release table lists v0.20.1 as maintained and compatible with Cilium 1.17 and newer, and the recent release tags follow a steady monthly rhythm, with v0.20.1 on 2026-09-24, v0.20.0 on 2026-08-28 and v0.19.7 on 2026-07-28. The last push to the repository was on 2026-10-22, so the source is moving faster than the tagged releases, which is normal for a tool that is often run against a main branch build of Cilium itself. The limits of the tool are worth stating. It is a wrapper around Helm and kubectl behaviour, so anything the underlying chart does not expose is not reachable through it, and a team with pinned chart values and tuned flags may find the CLI adds a layer rather than removing one. It does not manage the Cilium operator's own configuration beyond what install sets up. It does not cover Rancher, which is listed among the environments without being checked off. And the project description calls it a tool to install, manage and troubleshoot, which is the accurate scope: it is a convenience and diagnostic layer, and for a team that already has a mature Helm-based pipeline, its value is the connectivity test and the status view rather than the installer.

Building the CLI by hand versus scripting Helm and kubectl

The alternative is to skip the CLI and script the same steps directly with Helm and kubectl, which is entirely doable since the CLI is a thin layer over those calls. The difference in approach shows up in three places. The first is environment detection, where the CLI resolves the differences between a kind cluster and a managed Kubernetes service for you, and a script has to encode that logic or accept a flag for it. The second is diagnostic output, where `cilium status` and the connectivity test with flow validation give you component health, image versions and per-flow verdicts in one place, and a script has to assemble that from several kubectl calls and a Hubble relay of its own. The third is the cost of version drift. The CLI release is tied to a range of compatible Cilium versions, so a script that calls the chart with whatever flags it wants can hit a Cilium upgrade and fail in ways that are tedious to trace, while a CLI release is meant to be compatible with the range the README states. The argument against is ownership. A script is yours and behaves exactly as written, and the CLI is a dependency whose defaults, detection heuristics and version compatibility can change underneath you between releases.

Editorial conclusion

Adopt cilium-cli when you want one binary that installs Cilium across minikube, kind, k3s and managed clusters, checks the result and runs connectivity tests without assembling Helm flags by hand. Skip it if your workflow is pinned to a specific chart release and Helm flags, since the CLI abstracts those away, or if you need the features the README still lists as unsupported, such as Rancher. Verify first which CLI release matches your Cilium version, since the README states v0.20.1 is compatible with Cilium 1.17 and newer, and confirm the checksum of any downloaded release binary before running it.

Frequently asked questions

Official sources

1. cilium/cilium-cli on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases