ground-control-tui 1.0.2

A Python Textual app for monitoring VMs in the terminal

🚀 Ground Control - The Ultimate Terminal System Monitor

Ground Control is a sleek, real-time terminal-based system monitor built with Textual, Plotext and the nvitop API. It provides a powerful, aesthetic, customizable interface for tracking CPU, memory, disk, network, and GPU usage — all in a visually appealing and responsive TUI.

Ground Control works optimally with TMUX, install it here!

🌟 Features

📊 Real-Time System Monitoring

• CPU Usage: Per-core load tracking with frequency stats.
• Memory Utilization: RAM usage with dynamic visualization.
• Disk I/O: Monitor read/write speeds and disk usage.
• Network Traffic: Live upload/download speeds.
• GPU Metrics: Real-time NVIDIA GPU monitoring (if available).

🖥️ Responsive Layout

• Automatic resizing to fit your terminal window.
• Multiple layouts: Grid, Horizontal, and Vertical.
• Customizable widgets: Show only the metrics you need.

🎛️ Interactive Controls

• Keyboard shortcuts for quick navigation.
• Toggle between different layouts instantly.
• Customize displayed metrics via a built-in selection panel.

---

🛠️ Installation

🔹 Install via PyPI

pip install ground-control-tui

🔹 Install from Source

git clone https://github.com/alberto-rota/ground-control
cd ground-control
pip install -e .

---

🚀 Getting Started

🔹 Run Ground Control

Once installed, simply launch Ground Control with:

groundcontrol

Or run as a Python module:

python -m ground_control

🔹 Available Layouts

Grid Layout

A structured layout displaying all widgets neatly in a grid. When you first launch Ground Control, it will show this layout.

Horizontal Layout

All widgets aligned in a single row. If you like working with wide shell spaces, split a TMUX session horizontally and use this layout!

Vertical Layout

A column-based layout, ideal for narrow shell spaces. If you like working with tall shell spaces, split a TMUX session verticall and use this layout!

🖥️ Widget Breakdown

Each panel in Ground Control represents a different system metric:

🔹 CPU & Memory

• Shows real-time per-core CPU usage.
• Displays RAM usage with a visual bar.

🔹 Disk I/O

• Monitors read/write speeds.
• Displays disk usage in an easy-to-read format.

🔹 Network Traffic

• Tracks real-time upload/download speeds.
• Visualizes network activity.

🔹 GPU Metrics (NVIDIA Only)

• Displays GPU utilization and memory usage.
• Supports multiple GPUs with live tracking.

🛠️ Configuring Ground Control

You might not want to see all the widgets all at once. To select which widgets you want Ground Control to show, press c or the Configure button. You'll see a selection panel that yuu can use to toggle the widgets shown. Press c again to hide the configuration panel

You can switch to a grid, horizontal or verical layout with g, h or v or use the Grid Layout, Horizontal Layout or Vertical Layout buttons.

This configurations are saved when you quit Ground Control, so when you launch it again you will see the same layout!

All available keyboard shortcuts are listed here:

Key	Action
h	Switch to Horizontal Layout
v	Switch to Vertical Layout
g	Switch to Grid Layout
c	Show/Hide the configuration panel
q	Quit Ground Control

---

Ground Control saves user preferences in a configuration file located at: ~/.config/ground-control/config.json. Modify this file in your default text editor with

groundcontrol config

👨‍💻 Contributing

Pull requests and contributions are welcome! To contribute:

1. Fork the repo.
2. Create a feature branch.
3. Submit a PR with your changes.

Visit the Issue Section to start!

📜 License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

📧 Author

Alberto Rota
📩 Email: [e-mail]
🐙 GitHub: @alberto-rota

🚀 Stay Updated

For the latest features and updates, visit the GitHub repository.