systui — Modular Linux System Administration TUI

Overview

systui is a comprehensive Linux system administration tool with:

• Modular architecture — Clean separation of concerns
• Dialog-based TUI — Terminal UI for easy navigation
• Multi-distro support — Alpine, Arch, Debian, Devuan
• Easy installation — Single install.sh script
• Extensible design — Add features by creating modules

Quick Start

Installation

# Clone or download the project
git clone https://github.com/... systui
cd systui

# Run installation (requires root)
sudo ./install.sh

# Use systui
sudo systui

First Run

sudo systui
→ Main Menu
→ Ultimate Provision
→ Configure quick-setup settings
→ Quick setup (install/update, review, and run)
→ Re-login to activate the new shell environment

Project Structure

systui/
│
├── install.sh                # Installation script (dependencies + setup)
├── update.sh                 # Update from Git and reinstall
├── README.md                 # This file
│
├── src/                      # Source code (modules)
│   ├── core/                 # Core utilities and framework
│   │   ├── config.sh         # System detection, logging, config, run_strict
│   │   ├── tui-widgets.sh    # TUI widget functions
│   │   └── common.sh         # Common utilities & package mapping
│   │
│   ├── provision/            # Multi-distro quick-setup provisioning
│   │   ├── runtime.sh        # Shared distro adapters, sshd + config helpers
│   │   └── provision-ultimate.sh # Portable multi-distribution quick setup
│   │
│   └── features/             # Feature modules
│       ├── health.sh         # System health scanner
│       ├── rootfs.sh         # Rootfs builder and manager
│       ├── sysconfig.sh      # System configuration (shells, repos, packages,
│       │                     #   services, users, storage, Awesome Linux)
│       └── ultimate-provision.sh # Quick-setup lifecycle menu
│
├── share/                    # Non-code resources
│   └── homebrew/             # Root-compatible Homebrew compatibility layer
│       └── install-homebrew-root.sh
│
└── tests/                    # Test suite
    └── test-*.sh             # Test files

The `systui` executable is generated by install.sh into $INSTALL_PREFIX/bin;
it is not checked into the repository.

Module System

Core Modules

src/core/config.sh

• System detection (PM, init, distro)
• Logging and error handling
• Configuration management

Key Functions:

detect_pm()           # Detect package manager  -> $PM
detect_init()         # Detect init system      -> $INIT
detect_distro()       # Detect distribution     -> $DISTRO, $DISTRO_ID_LIKE,
                      #                            $DISTRO_VERSION,
                      #                            $DISTRO_PRETTY_NAME
require_root()        # Ensure root access (calls die, which exits)
log <message>         # Append to $LOGFILE (/var/log/systui.log when writable,
                      #   else ~/.local/state/systui.log; override with
                      #   $SYSTUI_LOGFILE)
warn <message>        # Record a warning and log it
die <message>         # Fatal error and exit
get_config <key> [default]   # Read a value from $(systui_config_file)
set_config <key> <value>     # Write a value to $(systui_config_file)
run_strict <desc> <fn> [args...]  # Run one routine fail-fast in a subshell

src/core/tui-widgets.sh

• Dialog wrapper functions
• TUI components (menu, input, checkbox, etc.)
• Command execution with output

Key Functions:

tui_msg <title> <message>              # Message dialog
tui_yesno <title> <question>           # Yes/no dialog
tui_input <title> <prompt> [default]   # Input dialog
tui_menu <title> <text> <tag> <desc>   # Menu selection
tui_check <title> <text> <tag> <desc>  # Checkbox list
tui_radio <title> <text> <tag> <desc>  # Radio list
tui_text <title> <file>                # Text viewer
tui_menu_no_tags <title> <text> ...    # Menu showing descriptions only
run_cmd <description> <cmd...>         # Run command with output

src/core/common.sh

• Package mapping (Debian → Alpine/Arch/Fedora/Void)
• Package manager operations
• Common utilities

Key Functions:

map_packages <family> <pkgs...>  # Map package names
pm_install <pkgs...>            # Install packages
pm_remove <pkgs...>             # Remove packages
pm_update                        # Update package lists
cmd_exists <command>            # Check if command exists

