How to Apply a Theme in Omarchy: Complete CLI Guide

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

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

The command excludes any folders missing a valid 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:

omarchy-theme-apply rose-pine

According to the implementation in default/agents/skills/omarchy/theming.md, this command performs three operations: it validates that the theme exists, copies the source 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:

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. The script first checks that the requested theme folder exists under themes/ and that it contains a valid 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 file with all required keys. Example structure:

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:

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

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