USM - User Service Manager

Headless → Desktop Bridge for systemd --user

USM is a complete CLI tool and PyQt6 GUI control panel for managing systemd user services. It brings visibility and control to the powerful but often invisible world of user-level systemd units.

Status: ✅ Production Ready (v0.1.0)

Why USM?

User services are powerful but invisible. systemd --user manages services, timers, and sockets under your user account - but unlike system services, there's no easy way to see what's running, what's failing, or what's waking up your CPU. USM fixes that.

Features

Current (v0.1.0 - All Phases Complete)

CLI (P0):

• 📋 List all user services, sockets, timers, and other units
• 🎯 Filter by unit type or failed status
• 🚦 Control units: start, stop, restart
• 🔧 Enable, disable, or mask units
• 📊 View detailed unit status
• 🎨 Beautiful, color-coded terminal output with Rich

GUI (P1):

• 🖥️ PyQt6 desktop interface with modern design
• 📊 Sortable table view with color-coded states
• 🔍 Sidebar filters (type, failed-only)
• 🖱️ Right-click context menu for operations
• 📜 Embedded log viewer with copy support
• ⌨️ Full keyboard navigation

Power Features (P2):

• ⏰ Timer tracking with next/last run timestamps
• 🔴 Missed run detection and highlighting
• ⚠️ Failure analysis with exit codes and signals
• 🔍 Error log extraction
• 🔄 Batch "Restart All Failed" operation
• 💻 Resource monitoring (CPU%, Memory)
• 📊 On-demand resource refresh

Polish (P3):

• 💾 Config persistence (~/.config/usm/config.json)
• 📐 Window geometry and filter preferences saved
• ⌨️ Keyboard shortcuts (Ctrl+R, Ctrl+F, Ctrl+W, F5, F6)
• 🖥️ Desktop integration with .desktop entry
• 🎨 Application icon
• 📦 Arch Linux PKGBUILD for easy installation

Installation

Arch Linux (Recommended)

# Build and install from PKGBUILD
cd /path/to/usm
makepkg -si

# Commands available globally:
usm --help
usm-gui

From Source

# Clone the repository
git clone https://github.com/vorlie/usm.git
cd usm

# Install in development mode with virtual environment
python -m venv .venv
source .venv/bin/activate
pip install -e ".[gui]"

Desktop Integration

# Install desktop entry (for application menu)
cp usm.desktop ~/.local/share/applications/
update-desktop-database ~/.local/share/applications

See INSTALL.md for detailed installation instructions.

Usage

CLI

# List all user units
usm list

# Filter by type
usm list --type service
usm list --type timer

# Show only failed units
usm list --failed

# View detailed status
usm status myservice.service

# Control operations
usm start myservice.service
usm stop myservice.service
usm restart myservice.service

# Enable/disable units
usm enable myservice.service
usm disable myservice.service

GUI

# Launch GUI (if installed via package)
usm-gui

# Or from source with venv
.venv/bin/usm-gui

GUI Keyboard Shortcuts:

• F5 or Ctrl+R - Refresh units
• F6 or Ctrl+Shift+R - Refresh resources
• Ctrl+F - Toggle "Show Failed Only"
• Ctrl+W - Close window
• Ctrl+Q - Quit

Requirements

• Python 3.10 or higher
• systemd with user session support
• Linux (systemd-based distributions)

Non-Goals

USM is not trying to be:

• ❌ A system-wide systemd manager (use systemctl or existing tools)
• ❌ A systemd unit file editor (use your favorite text editor)
• ❌ A replacement for journalctl (we integrate with it, not replace it)
• ❌ A service creator/generator (write your own unit files)
• ❌ Cross-platform (systemd is Linux-only by design)

USM focuses on visibility and control for existing user services.

Development

# Install development dependencies
pip install -e ".[dev]"

# Format code
black .

# Type checking
mypy usm/

Project Structure

usm/
├── usm/
│   ├── __init__.py
│   ├── cli.py           # CLI interface
│   ├── config.py        # Configuration management
│   ├── failures.py      # Failure analysis
│   ├── logs.py          # Journalctl wrapper
│   ├── models.py        # Data models
│   ├── operations.py    # Unit operations
│   ├── resources.py     # Resource monitoring
│   ├── systemctl.py     # Systemctl wrapper
│   ├── timers.py        # Timer tracking
│   └── gui/
│       ├── app.py           # GUI entry point
│       ├── main_window.py   # Main window
│       ├── unit_table.py    # Unit list table
│       ├── logs_panel.py    # Log viewer
│       ├── sidebar.py       # Filters sidebar
│       ├── context_menu.py  # Right-click menu
│       └── failure_dialog.py # Failure details
├── pyproject.toml
├── usm.desktop
├── PKGBUILD
└── README.md

License

MIT License - see LICENSE for details.

Acknowledgments

Built following the strict phased development approach outlined in the original TODO:

• P0: Backend + CLI (core functionality)
• P1: GUI Foundation (daily driver)
• P2: Power Features (diagnostics)
• P3: Polish (production ready)

---

Status: ✅ v0.1.0 - Production Ready

Module Count: 19 Python modules
Total Lines: ~2400 LOC
Package: Available as Arch Linux package