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
Multi-Agent SRE	Autonomous multi-agent council with local Ollama models, live Ink TUI, and closed-loop remediation (`kdm analyze --multi-agent`)
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

Install in a Project

npm install kdm-cli
npx kdm

npm install kdm-cli adds the kdm executable to the project at ./node_modules/.bin/kdm; it does not add it to your system PATH. Use npx kdm from that project, or choose the global installation above to run kdm from any directory.

Requirements:

Node.js >= 20
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 --multi-agent            # Run autonomous multi-agent SRE council with local Ollama models
kdm analyze deployment/checkout-api --multi-agent # Target specific workload for multi-agent root-cause triaging
kdm analyze --explain                # Run diagnostics and fetch single-prompt 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

Multi-Agent SRE Architecture (`--multi-agent`)

KDM v4.0.0 features an autonomous Multi-Agent SRE Council running 100% locally via Ollama. Instead of relying on a single static LLM prompt, KDM coordinates domain-specialist agents in parallel to collect evidence, evaluate deterministic failure rules, correlate observations, formulate root-cause hypotheses, and safely apply verified remediations.

Complete Lifecycle Flow

flowchart TD
    CLI["CLI Command: kdm analyze --multi-agent"] --> Collect["1. Evidence Collector\n(Pods, Events, Logs, Node Metrics)"]
    Collect --> RuleEngine{"2. Deterministic Rule Engine\n(&lt; 5ms fast-path check)"}
    RuleEngine -- Conclusive Match --> Instant["Instant Diagnosis\n(Zero LLM Overhead)"]
    RuleEngine -- Complex Failure --> Council["Specialist Agent Council\n(Parallel Execution)"]
    
    subgraph Specialists["2. Specialist Council"]
        Council --> Runtime["Runtime & Log Agent\n(Exit codes, panic traces, crashes)"]
        Council --> Config["Config & Dependency Agent\n(Limits, probes, secrets, ConfigMaps)"]
        Council --> Resource["Cluster & Resource Agent\n(Node memory/disk pressure, capacity)"]
    end
    
    Runtime --> Correlate["3. Correlate & Validate\n(Lead SRE Synthesizer)"]
    Config --> Correlate
    Resource --> Correlate
    
    Correlate --> Validator{"Cross-Agent Validator\n(Contradiction Check)"}
    Validator -- Validated --> Consensus["4. Consensus Diagnosis\n(Root Cause + High Confidence + Solution)"]
    Instant --> Consensus
    
    Consensus --> TUI["Live Ink TUI Dashboard"]
    TUI --> SafetyGate{"5. Remediation Safety Gate [y/N]\n(Destructive Command Policy)"}
    SafetyGate -- "Confirmed [y]" --> Executor["Parameterized Executor\n(Stdout/Stderr + Audit Trail)"]
    SafetyGate -- "Aborted [n]" --> Aborted["Remediation Aborted Safely"]
    
    Executor --> Verify["6. Post-Fix Verification\n(Pod Ready 1/1, Rollout, Zero Restarts)"]
    Verify --> Done["Remediation Successful!"]

Expected Product Flow

$ kdm analyze deployment/checkout-api --multi-agent

1. COLLECT
   ✓ Kubernetes evidence collected (14 items)

2. INVESTIGATE
   ✓ Runtime Agent (detected exit code 137)
   ✓ Config Agent (checked limits and probes)
   ✓ Resource Agent (checked node memory pressure)

3. CORRELATE & VALIDATE
   ✓ Lead Investigator formulated root-cause hypothesis
   ✓ Validator confirmed: no contradictions

4. DIAGNOSIS
   Root Cause: Container exceeded 256Mi memory limit under peak load
   Confidence: HIGH · 96%

5. REMEDIATION
   Action: Increase memory limit (256Mi → 512Mi)
   Command: kubectl set resources deployment checkout-api --limits=memory=512Mi
   Apply? [y/N]: y

6. VERIFY
   ✓ Deployment rolled out
   ✓ Pod Ready: 1/1
   ✓ No new restarts detected

Remediation successful.

CLI Flags & Configuration Options

Option	Method	Description
`--multi-agent`	CLI Flag	Enables multi-agent council for `kdm analyze`
`--model <model>`	CLI Flag	Selects local Ollama model (e.g. `llama3.1`, `qwen2.5-coder`)
`multi_agent: true`	Config Store	Persist opt-in via `kdm config set multi_agent true`
`KDM_MULTI_AGENT=true`	Environment	Set environment variable for CI/CD or non-interactive automation

Resilient 4-Step Graceful Degradation Ladder

KDM is engineered for mission-critical reliability. If local Ollama, Python, or cloud backends fail or timeout, KDM automatically falls back down the degradation ladder without throwing unhandled exceptions:

Step 1: Multi-Agent Council — Full parallel multi-agent triage with local Ollama models.
Step 2: Deterministic Rule Engine — Evaluates rules in < 5ms with zero LLM overhead for canonical failure signatures (OOMKilled, CrashLoopBackOff, ImagePullBackOff, ProbeFailure, Scheduling).
Step 3: Legacy AI Client — Single-prompt cloud provider completions (OpenAI, Claude, Azure).
Step 4: Raw Kubernetes Summary — Structured, formatted workload error diagnostics with zero AI required.

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 using the interactive checklist dashboard or CLI subcommands:

kdm filters                 # Open interactive checklist dashboard with instant persistence
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                                                        # Interactive rule manager (TTY required)
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
Python 3 + Ollama	Multi-agent SRE council and local LLM execution
Ink + React	Interactive terminal UI (watch mode & council dashboard)
chalk	Terminal string coloring
cli-table3	Table rendering
conf	Persistent configuration
nodemailer	Email alerts
tsup	High-performance bundler
Vitest	Unit and end-to-end integration test runner

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 🛡️	_{Akansha Gore} 💻	_{Kunal Khare} 💻
_{Suprovo Mallick (DYNO)} 💻	_Luochenchen 💻 ⚠️	_{Channa Karawita} 💻 ⚠️

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
.github		.github
.husky		.husky
.jules		.jules
agents		agents
bin		bin
config		config
docs		docs
src		src
.all-contributorsrc		.all-contributorsrc
.coderabbit.yaml		.coderabbit.yaml
.gitignore		.gitignore
.lintstagedrc.js		.lintstagedrc.js
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
kdm_multi_agent_detailed_implementation_plan (1).md		kdm_multi_agent_detailed_implementation_plan (1).md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

KDM — Kubernetes + Docker Monitoring CLI

Overview

Features

Installation

Global Install

Run Directly

Install in a Project

Quick Start

Usage

Show Workloads

Health Status

Live Dashboard

Log Fetching

Diagnostics & AI Analysis

Multi-Agent SRE Architecture (--multi-agent)

Complete Lifecycle Flow

Expected Product Flow

CLI Flags & Configuration Options

Resilient 4-Step Graceful Degradation Ladder

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

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Multi-Agent SRE Architecture (`--multi-agent`)