Cilium CLI for coding agents

When a coding agent has shell access to a Kubernetes cluster, it can use the Cilium CLI to check Cilium’s health and test network connections between applications running in the cluster. Cilium is networking software for Kubernetes. The CLI runs on your computer and sends requests to the cluster selected by your Kubernetes configuration.

Ask the agent to check an existing Cilium installation. Then have it run the connectivity test and report failures without changing Cilium. The CLI reads cluster state when it checks status. When it runs the connectivity test, it creates test resources, so the test changes cluster state. Cilium’s getting started documentation covers installation and connectivity testing.

Install the CLI and connect to a cluster

Install the Cilium CLI from the official cilium-cli repository. Follow the release instructions to select the program file for your operating system and processor, download it, verify its checksum, and put the file on your PATH. The checksum is a value you use to check that the downloaded file matches the release. On Linux, Cilium’s quick installation guide gives these commands:

CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
CLI_ARCH=amd64
if [ "$(uname -m)" = "aarch64" ]; then CLI_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
sha256sum --check cilium-linux-${CLI_ARCH}.tar.gz.sha256sum
sudo tar xzvfC cilium-linux-${CLI_ARCH}.tar.gz /usr/local/bin
rm cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}

The same guide has a macOS version. Then confirm that your shell can run it:

cilium version

Your local Kubernetes configuration tells the CLI which cluster to contact and provides credentials. Cilium’s guide installs into the cluster that your current kubectl context points to. kubectl is the Kubernetes command-line tool. Check that context before an agent runs cluster commands:

kubectl config current-context

The CLI does not require a separate Cilium account or token. Kubernetes credentials determine which cluster it reaches and what actions those credentials permit. Keep credentials in the normal Kubernetes configuration or credential provider; do not paste them into an agent prompt.

Check health and run a connectivity test

For a cluster where Cilium is already installed, start with the status check:

cilium status --wait

The CLI waits for Cilium to report its status. Review the health of each reported component before proceeding. If Cilium is missing or unhealthy, stop and report that result rather than running a test that assumes a working installation.

To test workload connectivity, run:

cilium connectivity test

The command creates a namespace with test workloads and checks network paths between them. According to the cilium-cli README, some checks also connect from a test pod to an address outside the cluster. Its output reports the checks that pass or fail; the agent should summarize the failing paths and relevant error text rather than claim the cluster is healthy based only on the status command. Because the test creates resources and sends traffic through the cluster, get approval before running it against a shared or production cluster. Cilium’s guide also mentions that the test can fail to deploy when a pod hits a “too many open files” error on the host.

The CLI also supports installation commands, but cilium install changes cluster state. Keep that separate from a diagnostic task: only run it when the operator explicitly asks to install or change Cilium. The Cilium installation instructions show CLI use in a Kubernetes setup.

Give the agent a bounded task

A prompt for a cluster with permission to run the test could say:

Check the current Kubernetes context and run cilium status --wait. If Cilium reports healthy, run cilium connectivity test. Report the failing checks and their error messages. Do not install, upgrade, or reconfigure Cilium.

This gives the agent a concrete diagnostic job while separating observation from the test’s resource creation. If the agent needs deeper troubleshooting, Cilium also documents cilium-dbg commands for inspecting BPF maps, data structures that hold networking data Cilium uses on a node. cilium-dbg is a separate program. It talks to the Cilium agent on one node, and the troubleshooting guide runs it inside a Cilium pod with kubectl exec. Those commands require more care because they expose low-level state. See the BPF command reference.

Know what the checks do not prove

A passing connectivity test reports success for the paths that the test exercised. It does not establish that every application-specific network policy or production traffic path works. Ask the agent to say which checks passed or failed. Compare the tested paths with the affected workload’s real traffic. Identify the workload that sends it and the one that receives it, then note which policy applies.

Cilium also depends on cluster and kernel requirements. For example, the generic install needs a cluster that uses CNI, the plugin interface Kubernetes uses for pod networking. The nodes also need Linux kernel 5.10 or newer, or an equivalent like 4.18 on RHEL 8.10. If status or connectivity checks fail, the result alone does not identify the cause. The agent should report the observed error and cluster context, then ask before making changes.