ujust Command System#

Lead Section#

The ujust command system is a command-line abstraction layer built on top of the Just task runner that provides user-friendly wrappers for administrative and system operations in Bluefin and other Universal Blue variants. Rather than requiring users to remember complex rpm-ostree, bootc, or systemd commands, ujust presents a curated collection of high-level commands organized into modular recipe files that handle system updates, application installation, system maintenance, and variant management.

ujust is part of the core experience in projectbluefin/common, meaning it ships by default with all Bluefin installations. The system operates within Bluefin's immutable architecture by coordinating across the three-layer package management strategy: immutable system layer updated via bootc, Flatpak for GUI apps, and Homebrew for CLI tools. Commands like ujust update orchestrate updates across all three layers, while ujust bbrew provides an interactive menu for installing curated software bundles validated through automated CI/CD workflows.

The architecture is extensible through optional custom justfiles placed in /usr/share/ublue-os/just/60-custom.just, allowing users to add their own commands without modifying base system files. Commands leverage interactive tools like gum for user-friendly prompts and detect system state to adjust behavior intelligently—for example, choosing between bootc upgrade and rpm-ostree upgrade based on the LockLayering configuration.

Architecture and Design#

Foundation: Just Task Runner#

ujust is built on Just, a command runner similar to Make but designed for running project-specific tasks. The 00-entry.just file serves as the entry point, importing all modular recipe files and defining the default command that lists available commands.

Modular File Organization#

Just recipes are organized into logical modules by function:

• apps.just - Application installation commands (bbrew, jetbrains-toolbox, opentabletdriver, gaming-flatpaks)
• update.just - System update and automatic update management
• system.just - Bluefin-specific system commands (bluefin-cli, toggle-devmode, rebase-helper, powerwash)
• default.just - Generic convenience commands (clean-system, bios, logs, benchmarking)
• shared.just - Commands common to both Bluefin and Aurora
• changelog.just - Release changelog display

Integration with Bluefin's Package Management#

ujust commands bridge Bluefin's three-layer package management architecture:

1. System Layer (Immutable): Updated via bootc, locked by default via LockLayering=true to prevent rpm-ostree package layering
2. Flatpak Layer (GUI Applications): Graphical applications with automatic daily updates
3. Homebrew Layer (CLI Tools): Command-line tools managed in user space

Commands like ujust update orchestrate updates across all three layers without requiring users to understand the underlying mechanisms.

Supporting Scripts#

ujust commands coordinate with several supporting scripts:

• ublue-bling - Terminal enhancements (eza aliases, bat, atuin/starship/zoxide initialization, mise activation)
• ublue-rollback-helper - Interactive interface for switching between Bluefin variants and release channels
• ublue-system-setup - System-level setup hooks execution

Core Commands#

System Management#

ujust update#

Primary system update command that:

1. Checks if automatic updates are currently running
2. Determines update method by examining /etc/rpm-ostreed.conf:
   • Uses bootc upgrade if LockLayering=true (default)
   • Uses rpm-ostree upgrade if package layering is enabled
3. Updates all Flatpaks (system and user remotes)
4. Updates Homebrew packages if Homebrew is installed

Usage: ujust update

ujust toggle-updates#

Manages automatic updates by enabling/disabling systemd timers. Detects current state and toggles the uupd.timer, disabling conflicting timers when enabling.

Usage:

• ujust toggle-updates (toggles based on current state)
• ujust toggle-updates enable
• ujust toggle-updates disable

ujust clean-system#

Comprehensive system cleanup that:

1. Prunes Podman images and volumes (with confirmation)
2. Prunes Docker images and volumes if Docker is installed (with confirmation)
3. Removes unused Flatpaks (flatpak uninstall --unused)
4. Cleans rpm-ostree base images and metadata (rpm-ostree cleanup -bm)
5. Performs Homebrew cleanup if Homebrew is installed

Usage: ujust clean-system

ujust powerwash#

Factory reset command using sudo bootc install reset --experimental. WARNING: This erases all user data.

Usage: ujust powerwash

ujust rebase-helper#

Interactive assistant for switching between Bluefin variants, release channels (gts, stable, latest), and optionally pinning to specific build dates. Runs the ublue-rollback-helper script.

Usage: ujust rebase-helper

Application Installation#

ujust bbrew#

Interactive menu for installing curated application bundles. The command:

1. Checks if bbrew is installed (prompts for installation if missing)
2. Uses gum choose to present an interactive menu
3. Finds all available Brewfiles in /usr/share/ublue-os/homebrew/
4. Executes bbrew with the selected Brewfile

All Brewfiles are validated in CI/CD before distribution to ensure package availability.

Usage: ujust bbrew

ujust bluefin-cli#

Installs the complete CLI development experience by:

1. Running ublue-bling to configure terminal enhancements
2. Installing all packages from cli.Brewfile

Usage: ujust bluefin-cli

ujust install-jetbrains-toolbox#

Downloads and installs JetBrains Toolbox with checksum verification via Homebrew cask.

Usage: ujust install-jetbrains-toolbox or ujust jetbrains-toolbox

ujust install-opentabletdriver#

Installs/uninstalls OpenTabletDriver with udev rules and kernel module configuration for graphics tablet support.

Usage: ujust install-opentabletdriver

ujust install-gaming-flatpaks#

Installs gaming-related Flatpak applications: Steam, Heroic Games Launcher, Lutris, ProtonPlus.

Usage: ujust install-gaming-flatpaks

System Configuration#

ujust toggle-tpm2#

Toggles TPM2-based LUKS auto-unlock for encrypted disks with optional PIN via systemd-cryptenroll.

Usage: ujust toggle-tpm2

ujust toggle-user-motd#

Controls MOTD banner display by creating/removing $HOME/.config/no-show-user-motd.

Usage: ujust toggle-user-motd

Curated Software Bundles (Brewfiles)#

Brewfiles use Homebrew's declarative bundle format with four entry types:

• tap: Custom Homebrew repository references
• brew: CLI tools and command-line applications
• cask: GUI applications and binaries
• flatpak: Graphical applications via Flatpak (bbrew extension)

Available Bundles#

Usage Examples#

Basic Usage#

# List available commands
ujust --list

# See help for specific command
ujust --help update

# Run a command
ujust update

System Maintenance Workflow#

# Check for and apply updates
ujust update

# Clean up unused resources
ujust clean-system

# Enable automatic updates
ujust toggle-updates enable

Application Installation Workflows#

# Install CLI tools directly
ujust bluefin-cli

# Interactive bundle installation
ujust bbrew
# Select "ai-tools" for AI/ML development
# Select "k8s-tools" for Kubernetes operations
# Select "cncf" for comprehensive cloud-native ecosystem

# Install specific applications
ujust install-gaming-flatpaks
ujust install-jetbrains-toolbox

Development Environment Setup#

# Install IDE bundle
ujust bbrew # Select "ide"

# Install language-specific tools
ujust bbrew # Select "swift" or other language bundle

# Install CLI development tools
ujust bluefin-cli

Configuration and Customization#

Custom Just Recipes#

Users can extend ujust by creating /usr/share/ublue-os/just/60-custom.just with custom recipes:

# /usr/share/ublue-os/just/60-custom.just

@my-custom-command:
    echo "Custom command running"
    # Add your recipe logic here

The file will be automatically imported if present, enabling local customization without modifying base system files.

Automatic Update Scheduling#

Automatic updates are managed via the uupd.timer systemd timer, enabled by default through systemd presets. Users can customize the schedule:

# Edit the timer schedule
sudo systemctl edit uupd.timer

# Add custom override (e.g., run at 3 AM daily)
[Timer]
OnCalendar=
OnCalendar=03:00

Relationship to Universal Blue and Bluefin#

Universal Blue Integration#

ujust commands are shared across all Universal Blue variants through projectbluefin/common, meaning the same commands work identically on:

• Bluefin
• Aurora
• Bazzite
• uCore

Cross-variant commands like ujust install-gaming-flatpaks work identically across all variants, enabling shared workflows and documentation.

Bluefin System Administration Layer#

ujust is the primary user interface for system administration in Bluefin, replacing direct use of lower-level tools:

• Instead of bootc upgrade or rpm-ostree upgrade: Use ujust update
• Instead of manually managing Flatpak and Homebrew updates: Use ujust update (coordinates all updates)
• Instead of systemctl enable/disable uupd.timer: Use ujust toggle-updates
• Instead of manually pruning containers and Flatpaks: Use ujust clean-system

This abstraction layer provides consistency, safety checks, and user-friendly prompts while maintaining the flexibility to access underlying tools when needed.

Related Technologies#

• Just - Task runner underlying ujust recipes
• bootc - Container-native bootable operating system mechanism used for system updates
• rpm-ostree - Fallback update system when package layering is enabled
• Flatpak - Application installation layer for GUI applications
• Homebrew - Package manager for CLI tools, installed in user space
• bbrew - Wrapper tool enabling Homebrew bundles to install Flatpak applications
• gum - Interactive prompt library used in ujust commands
• systemd timers - Scheduled update execution (uupd.timer)

Relevant Code Files#

See Also#

• Curated Software Distribution - Detailed information about Brewfile bundles
• Update Process - Technical details of the update mechanism
• Bluefin OS - Complete Bluefin system documentation
• rpm-ostree and bootc - Underlying image-based OS technologies
• Official ujust Commands Reference - Complete command listing