kube-events

A CLI tool to view and summarize Kubernetes events with resource grouping and warning highlighting.

For detailed documentation, see the docs/ folder:

Usage | Configuration | Examples | Deployment | Development | Use Cases

Why kube-events?

	kubectl get events	kube-events
Output	Flat, unsorted list	Resource-grouped, warning-first display
Highlighting	None	Color-coded warnings with icons
Grouping	None	By resource, namespace, kind, or reason
Filtering	Limited (--field-selector)	Namespace, kind, name, type, reason
Time window	Not supported	--since 5m, 1h, 24h
Output formats	Text only	Color, plain, JSON, Markdown, table
Summary	Not supported	Event counts, resource counts, warning ratio
Watch mode	--watch (raw)	Filtered, formatted real-time stream
CI integration	Not designed for CI	JSON/Markdown output for pipelines

Quick Start

Install

# Homebrew
brew install somaz94/tap/kube-events

# Scoop (Windows)
scoop bucket add somaz94 https://github.com/somaz94/scoop-bucket
scoop install kube-events

# Krew (kubectl plugin)
kubectl krew index add somaz94 https://github.com/somaz94/krew-index
kubectl krew install somaz94/events2

# Binary (latest)
curl -sL https://github.com/somaz94/kube-events/releases/latest/download/kube-events_linux_amd64.tar.gz | tar xz
sudo mv kube-events /usr/local/bin/

# Binary (specific version)
curl -sL https://github.com/somaz94/kube-events/releases/download/v0.1.0/kube-events_0.1.0_linux_amd64.tar.gz | tar xz
sudo mv kube-events /usr/local/bin/

# From source
go install github.com/somaz94/kube-events/cmd@latest

Upgrade

# Homebrew
brew update && brew upgrade kube-events

# Scoop
scoop update kube-events

# Krew
kubectl krew upgrade events2

# From source
go install github.com/somaz94/kube-events/cmd@latest

Uninstall

# Homebrew
brew uninstall kube-events

# Scoop
scoop uninstall kube-events

# Krew
kubectl krew uninstall events2

# Manual
sudo rm /usr/local/bin/kube-events

Basic Usage

# Show all events from last 1 hour (default)
kube-events

# Show only Warning events
kube-events -t Warning

# Show events from specific namespace
kube-events -n production

# Show events for Pods only
kube-events -k Pod

# Show events from last 5 minutes
kube-events --since 5m

# Filter by resource name
kube-events -N api-server

# Filter by reason
kube-events -r BackOff,Unhealthy

# Group events by namespace
kube-events -g namespace

# Group events by kind
kube-events -g kind

# Group events by reason
kube-events -g reason

# All namespaces, JSON output
kube-events --all-namespaces -o json

# Summary only
kube-events -s

# Combine filters
kube-events -n prod -k Pod -t Warning --since 30m

# Watch events in real-time
kube-events -w -n production -t Warning

Example Output

Pod/app-1 [default] (3 events)
  ! BackOff            2m       Back-off restarting failed container
  ! Unhealthy          3m       Readiness probe failed
    Scheduled          5m       Successfully assigned...

Deployment/api [default] (1 event)
    ScalingUp          1m       Scaled up replica set

Summary: 4 events, 2 resources | Warning: 2 | Normal: 2

CLI Flags

Flag	Short	Default	Description
--kubeconfig		$KUBECONFIG, then ~/.kube/config	Path to kubeconfig
--context		current	Kubernetes context
--namespace	-n	all	Filter by namespace (repeatable)
--kind	-k	all	Filter by involved object kind
--name	-N	all	Filter by involved object name
--type	-t	all	Event type: Normal, Warning
--reason	-r	all	Event reason (e.g., BackOff)
--since		1h	Show events newer than duration
--output	-o	color	Format: color, plain, json, markdown, table
--group-by	-g	resource	Group by: resource, namespace, kind, reason (no effect with --watch)
--summary-only	-s	false	Show summary statistics only (no effect with --watch)
--all-namespaces		false	Show events from all namespaces
--watch	-w	false	Watch for new events in real-time

--group-by and --summary-only shape a completed set of events, so they do nothing in watch mode, where events arrive one at a time. Both flags are still accepted there, and an invalid --group-by value is rejected in either mode. Every other filter — including a repeated --namespace — applies to both.

Output Formats

Format	Flag	Use Case
Color	-o color	Terminal (default)
Plain	-o plain	Terminal without color support
JSON	-o json	Scripting, piping to jq
Markdown	-o markdown	GitHub PR comments, docs
Table	-o table	Structured terminal view

In watch mode each event prints on its own as it arrives. -o json emits one JSON object per event, -o color a colored line, and -o plain, -o markdown and -o table the same line without color.

Quick Demo

Run the demo against a local cluster:

make demo        # Deploy resources → show events → detect warnings
make demo-clean  # Remove demo resources from cluster

The demo deploys crash-looping and unpullable pods, so it refuses any context that is not a local cluster (kind, k3d, minikube, docker-desktop, orbstack, rancher-desktop). Set ALLOW_ANY_CONTEXT=1 to override.

Project Structure

• cmd/: CLI entry point and Cobra commands
• internal/client/: Kubernetes client wrapper (EventLister interface)
• internal/event/: event model, filtering, grouping, conversion, formatting
• internal/report/: output formatters
• scripts/: demo and utility scripts

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

Related projects

• kube-ctx: Switch contexts and namespaces per terminal, with production guards and a built-in fuzzy picker.
• kube-diff: Diff local manifests (plain YAML, Helm, Kustomize) against the live cluster.
• kube-events-action: Check cluster events in GitHub Actions and report warnings on the pull request.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.