Skip to content

README.md

Latest commit

 

History

History
353 lines (260 loc) · 11.1 KB

README.md

File metadata and controls

353 lines (260 loc) · 11.1 KB
██╗  ██╗██████╗ ███╗   ███╗
██║ ██╔╝██╔══██╗████╗ ████║
█████╔╝ ██║  ██║██╔████╔██║
██╔═██╗ ██║  ██║██║╚██╔╝██║
██║  ██╗██████╔╝██║ ╚═╝ ██║
╚═╝  ╚═╝╚═════╝ ╚═╝     ╚═╝

KDM — Kubernetes + Docker Monitoring CLI

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

npm version npm downloads License All Contributors GitHub stars Node TypeScript PRs Welcome

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

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

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):

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