Provisioning Modules

src/provision/provision-ultimate.sh

Portable, single quick-setup path for Alpine, Arch, Debian, Devuan, and other package-manager families (apt/apk/pacman/dnf/yum/zypper/xbps/portage), driven by the package-manager family detected at runtime rather than a dedicated script per distro. Installs the shared package set, sets timezone and locale, creates the user account, configures sudo access, enables services, and writes the MOTD/shell environment — with a skip-and-continue installer so one unavailable package doesn't abort the whole run.

src/provision/runtime.sh

Shared, distro-agnostic helpers used by the provisioning path above: sshd configuration with sshd -t validation, and a config-file loader (provision_load_config) that snapshots and restores internal variables (LOGFILE, PM, DISTRO, PATH, ...) so a sourced config file can never override them.

Installation Details

What install.sh Does

1. Detects package manager (APT, APK, pacman, DNF, Zypper, XBPS, or Portage)

2. Installs only missing runtime dependencies, without recommended/weak packages:

   • bash
   • dialog
   • Minimal text and file utilities (coreutils, grep, sed, awk, find)
   • curl or an already-installed wget, plus CA certificates, for the synchronized software catalogue

   Feature-specific tools for rootfs creation, storage, networking, archives, builds, and managed applications are installed only when their menu action explicitly requires them.

3. Replaces managed project files in /usr/local/lib/systui/ with the latest copy

4. Creates or replaces the executable at /usr/local/bin/systui

5. Creates man page for documentation

6. Verifies installation

Dependencies

Minimum required:

• bash 4.0+
• dialog
• grep, sed, awk, cut, tr (standard utilities)
• openssl (for cryptography)
• curl or wget (for network operations)

Optional:

• man-db (for documentation)
• git (for cloning)
• tzdata (for timezone support)

Usage Examples

Basic Usage

# Run systui
sudo systui

# Navigate with arrow keys, Enter to select
Main Menu
  → Ultimate Provision
    → Quick setup (install/update, review, and run)
    → Install or update Ultimate Provision
    → Configure quick-setup settings
    → Show status and current settings
    → Run Ultimate Provision now
    → Remove installed Ultimate Provision

Quick System Setup

# On a supported Linux distribution
sudo systui
→ Ultimate Provision → Configure quick-setup settings
→ Quick setup (install/update, review, and run)

Ultimate Provision configures the timezone, primary user, hostname, sudo policy, terminal package set, services, Bash environment, Neovim, and tmux. It selects distribution-specific packages and service names for APT, Alpine APK, Arch pacman, Fedora/RHEL DNF or YUM, openSUSE zypper, Void XBPS, and Gentoo Portage. Unavailable packages are reported and skipped without stopping the run.

Configuration

User Configuration

Configuration stored in ~/.systui/config:

# Set timezone preference
systui-config-set "timezone" "America/New_York"

# Set preferred shell
systui-config-set "shell" "bash"

System-Wide Configuration

Location: /etc/systui/config

# Default distro preferences
default_timezone=America/Los_Angeles
enable_services=true
install_docs=true

Adding Features

Create a New Feature Module

1. Create file: src/features/myfeature.sh
2. Define functions:

#!/bin/bash
# systui — My Feature

menu_myfeature() {
    local choice
    choice=$(tui_menu "My Feature" "Description:" \
        option1 "First option" \
        option2 "Second option" \
        back    "Back") || return
    
    case "$choice" in
        option1) do_something_1 ;;
        option2) do_something_2 ;;
        back)    return ;;
    esac
}

export -f menu_myfeature

3. Add to main menu in bin/systui:

. "$LIBDIR/src/features/myfeature.sh"

# In main_menu():
myfeature) menu_myfeature ;;

Adding a New Distro

provision-ultimate.sh provisions by detected package-manager family, not by a per-distro script, so a new distro usually needs no new provisioning code — only:

