kernstat

Lightweight Linux system statistics CLI built directly on /proc and /sys interfaces. kernstat reports CPU, memory, disk, network, and per-process metrics without external monitoring daemons or subprocess wrappers, with both human-readable and JSON output modes for scripting and automation. It also includes a live updating terminal dashboard.

Basic usage

Show CPU usage:

kernstat cpu

CPU Usage:    12.4%

Show memory statistics:

kernstat memory

Memory
  Total:      7.62 GB
  Used:       4.11 GB
  Available:  3.51 GB
  Usage:      53.94%

Show full system report:

kernstat report

CPU Usage:    10.8%

Memory
  Total:      7.62 GB
  Used:       4.09 GB
  Available:  3.53 GB
  Usage:      53.67%

Disk
  Total:      238.47 GB
  Used:       121.84 GB
  Free:       116.63 GB
  Usage:      51.09%
  Reads:      0.0/sec
  Writes:     2.0/sec

Network (wlp1s0)
  Download:   4.82 KB/s
  Upload:     0.31 KB/s

Show statistics for a specific process:

kernstat proc 1

Process 1
  Name:       systemd
  State:      S (sleeping)
  Threads:    1
  Memory:     14.96 MB
  CPU Usage:  0.0%
  Command:    /usr/lib/systemd/systemd --switched-root --system

Run the live dashboard:

kernstat dashboard

          kernstat live dashboard
┌──────────────────┬──────────────────────────────┐
│ Metric           │ Value                        │
├──────────────────┼──────────────────────────────┤
│ CPU              │ 23.4%                        │
│ Memory           │ 4.85 / 6.94 GB (69.8%)       │
│ Disk             │ 23.08 / 34.42 GB (67.0%)     │
│ Disk IO          │ 0.00 reads/s | 2.00 writes/s │
│ Network (wlp1s0) │ ↓ 4.82 KB/s | ↑ 0.31 KB/s    │ 
└──────────────────┴──────────────────────────────┘
    Updated 14:52:31 • Press Ctrl+C to quit

The dashboard refreshes continuously until interrupted with Ctrl+C. Set the refresh interval with --interval, for example kernstat dashboard --interval 2.

JSON output for scripting:

kernstat report --format json

{
  "cpu": {
    "cpu_percent": 10.8
  },
  "memory": {
    "total_gb": 7.62,
    "available_gb": 3.53,
    "used_gb": 4.09,
    "percent": 53.67
  },
  "disk": {
    "io": {
      "reads_per_sec": 0.0,
      "writes_per_sec": 2.0,
      "read_bytes_per_sec": 0.0,
      "write_bytes_per_sec": 1024.0
    },
    "space": {
      "total_gb": 238.47,
      "free_gb": 116.63,
      "used_gb": 121.84,
      "percent": 51.09
    }
  },
  "network": {
    "rx_bytes_per_sec": 4935.68,
    "tx_bytes_per_sec": 317.44,
    "rx_kb_per_sec": 4.82,
    "tx_kb_per_sec": 0.31
  }
}

Installation

Install from PyPI:

pip install kernstat

Run the CLI:

kernstat report

For development:

git clone https://github.com/WaiHlyanMinThein17/kernstat.git
cd kernstat
uv sync

Commands

All metric commands accept --format json for structured output. The dashboard accepts --interval to set the refresh rate in seconds.

Configuration

kernstat reads optional configuration from ~/.config/kernstat/config.toml, or from $XDG_CONFIG_HOME/kernstat/config.toml if that environment variable is set.

[kernstat]
interval = 0.5
format = "json"

Available settings:

Command line flags always override configuration file values. If no config file exists, built-in defaults are used. See config.example.toml for a documented example you can copy to get started.

Design notes

Direct /proc and /sys parsing

kernstat reads Linux kernel interfaces directly instead of shelling out to tools like top, free, or iostat. This avoids subprocess overhead, removes dependencies on external utilities, and keeps the implementation portable across minimal Linux environments and containers. Parsing kernel interfaces directly also provides predictable structured data and exposes how Linux system metrics are actually represented internally.

Sampling with two readings

CPU and network usage are calculated from differences between two cumulative kernel readings over a short interval. Linux counters in /proc continuously increase since boot, so a single reading cannot represent utilization or throughput by itself. Taking two samples and calculating the delta produces accurate rates such as CPU utilization percentages and network transfer speeds.

JSON output for automation

All commands support structured JSON output in addition to human-readable terminal output. This allows kernstat to integrate cleanly with shell scripts, monitoring pipelines, CI systems, and other automation tooling. The JSON mode provides stable machine-readable output while preserving a concise CLI experience for interactive use.

Contributing

Contributions, bug reports, and suggestions are welcome. See CONTRIBUTING.md for development setup and guidelines.

Run tests:

uv run pytest

Run linting:

uvx ruff check src tests

License

kernstat is released under the GPL-3.0 license.