kernstat 0.1.0

Linux kernel statistics CLI tool

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

Command	Description
kernstat cpu	CPU usage percentage
kernstat memory	Memory usage statistics
kernstat disk	Disk I/O and space statistics
kernstat network	Network I/O statistics
kernstat proc <pid>	Statistics for a specific process
kernstat report	Full system report
kernstat dashboard	Live updating system metrics dashboard

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:

Setting	Type	Default	Description
interval	float	0.1	Sampling interval in seconds for rate calculations
format	string	text	Default output format, either text or json

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.