1. Update detect_distro() / detect_pm() in src/core/config.sh if the distro isn't already recognized.
2. Extend the package-name map in src/core/common.sh if it needs distro-specific package names.
3. Add any distro-specific package-manager branch to src/provision/provision-ultimate.sh if its family isn't already handled (apt/apk/pacman/dnf/yum/zypper/xbps/portage).

Troubleshooting

"Command not found: dialog"

# Install dialog
sudo apt install dialog        # Debian
sudo apk add dialog            # Alpine
sudo pacman -S dialog          # Arch
sudo dnf install dialog        # Fedora

"Must run as root"

# Run with sudo
sudo systui

"Package not found"

• Check /tmp/systui.log for details
• Package mapping in src/core/common.sh may need updates
• Some packages have distro-specific names

Provisioning failed

1. Check log file: cat /tmp/systui.log
2. Check internet connectivity
3. Verify distro is supported
4. Try again (scripts are idempotent)

Development

Project Structure Rationale

• Modular design → Easy to test, extend, maintain
• Function-based → No class complexity, pure bash
• Logging everywhere → Debug issues easily
• Consistent patterns → Similar code style throughout

Code Style

• Use #!/bin/bash (bash-specific features OK)
• Export functions: export -f function_name
• Log important operations: log "message"
• Validate input in functions
• Use set -e to catch errors
• Comment complex logic

Testing

# Syntax check
bash -n src/core/config.sh
bash -n src/core/tui-widgets.sh
bash -n src/core/common.sh
bash -n src/features/rootfs.sh

# Rootfs backend tests
bash tests/test-rootfs-backends.sh

# Full test
sudo ./install.sh
sudo systui
# Test menu navigation and features

Performance

• Startup: < 1 second
• Menu navigation: Instant
• Provisioning: 5-15 minutes (depends on distro and internet)
• Memory: < 10 MB
• Disk: < 5 MB (project files)

Supported Distributions

Distro	Version	Init	PM	Status
Alpine	3.23+	OpenRC	apk	✓ Supported
Arch	Current	systemd	pacman	✓ Supported
Debian	12+	systemd	apt	✓ Supported
Devuan	6+	sysvinit	apt	✓ Supported
Ubuntu	22.04+	systemd	apt	✓ Compatible
Fedora	38+	systemd	dnf	✓ Partial

Known Limitations

1. Feature modules not yet implemented — Shells, repos, rootfs planned
2. Offline provisioning — Requires internet for package downloads
3. Non-interactive provisioning — TUI always shown (but scriptable via env vars)
4. Limited customization — Edit scripts for fine-grained control

Future Enhancements

• Feature modules (shells, repos, rootfs)
• Fedora/RHEL/CentOS support
• Configuration file support
• Package version pinning
• Automated testing suite
• Plugin system
• Cloud-init integration
• Backup/restore functionality

License

Free and open for use, modification, and distribution.

Support

• Documentation: See /usr/local/lib/systui/docs/
• Log file: /tmp/systui.log
• Man page: man systui

Version History

• 1.0.0 (2026-07-29) — Initial release
  • Modular architecture
  • Multi-distro provisioning
  • TUI framework
  • Alpine, Arch, Debian, Devuan support

---

Happy provisioning! 🚀

For detailed architecture, see docs/ARCHITECTURE.md
For developers, see docs/DEVELOPER_GUIDE.md

Expanded Software Catalogue

The package catalogue now includes:

• 17 software categories covering terminal tools, development, networking, security, monitoring, servers, containers, backups, multimedia and more.
• Curated one-click collections for iSH-AOK essentials, development stacks, servers, networking, security and backup environments.
• Bulk package-list export/import and bulk removal.
• Package health checks, orphan detection, cache cleanup and integrity checks.
• Rich package pages with install, remove, reinstall, metadata, installed-file, version-hold and package-integrity actions.
• Package-name translation for APT, APK, Pacman and DNF environments.

Expanded rootfs and package management

• Guided backend selection with Automatic or explicit choices: mmdebstrap, debootstrap, cdebootstrap, qemu-debootstrap, and multistrap for Debian-family roots; pacstrap or the official bootstrap tarball for Arch; and the native APK, DNF, Zypper, stage3, or Void tarball backend for other distributions.
• Backend-specific configuration menus cover variants/flavours, components, bootstrap include/exclude lists, keyrings, merged /usr, execution modes, documentation/locale pruning, cdebootstrap configuration directories and authentication, and generated or custom multistrap configurations.
• Backend settings are persisted in .systui-backend.conf inside the build so interrupted rootfs generation resumes with the same tool configuration. They can be edited later through Rootfs → Manage → Configure bootstrap backend.
• Repository-backed, SPACE-selectable release discovery with offline fallbacks.
• Expanded minimal, workstation, development, server, web, and security presets.
• Profile-based custom package installation and additional individual packages.
• In-rootfs locale, timezone, shell, editor, SSH, services, package update/upgrade, cleanup, machine-id, and mount-helper configuration.
• Rootfs management exposes the same post-build configuration controls.
• tar.gz is the default build and management compression format.
• System Configuration → Packages begins with Package Managers, followed by Repositories and Catalogue.
• Package-manager configuration covers APT, apt-fast, Nala, pip, pipx, Flatpak, Snap, Cargo, npm, pnpm, and Yarn.
• Additional iSH-AOK, memory, writeback, tmpfs, and DNS-cache performance controls.
• Rootfs backend prerequisites remain optional and are checked only after a backend is selected; the minimal install.sh does not install them.
• Menu cancellation paths return to their parent menu instead of propagating a fatal status.

Additional rootfs distributions

Kali Linux, openSUSE Leap, openSUSE Tumbleweed, and Gentoo stage3 are available from the Rootfs Builder.

System Health

The main-menu System Health section replaces the former log viewer and provides:

• Quick health dashboard
• Full exportable health reports
• Package integrity and dependency checks
• Storage, filesystem, inode, and mount checks
• Failed/crashed service detection
• Network, route, resolver, and listening-port checks
• Security configuration audit
• CPU, memory, process, zombie, and kernel-warning checks
• Conservative package repair, cleanup, SSH validation, and fstab validation

The internal operation log remains available at /tmp/systui.log for command diagnostics.

Awesome Linux catalogue

The Awesome Linux menu synchronizes the upstream software list and rebuilds it as a 26-group catalogue. All 1,235 current software entries are retained under stable categories such as Audio & Music, Development, Gaming & Emulation, Security, System Utilities, and Terminal & CLI. Documentation-only sections, including “Unsure how to contribute?”, contribution guidelines, news, Reddit, contributors, and licensing, are excluded and cannot appear as installable categories. Existing caches are automatically reparsed when the taxonomy version changes. Nested category menus use independent state, so returning from a subcategory cannot corrupt its parent menu. Project installer scripts are generated only after a project is selected, keeping first launch and catalogue refresh responsive.

Package and shell menu organization

System Configuration > Packages now contains Package Managers, Repos, Catalogue, Packages, and Advanced. Native install, remove, search, information, installed-package listing, hold, update, and cleanup actions are grouped under the Packages submenu.

APT repository management includes both /etc/apt/sources.list and /etc/apt/sources.list.d/. The signing-key menu can install available Debian, Ubuntu, Devuan, and Kali archive keyrings using a SPACE-to-select checklist.

System Configuration > Shells separates Managers from Plugins. Each Bash, Zsh, and Fish manager includes installation, removal, and its framework/plugin-manager configuration. Cross-shell plugins include Starship, fzf, completion packages, zoxide, Atuin, direnv, Carapace, syntax highlighting, and autosuggestions.

Terminal file managers

System Configuration > File Managers manages terminal file managers and their user configuration:

• lf
• tere
• Yazi
• Ranger
• nnn
• Vifm
• Broot
• xplr

Each entry supports installation/removal, a recommended starter configuration, direct configuration editing, launching, and a GitHub-backed add-on manager. Add-ons are installed per user under the applicable ~/.config directory; custom Git repositories are also supported.

Shell plugin configuration managers

System Configuration > Shells > Plugins now opens a per-user manager for each plugin. Starship, fzf, completions, zoxide, Atuin, direnv, Carapace, Zsh syntax highlighting, and Zsh autosuggestions include install/remove actions, shell integration, editable configuration, status inspection, and cleanup controls.

Updating

From a Git checkout:

sudo ./update.sh

After installation, the same updater is available globally:

sudo systui-update

The updater fetches the current branch from origin, backs up and stashes local source changes, fast-forwards to the latest revision, and reruns install.sh. Use --no-deps to skip package dependency installation or --force to reset the source checkout after creating a backup.

RootFS additional package catalogue

The RootFS Builder now opens a categorized package catalogue after preset selection. It supports space-to-select package lists, reusable rescue/developer/server/network/container/diagnostic presets, catalogue search, manual native package names, selection review, and de-duplication. Canonical package names are translated through the existing Alpine, Arch, Fedora, and Void package maps where available.

Shell configuration and aliases

System Configuration → Shells includes:

• Shell config files — automatically populated targets for .bashrc, .zshrc, Fish config.fish, .profile, .bash_profile, .zprofile, and .inputrc. Common settings can be selected with SPACE and written into a removable systui-managed block. The tool also supports custom entries, backups, direct editing, viewing, and syntax validation.
• Alias manager — installs aliases from a catalog, adds or replaces custom aliases, removes aliases, imports existing alias definitions, validates syntax, and generates Fish-compatible aliases. Managed aliases are stored under ~/.config/systui/ and sourced from supported shell files.

Expanded system configuration

• Shell plugin catalogue for Bash, Zsh, and Fish GitHub projects with installation, updates, and shell integration.
• Expanded GitHub add-on catalogues and update/status management for terminal file managers.
• Full OpenSSH server configuration for authentication, access controls, keys, forwarding, keepalives, SFTP, banners, host keys, logs, and validation.
• Additional iSH-AOK compatibility, storage, cache, logging, shell, APT, and capability-report tuning.

Expanded package-manager configuration

System Configuration > Packages > Managers now provides configuration and maintenance hubs for APT, apt-fast, Nala, aptitude, pacman, yay, paru, DNF, YUM, zypper, apk, XBPS, Portage, Flatpak, Snap, Nix, Homebrew, pip, pipx, npm, pnpm, Yarn, Cargo, RubyGems, Composer, and Go tools.

Homebrew is managed through a permanent root-compatibility layer for iSH-AOK / Debian arm64: a shared installer under share/homebrew/, a system wrapper at /usr/local/bin/brew, a UID shim at /usr/local/lib/homebrew-root/, and a managed environment file at /etc/systui/homebrew.env.

Notes on behaviour

Error handling

config.sh does not enable a shell-wide set -e. dialog returns 1 on Cancel and 255 on ESC as ordinary control flow, so a global set -e plus an ERR trap turned every stray Escape keypress into a fatal error. Routines that want fail-fast semantics opt in:

run_strict "rootfs_builder" rootfs_builder_impl "$@"

run_strict runs the routine in a subshell with set -eE and an ERR trap, so a failure aborts that routine and is recorded as a warning, without tearing down the surrounding menu.

Building software from the Awesome Linux catalogue

The catalogue is generated from a community-maintained upstream README. The github install method clones the listed repository and runs its build system — and its own install.sh, where one exists — with root privileges.

Because of that, it is never reached implicitly: auto tries the native package, Flatpak and Snap, then stops and tells you what to run. Choosing the GitHub method shows the resolved repository URL and requires typing yes before anything is fetched. Set SYSTUI_ASSUME_YES=1 to skip the prompt in an unattended run.

Review the repository, and the generated installer (GitHub: review generated installer), before using this method.

Configuration file location

get_config / set_config read and write /etc/systui/config when running as root and ${XDG_CONFIG_HOME:-~/.config}/systui/config otherwise. Set $SYSTUI_CONFIG_DIR to override. A bare ~ is not used, because whether sudo resets HOME varies by distribution and the same install would otherwise read two different files.

Provisioning config files

provision_load_config in src/provision/runtime.sh sources a config file as a shell script with root privileges. Values that systui depends on internally (LOGFILE, PM, DISTRO, PATH, ...) are snapshotted and restored around the source, and any attempt to change them is logged and reverted.