diff --git a/README.md b/README.md index efb7e03..ad7fc25 100644 --- a/README.md +++ b/README.md @@ -1,81 +1,353 @@ +
+
+██╗  ██╗██████╗ ███╗   ███╗
+██║ ██╔╝██╔══██╗████╗ ████║
+█████╔╝ ██║  ██║██╔████╔██║
+██╔═██╗ ██║  ██║██║╚██╔╝██║
+██║  ██╗██████╔╝██║ ╚═╝ ██║
+╚═╝  ╚═╝╚═════╝ ╚═╝     ╚═╝
+
+
+ +
+ # KDM — Kubernetes + Docker Monitoring CLI +**Monitor Docker containers and Kubernetes pods from a single terminal interface.** + +[![npm version](https://img.shields.io/npm/v/kdm-cli?style=flat-square&logo=npm&color=cb3837)](https://www.npmjs.com/package/kdm-cli) +[![npm downloads](https://img.shields.io/npm/dm/kdm-cli?style=flat-square&logo=npm&color=cb3837)](https://www.npmjs.com/package/kdm-cli) +[![License](https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square)](LICENSE) [![All Contributors](https://img.shields.io/github/all-contributors/KDM-cli/kdm-cli?color=ee8449&style=flat-square)](#contributors) +[![GitHub stars](https://img.shields.io/github/stars/KDM-cli/kdm-cli?style=flat-square&logo=github)](https://github.com/KDM-cli/kdm-cli) +[![Node](https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js)](https://nodejs.org) +[![TypeScript](https://img.shields.io/badge/TypeScript-7-3178C6?style=flat-square&logo=typescript)](https://www.typescriptlang.org) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](CONTRIBUTING.md) + +
+ +--- + +## Overview -KDM (Kubernetes Docker Monitor) is a lightweight, terminal-based monitoring CLI tool that automatically detects and monitors running Docker containers and Kubernetes pods. It provides real-time resource usage, health status, and unified views of your runners. +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. + +[k9s]: https://k9scli.io/ +[lazydocker]: https://github.com/jesseduffield/lazydocker + +--- ## Features -- **Auto-Detection**: Automatically detects Docker containers and Kubernetes pods in your local environment. -- **Unified Runner View**: Combined view of Docker and Kubernetes workloads. -- **Health Monitoring**: Advanced health status for both containers and pods (Ready, Unhealthy, CrashLoopBackOff, etc.). -- **Live Watch Mode**: Real-time monitoring of resource usage. -- **Logs**: Easily fetch logs from both Docker and Kubernetes sources. -- **Beautiful UI**: Interactive terminal UI powered by Ink and Commander. +| 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 -Install kdm-cli via npm: +
+ +### Global Install + ```bash npm install -g kdm-cli ``` -Run directly with npx: +### Run Directly ```bash npx kdm-cli ``` +
+ +**Requirements:** + +- [Node.js](https://nodejs.org) >= 18 +- Docker daemon (for container features) +- Kubernetes cluster or [Minikube](https://minikube.sigs.k8s.io) (for pod features) + +--- + +## Quick Start + +Once installed, run KDM with no arguments to display the welcome banner, connection status, and available commands: + +```bash +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. + ```bash -kdm show runners # Show all running pods + containers -kdm show pods # Show kubernetes pods -kdm show containers # Show docker containers -kdm show minikube # Show minikube status +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. + ```bash -kdm health pods # Show health status for pods -kdm health containers # Show health status for containers +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 ``` -### Monitoring & Logs +### Live Dashboard + +Monitor all workloads in real time with an interactive terminal dashboard. ```bash -kdm watch # Live monitoring mode -kdm logs # Show logs for a container or pod +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. + +```bash +kdm logs # Container name/ID prefix or pod name +``` + +### Configuration + +Set up notification services and manage configuration interactively. + +```bash +kdm config setup # Interactive setup (Discord webhook / Email SMTP) +kdm config list # Show current configuration +kdm config set # Set a specific value +kdm config clear # Clear all configuration ``` ### Help ```bash -kdm --help +kdm --help # Show all commands and options +kdm --help # Show help for a specific command ``` -## Technical Details +--- + +## Configuration + +KDM stores configuration locally using the [`conf`](https://github.com/sindresorhus/conf) package. + +### Config File Location + +| OS | Path | +|---------|------| +| macOS | `~/Library/Application Support/kdm-cli` | +| Linux | `~/.config/kdm-cli` | +| Windows | `%APPDATA%\kdm-cli` | -KDM is built with: -- **TypeScript** & **Node.js** -- **Commander.js** for CLI orchestration -- **dockerode** for Docker integration -- **@kubernetes/client-node** for Kubernetes integration -- **Ink** for terminal UI -- **tsup** for high-performance bundling +### 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.). + +```bash +kdm config setup +``` + +Supports: + +- **Discord** — via webhook URL +- **Email (SMTP)** — via SMTP credentials + +Alerts are rate-limited with a configurable cooldown (default: 300 seconds). + +```bash +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 | + +[TypeScript]: https://www.typescriptlang.org +[Node.js]: https://nodejs.org +[Commander.js]: https://github.com/tj/commander.js +[dockerode]: https://github.com/apocas/dockerode +[@kubernetes/client-node]: https://github.com/kubernetes-client/javascript +[Ink]: https://github.com/vadimdemedes/ink +[React]: https://react.dev +[chalk]: https://github.com/chalk/chalk +[cli-table3]: https://github.com/cli-table/cli-table3 +[conf]: https://github.com/sindresorhus/conf +[nodemailer]: https://nodemailer.com +[tsup]: https://tsup.egoist.dev + +--- + +## Documentation + +For detailed command reference, see: + +- [Contribution Guide](CONTRIBUTING.md) +- [Code of Conduct](CODE_OF_CONDUCT.md) +- [Security Policy](SECURITY.md) +- [Changelog](docs/README.md) + +--- + +## Contributing + +We welcome contributions of all kinds — bug reports, feature suggestions, and pull requests. + +Please read our [Contribution Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before getting started. + +### Development Setup + +```bash +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](https://allcontributors.org/docs/en/emoji-key)): + + + +This project follows the [All Contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome! + +--- ## License -[GNU AGPL 3.0](https://github.com/KDM-cli/kdm-cli?tab=AGPL-3.0-1-ov-file#) + +[GNU Affero General Public License v3.0](LICENSE) — See [LICENSE](LICENSE) for full terms. + +
+ +**Maintained by [KDM-cli](https://github.com/KDM-cli)** · Built with ❤️ by the community + +