How `omarchy-plymouth-set-by-theme` Generates Boot Screens: A Deep Source Code Analysis

omarchy-plymouth-set-by-theme is a thin wrapper script that transforms an Omarchy theme into a Plymouth boot splash by resolving theme directories, extracting color values from colors.toml, and delegating security-critical operations to the privileged helper omarchy-plymouth-set.

The omarch/omarchy repository provides a streamlined mechanism for users to customize their boot experience without manual Plymouth configuration. The omarchy-plymouth-set-by-theme script acts as the primary interface, converting high-level theme names into fully rendered boot screens through a carefully layered architecture that separates user-facing convenience from privileged system operations.

---

How omarchy-plymouth-set-by-theme Works

The script operates through three distinct stages, each implemented in bin/omarchy-plymouth-set-by-theme.

Stage 1: Resolve the Theme Directory

The script first locates the requested theme on disk by calling the helper utility omarchy-theme-dir.

# From bin/omarchy-plymouth-set-by-theme (lines 17-18)

theme_dir=$(omarchy-theme-dir "$1")

This returns the absolute path to the theme directory, ensuring consistent resolution regardless of where the command is invoked from.

Stage 2: Extract Color Values from colors.toml

The script defines a local theme_color function that parses the theme's colors.toml configuration file using awk. This function:

• Searches for a specified key (e.g., background or foreground)
• Falls back to a secondary key if the primary is missing
• Strips surrounding quotes and whitespace from values

# From bin/omarchy-plymouth-set-by-theme (lines 19-48)

theme_color() {
    local key="$1"
    local fallback="$2"
    local file="$theme_dir/colors.toml"
    
    # awk-based extraction with fallback logic

    # ...

}

This extraction yields the hexadecimal color values required for Plymouth's visual configuration.

Stage 3: Delegate to the Privileged Setter

With colors and logo path assembled, the script invokes omarchy-plymouth-set with validated arguments:

# From bin/omarchy-plymouth-set-by-theme (lines 50-53)

omarchy-plymouth-set \
    "$(theme_color background bg)" \
    "$(theme_color foreground fg)" \
    "$theme_dir/unlock.png"

All security-sensitive operations occur within omarchy-plymouth-set, keeping the wrapper unprivileged and simple.

---

Security Architecture of omarchy-plymouth-set

The privileged helper bin/omarchy-plymouth-set (lines 19-40) implements multiple defense-in-depth mechanisms:

Input validation — Hex color strings must strictly match the pattern ^[0-9a-fA-F]{6}$. Any deviation causes immediate rejection.

Logo path safety — The script opens the logo file as the unprivileged user before any sudo escalation, ensuring root never follows a user-controlled path that could be swapped for a malicious target.

Atomic publishing — The root-owned transaction:

1. Creates a temporary directory
2. Copies the logo into place
3. Updates Plymouth's configuration
4. Swaps the complete theme atomically

This guarantees the boot screen is never in a partially configured state.

---

Usage Examples

Apply the currently active theme's Plymouth splash:

omarchy-plymouth-set-by-theme "$(omarchy-theme-current)"

Specify a theme explicitly:

omarchy-plymouth-set-by-theme catppuccin-mocha

Both commands ultimately resolve to arguments similar to:

omarchy-plymouth-set '#1d2021' '#ebdbb2' /home/user/.local/state/omarchy/current/theme/catppuccin-mocha/unlock.png

---

Key Files in the Boot Screen Pipeline

File	Purpose
bin/omarchy-plymouth-set-by-theme	User-facing wrapper that orchestrates theme-to-Plymouth conversion
bin/omarchy-plymouth-set	Privileged helper performing validation and atomic theme deployment
test/shell.d/plymouth-set-test.sh	Automated tests verifying security checks and correct behavior
default/omarchy/omarchy-menu.jsonc	Integrates the command into the Omarchy menu system
etc/plymouth/plymouthd.conf	Default Plymouth configuration fallback

---

Summary

• omarchy-plymouth-set-by-theme serves as the entry point, resolving themes and extracting colors from colors.toml
• Three-stage pipeline: directory resolution → color extraction → privileged delegation
• omarchy-plymouth-set handles all root operations with strict input validation, safe file opening, and atomic deployment
• The architecture separates concerns cleanly, allowing unprivileged users to change boot screens without compromising system security
• All operations are testable via test/shell.d/plymouth-set-test.sh

---

Frequently Asked Questions

What is Plymouth and why does Omarchy wrap it?

Plymouth is the standard Linux boot splash framework that displays graphical screens during early boot before the display manager loads. Omarchy wraps Plymouth to provide theme consistency—users select one theme name, and both their desktop environment and boot screen update automatically without manual configuration file editing.

Can I use omarchy-plymouth-set-by-theme without sudo?

The wrapper itself runs without privileges, but it internally calls omarchy-plymouth-set which requires root access to modify Plymouth's system directories. As implemented in omarch/omarchy, this escalation is handled safely through pre-validation and secure file opening patterns.

What happens if my theme's colors.toml is missing a background key?

The theme_color function in omarchy-plymouth-set-by-theme implements fallback logic. If the primary key (e.g., background) is absent, it automatically attempts the secondary key (e.g., bg). If both fail, the behavior depends on omarchy-plymouth-set's validation, which may reject the empty value.

How do I verify my boot screen changes worked correctly?

After running omarchy-plymouth-set-by-theme, you can test the configuration without rebooting by using Plymouth's test mode: plymouthd ; plymouth --show-splash ; sleep 5 ; plymouth --quit. For automated validation, reference test/shell.d/plymouth-set-test.sh in the omarch/omarchy repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}