cluster-cli

A fast, interactive terminal UI for monitoring Kubernetes cluster health in real-time

curl -fsSL https://raw.githubusercontent.com/sharat/cluster-cli/main/install.sh | bash

Download Documentation

Features

Real-Time Dashboard

Unified view of nodes, incidents, and pods with live health scoring (0-100, A-F grading).

Incident Queue

Ranked warning and failure signals from nodes, pods, and events. Press Enter to drill down.

Resource Monitoring

CPU/memory usage with sparklines, pressure indicators, and node pool filtering.

Pod Management

Multi-container and native sidecar support, log streaming, search, export, and crash loop detection.

Pod Diagnosis

Explains why a pod is unhealthy, with the likely cause and the next read-only kubectl command to run.

Right-Sizing

Compares requests with peak usage per workload, flags over- and under-provisioning, and suggests requests.

Incident Timeline

Chronological view of events with precursor detection and time-based correlation.

AI Agent Integration

MCP server for Claude Desktop, Cursor, VS Code. Natural language cluster queries.

In Action

Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/sharat/cluster-cli/main/install.sh | bash

Build from Source

git clone https://github.com/sharat/cluster-cli.git
cd cluster-cli
cargo build --release

Requires Rust 1.85+ and kubectl configured with cluster access.

See full installation guide for all platforms and methods.

Key Bindings

cluster-cli is fully keyboard-driven for fast navigation.

Navigation

q Ctrl+C

Quit application

1 2 3

Focus Nodes / Incidents / Pods

Tab

Cycle between panels

↑ ↓ j k

Move cursor

Enter

View details or drill into incident

Actions

t

Open incident timeline

T

Timeline filtered to incident

?

Help for every key and marker

u

Open right-sizing view

w

Toggle workload popup

n

Open namespace selector

s

Cycle pod sort modes

E

Export pods to CSV

r

Manual refresh

R

Change refresh interval

Pod Detail View

f

Toggle log follow mode

c

Cycle containers

p

Toggle previous logs

/

Search logs

t

Toggle timestamps

w

Toggle line wrapping

Timeline View

s

Toggle sort order

f

Cycle kind filter

F

Cycle severity filter

c

Clear all filters

See complete UI guide for all keyboard shortcuts.

Headless Mode

Use cluster-cli in scripts, CI/CD pipelines, and automation with stable JSON output.

Cluster Health

cluster status --json
cluster status --json --verbose  # Include detailed findings

List Incidents

cluster incidents --json
cluster incidents --json --verbose  # All incidents (not just top 10)

List Pods and Nodes

cluster pods --json --verbose  # Include container details
cluster nodes --json --verbose  # Include node conditions

Stream Logs

cluster logs <pod-name> --tail 100
cluster logs <pod-name> -c <container> --follow --timestamps

CI/CD Health Check Example

#!/bin/bash
HEALTH=$(cluster status --json -n production | jq -r '.data.score')
if [ "$HEALTH" -ge 80 ]; then
  echo "✓ Cluster health: $HEALTH (OK)"
  exit 0
else
  echo "✗ Cluster health: $HEALTH (CRITICAL)"
  exit 1
fi

All JSON responses include version field (current: 1.0.0) for schema versioning.

See headless mode documentation for complete JSON API reference.

AI Agent Integration (MCP Server)

Connect cluster-cli to AI agents like Claude Desktop, Cursor, and VS Code using the Model Context Protocol (MCP).

Starting the MCP Server

cluster mcp

Cursor Configuration

Add to .cursor/mcp_config.json:

{
  "mcpServers": {
    "cluster-cli": {
      "command": "cluster",
      "args": ["mcp"]
    }
  }
}

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "cluster-cli": {
      "command": "/Users/username/.local/bin/cluster",
      "args": ["mcp"]
    }
  }
}

VS Code Configuration

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "cluster-cli": {
      "command": "cluster",
      "args": ["mcp"]
    }
  }
}

Available Tools

get_cluster_health - Health score, grade, critical resource counts
list_incidents - Ranked incidents by severity
list_pods - Pod status, resource usage, readiness
describe_pod - Detailed pod information
explain_pod - Diagnosis findings with severity, likely cause, and next kubectl command
get_logs - Fetch pod logs
list_nodes - Node metrics and conditions
list_contexts - Available kubectl contexts

Example Queries

"What's the health of my production cluster?"
"Show me all crash looping pods"
"Explain why the api pod is failing"
"Which pods have high memory usage?"

Security Note: The MCP server is read-only. No mutation operations are exposed.

See MCP server documentation for complete setup guide and tool reference.