# How to Manage Themes in Omarchy: A Complete Guide to CLI Tools and Configuration

> Learn to manage Omarchy themes effortlessly using CLI tools and configuration. Our guide covers installation, switching, and refreshing themes with ease.

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

---

**Omarchy manages themes through a modular architecture of definition files, template engines, and dedicated CLI utilities that handle installation, switching, and refresh operations.**

The theming system in the **omacom/omarchy** repository provides comprehensive tools to customize your desktop environment. You can switch between pre-installed themes, install new ones from remote repositories, or create custom themes using template files. This guide explains how to manage themes in Omarchy using the command-line interface and underlying configuration files.

## Understanding the Omarchy Theme Architecture

Before executing commands, it helps to understand how Omarchy structures its theming system across three core components.

### Theme Definition Files

Each theme resides in a dedicated subdirectory under `themes/`, containing **`.theme` files** that follow the XDG desktop theme specification. These files define visual assets for specific applications—for example, `icons.theme`, `chromium.theme`, or `btop.theme`. When you activate a theme, these definition files are copied into your user configuration directories. Explore the theme collection in the repository at [`themes/`](https://github.com/omacom/omarchy/tree/quattro/themes).

### Template System with Variable Substitution

Default theme templates are stored in [`default/themed/`](https://github.com/omacom/omarchy/tree/quattro/default/themed). These templates use `{{ variable }}` placeholders that expand dynamically during theme installation. This system allows themes to inherit base configurations while substituting color values, font names, or icon paths specific to the selected theme.

### Installation Scripts and Safety Mechanisms

The [[`install/user/theme.sh`](https://github.com/omacom/omarchy/blob/main/install/user/theme.sh)](https://github.com/omacom/omarchy/blob/quattro/install/user/theme.sh) script performs the actual deployment of theme files. It creates backups of existing configurations before overwriting them, copies `.theme` files to appropriate XDG directories, and executes post-installation hooks. For first-time setup, the helper script [[`install/user/first-run/gnome-theme.sh`](https://github.com/omacom/omarchy/blob/main/install/user/first-run/gnome-theme.sh)](https://github.com/omacom/omarchy/blob/quattro/install/user/first-run/gnome-theme.sh) initializes the theming environment.

## Core CLI Commands to Manage Themes in Omarchy

All theme operations are exposed through the `omarchy-theme-*` command family located in the `bin/` directory. These utilities provide a consistent, scriptable interface for theme management.

- **`omarchy-theme-list`** – Displays all themes currently installed in the system. Source: [`bin/omarchy-theme-list`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-list).

- **`omarchy-theme-set <name>``** – Activates the specified theme by copying its definition files and running template expansion. Source: [`bin/omarchy-theme-set`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-set).

- **`omarchy-theme-install <git-url>``** – Clones a remote theme repository into the local themes directory and registers it for use. Source: [`bin/omarchy-theme-install`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-install).

- **`omarchy-theme-remove <name>``** – Safely removes a theme directory and cleans up associated configuration files. Source: [`bin/omarchy-theme-remove`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-remove).

- **`omarchy-theme-refresh`**** – Re-copies default configurations for the currently active theme, useful after manually editing theme files. Source: [`bin/omarchy-theme-refresh`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-refresh).

- **`omarchy-theme-bg-*` family`** – Manages background-specific themes, including `omarchy-theme-bg-set` and `omarchy-theme-bg-next` for cycling wallpaper collections.

## Advanced Theme Operations

Beyond basic switching, Omarchy supports custom theme development, remote installation, and automated hooks.

### Installing Custom Themes from Git Repositories

You can extend your theme library by installing community-created themes directly from Git repositories. The installation command handles cloning, verification, and registration automatically.

```bash

# Install a community theme from GitHub

omarchy-theme-install https://github.com/username/custom-omarchy-theme.git

# Verify the installation

omarchy-theme-list

```

### Refreshing Active Themes After Modifications

When you edit theme files directly in `~/.config/omarchy/themes/`, those changes do not apply immediately to running applications. The refresh command re-processes templates and re-copies configuration files without requiring a full theme switch.

```bash

# Apply changes after editing current theme files

omarchy-theme-refresh

```

### Hook Scripts and Desktop Notifications

Omarchy executes hook scripts stored in [`config/omarchy/hooks/theme-set.d/`](https://github.com/omacom/omarchy/tree/quattro/config/omarchy/hooks/theme-set.d) whenever you change themes. The sample file `show-theme-notification.sample` demonstrates emitting desktop notifications upon theme switches. You can create custom hooks by placing executable scripts in this directory.

## Practical Examples for Managing Omarchy Themes

Here are common workflows for daily theme management:

```bash

# View all available themes before switching

omarchy-theme-list

# Switch to the Nord color scheme

omarchy-theme-set nord

# Test a new theme without permanently installing it

omarchy-theme-install https://github.com/arcticicestudio/nord-omarchy.git
omarchy-theme-set nord-omarchy

# Revert to default after testing

omarchy-theme-set default
omarchy-theme-remove nord-omarchy

# Cycle to the next background in the current theme

omarchy-theme-bg-next

```

## Summary

- **Theme definitions** reside in `themes/` as `.theme` files following XDG specifications.
- **Templates** in `default/themed/` use `{{ variables }}` for dynamic configuration generation.
- **Core scripts** like [`install/user/theme.sh`](https://github.com/omacom/omarchy/blob/main/install/user/theme.sh) handle safe deployment with backup creation.
- **CLI utilities** provide complete control: `omarchy-theme-list`, `omarchy-theme-set`, `omarchy-theme-install`, `omarchy-theme-remove`, and `omarchy-theme-refresh`.
- **Hooks** in `config/omarchy/hooks/theme-set.d/` enable automated actions during theme switches.
- **Documentation** at [[`manual/06-themes.md`](https://github.com/omacom/omarchy/blob/main/manual/06-themes.md)](https://github.com/omacom/omarchy/blob/quattro/manual/06-themes.md) provides additional user guidance.

## Frequently Asked Questions

### How do I list available themes in Omarchy?

Execute the `omarchy-theme-list` command in your terminal. This utility scans the `themes/` directory and displays all installed theme names, including system defaults and user-installed custom themes.

### What is the difference between omarchy-theme-set and omarchy-theme-refresh?

`omarchy-theme-set <name>` switches to a different theme entirely, copying all definition files and running template expansion. `omarchy-theme-refresh` re-applies the current theme's configuration files without changing themes, useful for applying manual edits you made to active theme files.

### Where are theme files stored in Omarchy?

Theme definition files are stored in the `themes/` subdirectory of the Omarchy installation. When activated, these files are copied to your user configuration directories (typically under `~/.config/`). The template source files remain in `default/themed/` for reference and customization.

### How do I create a custom theme for Omarchy?

Create a new directory under `themes/` with your theme name, add `.theme` files for each application you want to style, and use `{{ variable }}` syntax in templates stored in `default/themed/`. Test your theme locally with `omarchy-theme-set <your-theme-name>`, then share it by pushing to a Git repository that others can install via `omarchy-theme-install`.