# How to Apply a Theme to the Omarchy Shell

> Easily apply a theme to the Omarchy shell using the omarchy-theme-set utility and applyTheme IPC command. Customize your interface instantly without restarting your shell.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-08-30

---

**To apply a theme to the Omarchy shell, use the `omarchy-theme-set` utility to base64-encode the theme's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) files and transmit them via the `applyTheme` IPC command, which updates the interface instantly without requiring a shell restart.**

Omarchy is a desktop shell environment where visual styling is controlled through **TOML** configuration files. When you apply a theme to the Omarchy shell, the system decodes **base64**-encoded payloads and injects them into the running **QML** interface through an **IPC** layer. This architectural design allows zero-downtime theme switching while preserving active applications and window states.

## Theme File Structure and Location

Every theme resides in a subdirectory under `themes/` and requires two specific TOML files:

- **[`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)** – Defines the color palette including foreground, background, and accent values.
- **[`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml)** – Configures shell-specific settings such as bar transparency, widget placement, and font tokens.

These files serve as the source of truth for the **[Color](https://github.com/omacom/omarchy/blob/quattro/shell/Commons/Color.qml)** module, which parses them at runtime to update the interface.

## The IPC-Based Theme Application Architecture

When you initiate a theme change, the shell follows a strict IPC pipeline to ensure atomic updates. According to the [Omarchy source code](https://github.com/omacom/omarchy), the process works as follows:

1. **Encoding**: The [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) files are base64-encoded into strings.
2. **Transmission**: The encoded payloads are sent via the `applyTheme` IPC command.
3. **Decoding and Loading**: In [`shell/shell.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/shell.qml#L879-L887), the `applyTheme` handler decodes the strings and invokes `Color.loadColors()` and `Color.loadShell()`.
4. **UI Refresh**: The system calls `Style.scheduleRefresh()` to repaint affected components without restarting the shell session.

This flow ensures that when you apply a theme to the Omarchy shell, the transition is instantaneous and non-destructive.

## Three Methods to Apply a Theme

You can apply a theme using the provided CLI wrapper, manual IPC commands, or programmatic QML calls.

### Method 1: Using the CLI Helper (Recommended)

The `bin/omarchy-theme-set` wrapper automates base64 encoding and IPC transmission. Located at [`bin/omarchy-theme-set`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-set), this script handles the heavy lifting around lines 112-129.

To apply a theme:

```bash
omarchy-theme-set solitude

```

The script locates [`themes/solitude/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/solitude/colors.toml) and [`themes/solitude/shell.toml`](https://github.com/omacom/omarchy/blob/main/themes/solitude/shell.toml), encodes them, and dispatches the `applyTheme` command automatically.

### Method 2: Manual Base64 Encoding and IPC

For advanced use cases or custom theme paths, manually encode the files and invoke the IPC command directly:

```bash

# Encode theme files as base64 (wrap=0 for single-line strings)

colors_b64=$(base64 -w0 themes/solitude/colors.toml)
shell_b64=$(base64 -w0 themes/solitude/shell.toml)

# Send via omarchy-shell IPC

omarchy-shell applyTheme "$colors_b64" "$shell_b64"

```

This bypasses the helper script and sends raw payloads directly to the shell's IPC handler at [`shell/shell.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/shell.qml#L879-L887).

### Method 3: Programmatic Application from QML

Within the shell's QML environment, trigger theme changes using the `shell_ipc` object:

```qml
// Inside any QML component with shell_ipc access
shell_ipc.shell.applyTheme(colorsBase64, shellBase64)

```

This method integrates theme switching directly into custom widgets or settings panels, referencing the same `applyTheme` logic implemented in the core shell.

## Key Source Files and Functions

| File | Role | Key Functions |
|------|------|---------------|
| [`shell/shell.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/shell.qml#L879-L887) | IPC handler for `applyTheme` command | Decodes base64, calls `Color.loadColors()` and `Color.loadShell()`, triggers `Style.scheduleRefresh()` |
| [`shell/Commons/Color.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/Commons/Color.qml) | Theme state management | `loadColors()`, `loadShell()`, stores config in `currentThemePath` |
| [`bin/omarchy-theme-set`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-set) | CLI automation | Encodes TOML files and invokes IPC (lines 112-129) |
| [[`docs/omarchy-shell.md`](https://github.com/omacom/omarchy/blob/main/docs/omarchy-shell.md)](https://github.com/omacom/omarchy/blob/quattro/docs/omarchy-shell.md) | Command reference | Documents `applyTheme` parameters and usage |

## Summary

Applying a theme to the Omarchy shell involves encoding TOML configuration files and transmitting them through the IPC layer. Key takeaways include:

- **Theme Structure**: Every theme requires [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) in a `themes/<name>/` directory.
- **IPC Command**: The `applyTheme` command accepts base64-encoded strings and processes them in `shell/shell.qml` (lines 879-887).
- **Zero-Downtime Updates**: The **Color** module parses themes and refreshes the UI via `Style.scheduleRefresh()` without restarting the shell.
- **CLI Convenience**: Use `omarchy-theme-set <theme-name>` for automated application, or manually encode files and call `omarchy-shell applyTheme` for custom implementations.

## Frequently Asked Questions

### Do I need to restart the Omarchy shell after applying a theme?

No. The Omarchy shell applies themes dynamically through its IPC layer. When you send the `applyTheme` command, the shell immediately decodes the base64 payloads, parses the TOML configuration via `Color.loadColors()` and `Color.loadShell()`, and schedules a UI refresh. Your applications and window states remain intact throughout the process.

### What files are required to apply a theme to the Omarchy shell?

Every valid theme requires exactly two TOML files located in `themes/<theme-name>/`: [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) for the palette definitions and [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) for layout and transparency settings. Both files must be base64-encoded and sent together via the `applyTheme` IPC command to ensure consistent styling.

### Can I apply a theme from a custom directory outside of `themes/`?

Yes. While the `omarchy-theme-set` helper looks in the standard `themes/` directory, you can apply a theme from any location by manually base64-encoding your [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) files and passing them as arguments to `omarchy-shell applyTheme`. This allows testing themes without moving them into the system themes folder.

### Where is the active theme configuration stored after application?

The active theme configuration is stored in memory by the **Color** module, specifically in the `currentThemePath` property defined in [`shell/Commons/Color.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/Commons/Color.qml). The shell does not write the applied theme back to disk; it maintains the parsed TOML values in runtime memory for the UI to reference via QML property bindings.