Documentation

Complete guide to installing and using minit

Getting Started

minit is a lightweight, real-time system monitoring CLI tool designed for developers. It provides beautiful live dashboards to monitor CPU, memory, disk, network, and running processes.

Features:

  • ✓ Real-time system metrics with live updates
  • ✓ Beautiful terminal UI with smooth animations
  • ✓ Web dashboard accessible via browser
  • ✓ REST API for programmatic access
  • ✓ Lightweight with minimal resource overhead

Installation

Requirements

  • • Python 3.8 or higher
  • • pip (Python package manager)
  • • Windows, macOS, or Linux

From PyPI

pip install minit-cli

From Source

git clone https://github.com/minit-cli/minit-cli.git cd minit-cli pip install -e .

Verify Installation

minit --version

Quick Start

1. Start the CLI Dashboard

Run minit in your terminal:

minit

This starts the live terminal dashboard showing real-time system metrics.

2. Access Web Dashboard

Open your browser and navigate to:

http://localhost:7770

Beautiful web interface with real-time charts and metrics.

3. Query the API

Get JSON data via REST API:

curl http://localhost:7770/api/metrics

Usage

Basic Commands

Start monitoring (terminal UI):

$ minit

Displays live dashboard with CPU, memory, disk, network, and process information.

Start monitoring with custom port:

$ minit --port 8000

Web dashboard available at http://localhost:8000

View all available options:

$ minit --help

Display version:

$ minit --version

CLI Options

Option Description Default
--port Web server port 7770
--host Server host address localhost
--interval Update interval in seconds 1
--log-level Logging level (DEBUG, INFO, WARNING, ERROR) INFO
--no-web Disable web server (CLI only) -
--version Show version and exit -
--help Show help message -

API Reference

minit provides a REST API for programmatic access to system metrics.

Base URL

http://localhost:7770/api

Endpoints

GET /metrics

Get all current system metrics.

Request:

curl http://localhost:7770/api/metrics

Response (JSON):

{
  "cpu": {
    "percent": 25.5,
    "cores": 8,
    "freq": 3400
  },
  "memory": {
    "total": 16384,
    "used": 8192,
    "percent": 50.0
  },
  "disk": {
    "total": 512000,
    "used": 256000,
    "percent": 50.0
  },
  "network": {
    "bytes_sent": 1048576,
    "bytes_recv": 2097152
  },
  "timestamp": "2026-03-24T12:34:56Z"
}

GET /cpu

Get CPU metrics only.

Request:

curl http://localhost:7770/api/cpu

Response:

{
  "percent": 25.5,
  "cores": 8,
  "freq": 3400,
  "per_cpu": [12.0, 18.5, 22.3, ...]
}

GET /memory

Get memory metrics.

Request:

curl http://localhost:7770/api/memory

Response:

{
  "total": 16384,
  "available": 8192,
  "used": 8192,
  "free": 4096,
  "percent": 50.0
}

GET /disk

Get disk usage metrics for all partitions.

Request:

curl http://localhost:7770/api/disk

Response:

{
  "partitions": [
    {
      "device": "/dev/sda1",
      "mountpoint": "/",
      "total": 512000,
      "used": 256000,
      "free": 256000,
      "percent": 50.0
    }
  ]
}

GET /network

Get network metrics.

Request:

curl http://localhost:7770/api/network

Response:

{
  "bytes_sent": 1048576,
  "bytes_recv": 2097152,
  "packets_sent": 5000,
  "packets_recv": 10000,
  "errors_in": 0,
  "errors_out": 0
}

GET /processes

Get list of running processes (limit: top 50 by CPU).

Request:

curl http://localhost:7770/api/processes

Response:

{
  "processes": [
    {
      "pid": 1234,
      "name": "minit-server",
      "cpu_percent": 12.5,
      "memory_mb": 245,
      "status": "running"
    },
    {
      "pid": 5678,
      "name": "chrome",
      "cpu_percent": 8.3,
      "memory_mb": 892,
      "status": "running"
    }
  ]
}

GET /system

Get system information.

Request:

curl http://localhost:7770/api/system

Response:

{
  "hostname": "my-machine",
  "os": "Linux",
  "os_version": "5.15.0",
  "platform": "x86_64",
  "uptime": 1048576,
  "boot_time": "2026-03-12T10:30:00Z"
}

Examples

Monitoring CPU Usage

Get real-time CPU metrics:

curl -s http://localhost:7770/api/cpu | jq '.percent'

Output: 25.5

Checking Memory Usage

Get memory percentage:

curl -s http://localhost:7770/api/memory | jq '.percent'

Output: 50.0

Top CPU Consuming Processes

Get top processes by CPU:

curl -s http://localhost:7770/api/processes | jq '.processes[] | {name, cpu_percent}' | head -20

Continuous Monitoring with Polling

Monitor metrics every 5 seconds in bash:

while true; do
  curl -s http://localhost:7770/api/metrics | jq '.cpu.percent, .memory.percent'
  sleep 5
done

Export to File

Save metrics to JSON file for analysis:

curl -s http://localhost:7770/api/metrics > metrics_$(date +%s).json

Python Integration

Access metrics from Python:

import requests
import json

response = requests.get('http://localhost:7770/api/metrics')
metrics = response.json()
print(f"CPU: {metrics['cpu']['percent']}%")
print(f"Memory: {metrics['memory']['percent']}%")

Troubleshooting

❌ "Command not found: minit"

The package isn't installed or not in PATH.

✓ Solution:

pip install --upgrade minit-cli

❌ "Port 7770 already in use"

Another service is using the default port.

✓ Solution: Use a different port:

minit --port 8000

❌ "Connection refused" when accessing API

minit is not running or not listening on the expected port.

✓ Solution: Ensure minit is running:

minit & # Start in background

❌ "Permission denied" errors

Some system information requires elevated privileges.

✓ Solution: Run with sudo (on Linux/macOS):

sudo minit

❌ High CPU usage on monitoring

Update interval is too short.

✓ Solution: Increase interval:

minit --interval 5

Need Help?

If you encounter issues or have questions not covered here: