Helper Tool - SoltrOS

What is helper.sh?

helper.sh is the primary interface for managing your SoltrOS system. It's a comprehensive Bash script that simplifies common tasks like installing software, switching between releases, configuring services, and maintaining your immutable operating system.

Unlike configuration management tools like Just, helper.sh is designed specifically for SoltrOS with a focus on user-friendliness and direct system integration. It's shipped from the component repository and maintained alongside the operating system itself.

🚀 Coming Soon: GUI Frontend

A graphical frontend for helper.sh is currently in development, written in Go using the Fyne toolkit. This will provide the same powerful functionality with a beautiful, modern interface for users who prefer graphical tools.

Why Not Just or Other Tools?

While tools like Just are popular in the immutable Linux space, helper.sh was created for several reasons:

Personal preference - As the creator of SoltrOS, I prefer writing in Bash for system tooling
Zero dependencies - Bash is already on your system; no need to install additional tools
Direct integration - Written specifically for SoltrOS architecture and workflows
Simplicity - Easy to read, modify, and understand for anyone comfortable with shell scripts
Immediate execution - No compilation or interpretation overhead
Complete control - Full access to system commands without abstraction layers

Getting Started

Helper is pre-installed on SoltrOS and available system-wide. Simply open your terminal and type:

helper

This displays all available commands. To run a specific command:

helper [COMMAND]

For Bash users who want quick access, you can add the helper alias:

helper add-helper

Core Features

🎯 Installation Commands

Quickly install software and configure your system with one-line commands.

install-flatpaks

Install all Flatpak applications from the official SoltrOS list

install-gaming

Install Steam, Heroic, Lutris, and gaming essentials

install-multimedia

Install Blender, GIMP, Kdenlive, and creative tools

install-homebrew

Install the Homebrew package manager

install-nix

Install Nix package manager with SoltrOS configuration

download-appimages

Download Feishin and Ryujinx AppImages

⚙️ Configuration Commands

Manage system settings and configure hardware features.

setup-git

Configure Git with username, email, and SSH signing

setup-distrobox

Create Ubuntu and Arch development containers

enable-amdgpu-oc

Enable AMD GPU overclocking support

unblock-docker

Allow containers from unapproved registries like Docker Hub

toggle-session

Switch between X11 and Wayland sessions

🔄 Release Management

Switch between SoltrOS releases seamlessly with atomic updates.

change-to-stable

Switch to SoltrOS LTS (Long-Term Support) rolling release

change-to-unstable

Switch to SoltrOS Unstable (Rolling Rocket) release

🎨 Desktop Environment Variants

When switching releases, you can choose between KDE Plasma, COSMIC, or GNOME desktop environments. The release switcher will prompt you to select your preferred variant.

🐚 Shell Management

Switch between shells with configurations automatically applied.

change-to-zsh

Switch to Zsh (default shell with Oh My Zsh pre-configured)

change-to-fish

Switch to Fish shell with SoltrOS configuration

change-to-bash

Switch to Bash shell with SoltrOS configuration

🎨 Theme Application

Apply the official SoltrOS theme to your desktop environment.

apply-soltros-look_plasma

Apply SoltrOS theme to KDE Plasma

apply-soltros-look_cosmic

Apply SoltrOS theme to COSMIC desktop

🔧 System Maintenance

Keep your system updated and clean with automated maintenance commands.

update

Update system (bootc), Flatpaks, and all containers

clean

Clean up system cache, unused Flatpaks, and old deployments

distrobox

List and manage distrobox containers

toolbox

List and manage toolbox containers

Advanced Features

Nix Package Manager Integration

Helper includes special support for the Nix package manager with the nixmanager.sh companion script:

      helper install-nix          # Install Nix with Determinate installer
helper setup-nixmanager    # Setup nixmanager script in ~/scripts/
helper add-nixmanager      # Add nixmanager alias to Bash
    

The nixmanager.sh script provides a user-friendly interface for working with Nix on SoltrOS, making it easy to install and manage Nix packages without learning complex Nix commands.

Smart Docker Registry Handling

SoltrOS blocks unapproved container registries by default for security. Helper intelligently manages this during updates:

If you've used unblock-docker, helper temporarily enables secure mode during system updates
After updates complete, it restores your insecure mode setting automatically
This ensures system updates work while preserving your Docker Hub access

Comprehensive Update Process

The helper update command is comprehensive, updating:

System - bootc upgrade for the latest SoltrOS image
Flatpaks - All installed Flatpak applications
Distrobox containers - Upgrades all distrobox environments
Toolbox containers - Updates packages in all toolbox containers

Safe Shell Switching

When you switch shells using helper, it:

Changes your default shell with chsh
Downloads the latest SoltrOS configuration for that shell
Applies the configuration automatically
Ensures a consistent SoltrOS experience

How It Works

Helper.sh is installed to /usr/share/soltros/bin/helper.sh as part of the base system image. It's shipped from the SoltrOS component repository and updated with each system release.

Immutable by Design

Because SoltrOS is immutable, helper.sh itself cannot be modified on your running system. Any updates to helper come through official system updates, ensuring consistency and reliability. If you want to experiment with modifications, you can copy it to your home directory.

Best Practices

Run updates regularly - Use helper update to keep everything current
Clean periodically - Run helper clean to free up disk space
Use helper for system changes - It handles immutable system complexities for you
Check available commands - New features are added regularly via system updates
Reboot after kernel changes - Commands like enable-amdgpu-oc require a reboot

Getting Help

If you need help with any command:

      helper help            # Show all available commands
helper list            # List commands in compact format
    

For issues or feature requests, visit our GitHub repository and open an issue with details about what you'd like to see added or improved.

💡 Pro Tip: Helper Off

If you're comfortable with SoltrOS and don't need the helper reminder in your Zsh prompt, run:

helper helper-off

To re-enable the reminder, simply delete ~/.no-helper-reminder

The Future: GUI Frontend

While helper.sh provides powerful command-line functionality, we understand not everyone prefers terminals. A graphical frontend is in active development using Go and the Fyne toolkit. This GUI will:

Provide all helper.sh functionality through an intuitive interface
Show real-time progress for long-running operations
Include visual system information and status displays
Offer guided wizards for complex operations
Maintain the same reliability and system integration

The GUI frontend will complement helper.sh, not replace it. Command-line users will always have the full-featured Bash script available, while those who prefer graphical interfaces will have an equally powerful option.