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

> Discover how omarchy-plymouth-set-by-theme generates boot screens. This analysis dives into source code, revealing how it transforms Omarchy themes into Plymouth splashes.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-06

---

**`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`](https://github.com/omacom/omarchy/blob/main/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`.

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/colors.toml)

The script defines a local `theme_color` function that parses the theme's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/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

```bash

# 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:

```bash

# 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:

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

```

Specify a theme explicitly:

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

```

Both commands ultimately resolve to arguments similar to:

```bash
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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/test/shell.d/plymouth-set-test.sh) in the omarch/omarchy repository.