# How to Apply a Theme in Omarchy: Complete CLI Guide

> Apply a theme in Omarchy using the command line. Switch color palettes for Hyprland, Quickshell, and GTK/Qt apps instantly with the omarchy-theme-apply command.

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

---

**Use the `omarchy-theme-apply` command followed by the theme name to instantly switch color palettes across Hyprland, Quickshell, and GTK/Qt applications.**

Omarchy is a declarative Linux desktop environment built on Hyprland and Quickshell. Changing its visual appearance is handled entirely through the command line using the built-in theming system. The repository `omacom/omarchy` stores theme definitions in the `themes/` directory and provides dedicated CLI tools to activate them.

## Understanding Omarchy Theme Structure

Before you apply a theme in Omarchy, it helps to understand how the system organizes visual assets.

### Theme Directory Layout

Omarchy themes are self-contained packages located under the `themes/` directory in the repository root. Each theme folder must contain a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file that defines the palette. Optional assets such as icons, wallpapers, or font configurations can be bundled within the same folder. When you run the apply command, the system reads from this location to validate and activate the requested theme.

### The colors.toml Specification

The core of every theme is the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file. This configuration defines standard keys including `accent`, `background`, `foreground`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, and their bright variants (`bright_red`, etc.). These values are written as hexadecimal color codes. The file follows a strict schema that the validation logic in [`default/agents/skills/omarchy/theming.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/theming.md) checks before activation.

## How to Apply a Theme in Omarchy (CLI Workflow)

Switching themes requires three steps: selecting the theme, running the activation command, and allowing the system to refresh dependent configurations.

### Listing Available Themes

To see which themes are installed, run the list command. This utility scans the `themes/` directory and outputs valid theme names.

```bash
omarchy-theme-list
#> default  rose-pine  nord  dracula

```

The command excludes any folders missing a valid [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file, ensuring only functional themes appear in the output.

### Activating a Theme via CLI

To apply a theme in Omarchy, invoke the `omarchy-theme-apply` utility with the theme name as the sole argument. For example, to switch to the `rose-pine` theme:

```bash
omarchy-theme-apply rose-pine

```

According to the implementation in [`default/agents/skills/omarchy/theming.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/theming.md), this command performs three operations: it validates that the theme exists, copies the source [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) to `~/.config/omarchy/theme/colors.toml`, and triggers a cascade of configuration refreshes for all subsystems.

### Verifying the Active Theme

To confirm which theme is currently active, use the current command:

```bash
omarchy-theme-current
#> rose-pine

```

This reads the symlink or metadata written during the last successful apply operation.

## How the Theme System Works (Deep Dive)

Understanding the internals helps troubleshoot issues when you apply a theme in Omarchy.

### The omarchy-theme-apply Implementation

The `omarchy-theme-apply` command is implemented as an Omarchy skill defined in [`default/agents/skills/omarchy/theming.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/theming.md). The script first checks that the requested theme folder exists under `themes/` and that it contains a valid [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). If validation passes, it copies the color file to the user's configuration directory and records the active theme name. This source file acts as the single source of truth for all UI components.

### Configuration Refresh Mechanism

After copying the color file, the skill invokes `omarchy-refresh-config` for every dependent component. This utility ensures that **Hyprland** reloads its window border and decoration settings, **Quickshell** re-sources its QML UI (reading colors via `theme.colors`), and **GTK/Qt** toolkits pick up the updated palette on the next widget draw. The refresh logic preserves manual edits to configuration files, only touching values that exist in the theme definition.

## Creating and Applying Custom Themes

You can extend Omarchy by creating custom theme packages and applying them using the same CLI workflow.

### Custom Theme Requirements

To create a valid custom theme:

1. Create a new directory under `themes/`, for example `themes/midnight/`.
2. Add a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file with all required keys. Example structure:

```toml
accent = "#ff6600"
background = "#1e1e2e"
foreground = "#cdd6f4"
red = "#f38ba8"
green = "#a6e3a1"
yellow = "#f9e2af"
blue = "#89b4fa"
magenta = "#f5c2e7"
cyan = "#94e2d5"
bright_red = "#f38ba8"

# ... additional bright variants

```

3. Apply the theme using the standard command:

```bash
omarchy-theme-apply midnight

```

### Adding Assets and Advanced Configuration

Advanced themes can include wallpaper images or icon sets within the theme folder. While the primary [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file is mandatory, auxiliary files referenced by custom Quickshell widgets or Hyprland configurations can be placed alongside it. When `omarchy-theme-apply` runs, it copies the entire theme folder contents, ensuring that relative paths in your configuration remain valid.

## Summary

Applying a theme in Omarchy is a streamlined, CLI-driven process that centralizes color management through the `omarchy-theme-apply` command. Key takeaways include:

- **Themes reside in `themes/`**: Each theme is a folder containing a mandatory [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and optional assets.
- **Single command activation**: Running `omarchy-theme-apply <name>` validates, copies, and activates the theme instantly.
- **Automatic cascading refresh**: The system updates Hyprland, Quickshell, and GTK/Qt configurations without requiring manual restarts.
- **Custom themes supported**: Creating a new theme requires only a valid [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file and placement in the themes directory.

## Frequently Asked Questions

### Where are Omarchy themes stored?

Omarchy themes are stored in the `themes/` directory at the repository root. Each theme occupies its own subfolder, such as `themes/rose-pine/` or `themes/nord/`. The system scans this location when you run `omarchy-theme-list` or `omarchy-theme-apply`.

### What file format does Omarchy use for color definitions?

Omarchy uses **TOML** files named [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) to define color palettes. These files must specify standard keys like `accent`, `background`, `foreground`, and ANSI color codes including their bright variants. The schema is validated by the theming skill before activation.

### Do I need to restart Hyprland after applying a theme?

No. When you apply a theme in Omarchy using `omarchy-theme-apply`, the command automatically invokes `omarchy-refresh-config` for Hyprland and other components. This reloads configurations in-place, updating window borders, bar colors, and UI elements immediately without closing applications or logging out.

### Can I override specific colors without creating a full theme?

The standard workflow requires a complete [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file. However, after applying a base theme, you can manually edit `~/.config/omarchy/theme/colors.toml`. Running `omarchy-refresh-config` will propagate those changes. For permanent overrides, it is recommended to create a custom theme folder rather than modifying the active configuration directly, as the apply command may overwrite manual edits on subsequent runs.