KDM — Kubernetes + Docker Monitoring CLI

██╗  ██╗██████╗ ███╗   ███╗
██║ ██╔╝██╔══██╗████╗ ████║
█████╔╝ ██║  ██║██╔████╔██║
██╔═██╗ ██║  ██║██║╚██╔╝██║
██║  ██╗██████╔╝██║ ╚═╝ ██║
╚═╝  ╚═╝╚═════╝ ╚═╝     ╚═╝

KDM — Kubernetes + Docker Monitoring CLI

Monitor Docker containers and Kubernetes pods from a single terminal interface.

Overview

KDM (Kubernetes Docker Monitor) is a lightweight CLI tool that automatically detects and monitors running Docker containers and Kubernetes pods. It provides real-time health status, live dashboards, log fetching, and alert notifications — all from your terminal.

Unlike tools that focus on a single runtime (k9s for Kubernetes or lazydocker for Docker), KDM gives you a unified view of both worlds.

Features

Feature	Description
Auto-Detection	Automatically discovers Docker containers and Kubernetes pods in your environment
Unified Runner View	Combined table of Docker and Kubernetes workloads in a single command
Health Monitoring	Color-coded health status with watch mode for continuous polling
Live Dashboard	Real-time Ink-based TUI that refreshes every 3 seconds
Log Fetching	Retrieve logs from containers or pods with automatic Docker-to-Kubernetes fallback
Alert Notifications	Send alerts via Discord webhook or email SMTP on failures
Minikube Support	Check Minikube profile status and connectivity
AI Diagnostics	Scan cluster workload configuration errors (`kdm analyze`) with AI explanations (`--explain`)
AI Providers	Multi-backend credentials (`kdm auth`) supporting OpenAI, Anthropic, Gemini, WatsonX, Ollama, etc.
Local Cache	Cache system (`kdm cache`) to save AI explanation API tokens and reduce network latency
Dynamic Filters	Customize default active analyzers list (`kdm filters`)
Custom Analyzers	Run scripts or webhooks (`kdm custom-analyzer`) to analyze CustomResourceDefinitions (e.g. KEDA, Kyverno)
MCP & HTTP Server	Run KDM as a REST API or Model Context Protocol (MCP) server (`kdm serve`) for agent integrations

Installation

Global Install

npm install -g kdm-cli

Run Directly

npx kdm-cli

Requirements:

Node.js >= 18
Docker daemon (for container features)
Kubernetes cluster or Minikube (for pod features)

Quick Start

Once installed, run KDM with no arguments to display the welcome banner, connection status, and available commands:

kdm

You should see output similar to:

Docker:      ✔ CONNECTED  (3 running)
Kubernetes:  ✔ CONNECTED  (5 running)
Minikube:    ✔ RUNNING

Usage

Show Workloads

Display running containers, pods, or both in a formatted table.

kdm show runners       # Combined view: pods + containers
kdm show pods          # Kubernetes pods only
kdm show containers    # Docker containers only
kdm show minikube      # Minikube profile status

Health Status

Check and monitor the health of your workloads with color-coded output.

kdm health all          # Both pods and containers
kdm health pods         # Pods only
kdm health containers   # Containers only
kdm health all -w       # Watch mode: auto-refresh every 5 seconds
kdm health pods -w -i 2  # Watch mode: refresh every 2 seconds

Live Dashboard

Monitor all workloads in real time with an interactive terminal dashboard.

kdm watch               # Opens Ink-based live dashboard (Ctrl+C to exit)

Log Fetching

Retrieve the last 100 lines of logs from a container or pod. Docker is tried first; Kubernetes is used as a fallback.

kdm logs <name>         # Container name/ID prefix or pod name

Diagnostics & AI Analysis

Scan your Kubernetes cluster for common workload issues (mismatched replicas, crashing containers, invalid Gateway routes, etc.) and get AI-powered troubleshooting advice in plain English.

kdm analyze                          # Run cluster diagnostics and output color-coded report
kdm analyze -n default               # Analyze resources in the 'default' namespace only
kdm analyze --explain                # Run diagnostics and fetch AI explanation
kdm analyze --explain --backend ollama # Force specific active AI backend provider
kdm analyze --explain --anonymize    # Anonymize resource names in prompt to protect sensitive data
kdm analyze --output json            # Output results in structured JSON format

AI Providers (Auth)

Manage AI backend settings and credentials. KDM supports 10+ AI providers including OpenAI, Anthropic, Gemini, Vertex, OCI GenAI, HuggingFace, Groq, WatsonX, and Ollama.

kdm auth add -b openai -m gpt-4o -p <key> # Configure OpenAI gpt-4o with API key
kdm auth add -b ollama -m llama3.1       # Configure local Ollama llama3.1
kdm auth list                            # List configured AI backends and settings
kdm auth default ollama                  # Set default active AI backend
kdm auth remove openai                   # Remove backend credentials from config
kdm auth update ollama -t 0.2            # Update settings (e.g. set temperature to 0.2)

Local Explanation Cache

KDM caches AI explanations locally to save API tokens and reduce network latency.

