minit-cli

A cross-platform (Ubuntu & Windows) real-time machine-stats CLI tool with a JSON export API, persistent metric logging, and configurable alerting.

Features

🌐 Website

For detailed documentation and features, visit: https://minit-cli.vamsi-tech.org/

Live Demo

Watch minit in action — real-time system monitoring in your terminal:

Or view it directly: minit Dashboard Demo

Install from PyPI

pip install minit-cli
minit setup          # adds minit to PATH (user shells + optionally system)
minit dashboard

Requirements: Python 3.9+ on Ubuntu/Debian or Windows 10/11.

"minit: command not found" / "'minit' is not recognized"

pip installs CLI scripts into a scripts directory that may not be on your PATH yet. Follow the steps for your OS below.

Windows

1. Find the scripts directory:

   python -m site --user-site
   

   Replace site-packages at the end of that path with Scripts, e.g. C:\Users\<you>\AppData\Roaming\Python\Python312\Scripts

   Or run this one-liner to print the exact path:

   python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
   

2. Add that path to your system (or user) environment variable:

   GUI — Search → "Edit the system environment variables" → Environment Variables → select Path under User variables → Edit → New → paste the Scripts path → OK.

   PowerShell (one-liner):

   [System.Environment]::SetEnvironmentVariable(
       "PATH",
       [System.Environment]::GetEnvironmentVariable("PATH","User") + ";C:\Users\<you>\AppData\Roaming\Python\Python312\Scripts",
       "User"
   )
   

3. Close and reopen your terminal, then run minit --help.

Tip: If you installed into a virtual environment, activate it first (.venv\Scripts\activate) — the minit command will be available automatically while the venv is active.

Linux / macOS

1. Find the scripts directory:

   python3 -m site --user-base
   

   The scripts live in <user-base>/bin, e.g. ~/.local/bin.

2. Check whether that directory is already on your PATH:

   echo $PATH | tr ':' '\n' | grep -i local
   

3. If it is not listed, add it to your shell profile:

   bash — append to ~/.bashrc:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   

   zsh — append to ~/.zshrc:

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   

   fish — run once:

   fish_add_path ~/.local/bin
   

4. Verify:

   which minit
   minit --help
   

Virtual environment: If you installed inside a venv, activate it first:

source .venv/bin/activate

The minit command is available as long as the venv is active.

Alternative — run via Python directly (all platforms)

If you prefer not to modify PATH, invoke the CLI through the Python interpreter:

python -m minit_cli.cli dashboard
python -m minit_cli.cli serve
python -m minit_cli.cli stats

Commands

minit dashboard

Launch the full-screen real-time terminal dashboard (press Ctrl-C to quit).

minit dashboard              # default: refresh every 2 s (or from config)
minit dashboard --refresh 5  # refresh every 5 s

minit serve

Start the JSON export API server in the background. Snapshots are collected on a configurable interval, kept in a rolling in-memory window, and also written to daily log files on disk.

minit serve                                          # defaults from config
minit serve --host 0.0.0.0 --port 9000
minit serve --interval 5 --window 1800              # 5 s interval, 30 min window

All flags fall back to values in ~/.config/minit/config.toml when not specified.

Endpoints:

minit stop

Stop the running background server.

minit stop

minit status

Show whether the server is running, plus its PID, host, port, and uptime.

minit status

minit server: running
  PID:     12345
  host:    127.0.0.1
  port:    8000
  uptime:  00:42:17

minit stats

Print a one-shot snapshot to stdout (useful for scripting).

minit stats                      # compact JSON
minit stats --pretty             # indented JSON
minit stats --format table       # aligned key/value table
minit stats --format csv         # two-column CSV

minit logs

View, filter, or tail the persistent metric log files stored in ~/.local/share/minit/logs/ (one .jsonl file per day).

minit logs                          # all entries from today
minit logs --date 2024-01-15        # entries for a specific date
minit logs --since 1h               # last hour
minit logs --since 30m              # last 30 minutes
minit logs --since 2024-01-15T10:00 # from an absolute timestamp
minit logs --until 2024-01-15T12:00 # up to a timestamp
minit logs --follow                 # tail live (Ctrl-C to stop)
minit logs --pretty                 # pretty-print JSON

Alert events are stored separately in alerts.jsonl in the same directory.

minit config

Manage the configuration file at ~/.config/minit/config.toml.

minit config                          # show all current values
minit config --show                   # same as above
minit config --path                   # print the config file path

minit config set server.port 9000
minit config set server.interval 5
minit config set server.history_window 1800
minit config set dashboard.refresh 1.0
minit config set logging.retention_days 30
minit config set thresholds.cpu_percent 85
minit config set thresholds.memory_percent 90
minit config set thresholds.disk_percent 80
minit config set thresholds.hook "notify-send minit '$MINIT_ALERT_METRIC exceeded'"

Config keys:

Alert hook environment variables:

minit setup

Add the minit install directory to PATH so the command is available in every new shell session.

minit setup              # user-level: ~/.bashrc and ~/.zshrc (Linux/macOS)
                         #             HKCU\Environment via setx (Windows)
minit setup --system     # also update system-wide PATH
                         # Linux/macOS: /etc/environment (requires sudo)
                         # Windows:     HKLM environment key (requires admin shell)

Development setup

For contributors and anyone who wants to run or modify the source directly.

Prerequisites

• Python 3.9 or newer
• git

1. Clone the repository

git clone https://github.com/vamsi-ehc/minit-cli
cd minit-cli

2. Create and activate a virtual environment

# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\activate

3. Install dependencies and the package in editable mode

pip install -r requirements.txt
pip install -e .

4. Verify

minit --help

Run tests

pytest