kloudlens-cli (klctl)

klctl is the operator CLI for KloudLens, the eBPF-based runtime visibility platform for Kubernetes. It exposes every kloudlens RPC as a verb and adds offline tooling for the policy lifecycle:

• kloudlens probe — klctl status, klctl caps, klctl diag (LSM, helpers, BTF, cgroup v2, hook availability)
• Streaming — klctl stream {intents,deviations,raw,graph,session,snapshot}, klctl top
• Durable subscribe — klctl get events --follow with cursor resume
• Baseline lifecycle — klctl baseline {snapshot,promote,activate,deactivate,reset,merge,drift,status}
• BehaviorContract lifecycle — klctl contract {from-profile,simulate,export,import} with adapters for seccomp, AppArmor, KubeArmor, Cilium, Kyverno, OPA/Rego, NetworkPolicy, PodSecurity
• Gap analysis — klctl gap analyze
• Runtime config — klctl config get|set for kloudlens's runtime-tunable knobs

KloudLens itself lives at boanlab/KloudLens. This repo builds only the CLI.

---

Requirements

• Go 1.24+ (build only)
• A running KloudLens on the network for runtime commands (klctl stream, klctl caps, …).

Docker is only needed to build the container image.

---

Install

From a release

curl -L -o klctl https://github.com/boanlab/kloudlens-cli/releases/latest/download/klctl-linux-amd64
chmod +x klctl
./klctl --help

go install

go install github.com/boanlab/kloudlens-cli@latest

From source

git clone https://github.com/boanlab/kloudlens-cli.git
cd kloudlens-cli
make
./bin/klctl --help

Container image

docker run --rm --network=host boanlab/kloudlens-cli:<tag> status --agent=127.0.0.1:8180

---

Usage

# Liveness + capability probe (admin RPC defaults to :8180)
klctl status --agent=127.0.0.1:8180
klctl caps  --agent=127.0.0.1:8180

# Streaming (streaming RPCs default to :8181)
klctl stream intents                # live semantic intent feed
klctl stream deviations             # only events that diverge from the active baseline
klctl get events --follow           # durable subscribe with cursor resume
klctl top                           # live top-talkers

# BehaviorContract lifecycle
klctl baseline snapshot -o prof.json
klctl contract from-profile --min-confidence=0.8 -o contract.yaml prof.json
klctl contract simulate --since=7d --wal-dir=/var/lib/kloudlens/wal contract.yaml
klctl contract export --adapter=seccomp -o seccomp/frontend.json contract.yaml
klctl gap analyze --observed prof.json --policy contract.yaml

A full walk-through is in getting-started/README.md. Copy-paste recipes for common detection + enforcement patterns are in getting-started/use-cases.md.

---

Documentation

Doc	Purpose
getting-started/README.md	10-minute tour of every klctl verb
getting-started/use-cases.md	Detection + enforcement recipes
getting-started/docker-mode.md	Using klctl against host-binary / docker-compose kloudlens
getting-started/integrations.md	Plug CLI output into Loki / Elasticsearch / OTel / Slack / PagerDuty
getting-started/troubleshooting.md	CLI-facing diagnostics
contribution/README.md	Dev environment setup + PR process
contribution/contracts-git-diff-prs.md	BehaviorContract PR review workflow

For KloudLens-side operational docs (DaemonSet install, eBPF attach, ringbuf tuning, /metrics), see the KloudLens repo.

---

Development

The CLI imports the kloudlens module (github.com/boanlab/kloudlens) as a regular tagged Go-module dependency. The gRPC wire format (api/pb) lives inside that module, so this repo is self-contained — clone it alone and make builds:

git clone https://github.com/boanlab/kloudlens-cli.git
cd kloudlens-cli
make            # bin/klctl
make verify     # gofmt + vet + golangci-lint + gosec + test
make build-image

To pin a different kloudlens version, bump the github.com/boanlab/kloudlens line in go.mod and run go mod tidy.

See contribution/README.md for the full dev loop and PR requirements.

License

Apache License 2.0 — see LICENSE.

---

Copyright 2026 BoanLab @ Dankook University