kdm cache list              # List all cached AI explanation keys
kdm cache get <key>         # Retrieve cached text for a key
kdm cache remove <key>      # Delete a specific cached entry
kdm cache purge             # Clear all cached AI explanations

Analyzer Filters

By default, KDM runs all core resource analyzers. You can customize which analyzers are active.

kdm filters list            # List active filters and available inactive ones
kdm filters add Ingress     # Add Ingress analyzer to active default filters list
kdm filters remove Ingress  # Remove analyzer from active list (falls back to defaults)

Custom Analyzers

Register custom scripts/commands or HTTP webhooks to analyze arbitrary custom resources (CRDs) like Kyverno, KEDA, and Prometheus.

kdm custom-analyzer add keda --command "kubectl get scaledobjects -A -o json" # Add custom analyzer command
kdm custom-analyzer add my-webhook --url "https://api.my-org.internal/check"  # Add custom HTTP analyzer
kdm custom-analyzer list                                                     # List all custom analyzers
kdm custom-analyzer remove keda                                              # Remove custom analyzer

HTTP & MCP Server

Run KDM in server mode. KDM can run as a standard REST API or as a Model Context Protocol (MCP) server, enabling seamless integration with AI agents (like Claude Desktop).

kdm serve --port 8080       # Start KDM HTTP REST server on port 8080
kdm serve --mcp             # Start KDM JSON-RPC MCP server over stdio

Configuration

Set up notification services and manage configuration interactively.

kdm config setup        # Interactive setup (Discord webhook / Email SMTP)
kdm config list         # Show current configuration
kdm config set <key> <value>   # Set a specific value
kdm config clear        # Clear all configuration

Help

kdm --help              # Show all commands and options
kdm <command> --help    # Show help for a specific command

Configuration

KDM stores configuration locally using the conf package.

Config File Location

OS	Path
macOS	`~/Library/Application Support/kdm-cli`
Linux	`~/.config/kdm-cli`
Windows	`%APPDATA%\kdm-cli`

Environment Variables

Variable	Description
`KDM_SMTP_PASSWORD`	SMTP password (overrides stored config for security)

Notification Services

Set up alerts to be notified when containers restart or pods enter failure states (CrashLoopBackOff, ImagePullBackOff, Failed, etc.).

kdm config setup

Supports:

Discord — via webhook URL
Email (SMTP) — via SMTP credentials

Alerts are rate-limited with a configurable cooldown (default: 300 seconds).

kdm config set alert_cooldown 600   # 10 minutes between alerts

Alert Monitoring

KDM automatically checks for failure conditions and sends notifications when configured:

Condition	Severity	Source
Container restarting	Warning	Docker
Container non-zero exit	Critical	Docker
Pod phase is `Failed`	Critical	Kubernetes
`CrashLoopBackOff`	Critical	Kubernetes
`ImagePullBackOff`	Critical	Kubernetes
`CreateContainerConfigError`	Critical	Kubernetes

Technical Stack

Technology	Purpose
TypeScript + Node.js	Runtime and language
Commander.js	CLI framework and argument parsing
dockerode	Docker daemon API client
@kubernetes/client-node	Kubernetes API client
Ink + React	Interactive terminal UI (watch mode)
chalk	Terminal string coloring
cli-table3	Table rendering
conf	Persistent configuration
nodemailer	Email alerts
tsup	High-performance bundler

Documentation

For detailed command reference, see:

Contributing

We welcome contributions of all kinds — bug reports, feature suggestions, and pull requests.

Please read our Contribution Guide and Code of Conduct before getting started.

Development Setup

git clone https://github.com/KDM-cli/kdm-cli.git
cd kdm-cli
npm install
npm run dev        # Watch mode for development
npm test           # Run test suite
npm run build      # Production build

Contributors

Thanks goes to these wonderful people (emoji key):

_{Yuvraj Sarathe}
🚇 📖

_{Utkarsh Patrikar}
💻 🚇 🚧

_blut-agent
✨ 📖 🔐

_{Rishiraj Pathak}
💻

_fizyxbt
✨

This project follows the All Contributors specification. Contributions of any kind are welcome!

License

GNU Affero General Public License v3.0 — See LICENSE for full terms.

Maintained by KDM-cli · Built with ❤️ by the community

Name		Name	Last commit message	Last commit date
Latest commit History 287 Commits
.github		.github
bin		bin
docs		docs
src		src
.all-contributorsrc		.all-contributorsrc
.coderabbit.yaml		.coderabbit.yaml
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
coding_style.md		coding_style.md
commands.md		commands.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

KDM — Kubernetes + Docker Monitoring CLI

Overview

Features

Installation

Global Install

Run Directly

Quick Start

Usage

Show Workloads

Health Status

Live Dashboard

Log Fetching

Diagnostics & AI Analysis

AI Providers (Auth)

Local Explanation Cache

Analyzer Filters

Custom Analyzers

HTTP & MCP Server

Configuration

Help

Configuration

Config File Location

Environment Variables

Notification Services

Alert Monitoring

Technical Stack

Documentation

Contributing

Development Setup

Contributors

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages