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

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/.

Template System with Variable Substitution

Default theme templates are stored in 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/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/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.

• **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.

• **omarchy-theme-bg-* family** – Manages background-specific themes, including omarchy-theme-bg-setandomarchy-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.

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

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

# 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 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/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.

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