How to Apply a Theme in Omarchy: CLI, Menu, and Hotkey Methods

Run omarchy theme set "<theme-name>" or press Super + Ctrl + Shift + Space to open the theme picker and instantly activate a new look across your entire desktop.

Omarchy is a declarative desktop environment that unifies theming across terminals, window managers, and applications through a centralized activation pipeline. Whether you prefer command-line precision or graphical menus, applying a theme in Omarchy follows the same robust four-stage process defined in the bin/omarchy-theme-set executable.

Where Omarchy Stores Themes

Omarchy discovers themes in two distinct scopes. System-wide themes live at /usr/share/omarchy/themes/<name>/, while user-specific overrides reside in ~/.config/omarchy/themes/<name>/. Each theme directory contains a colors.toml palette and associated template files that define the visual appearance.

When you invoke a theme change, the system does not modify these source directories directly. Instead, bin/omarchy-theme-set creates a clean staging area at ~/.local/state/omarchy/current/next-theme to prepare the transition.

The Theme Activation Pipeline

The omarchy-theme-set script executes a deterministic four-step pipeline to ensure atomic theme application. Understanding this flow helps debug issues and customize post-activation behavior.

Stage 1: Staging the Theme

The activation begins by populating the staging directory with base theme files merged with any user overrides. This isolation prevents partial updates from corrupting the live desktop state. The staging location at ~/.local/state/omarchy/current/next-theme serves as a temporary workspace where files are validated before promotion.

Stage 2: Rendering Templates

Once staged, the omarchy-theme-set-templates helper processes all default/themed/*.tpl files. It expands template placeholders using values from the theme’s colors.toml, generating concrete configuration files for applications like Hyprland, btop, and terminal emulators. This template engine ensures every application receives consistent color values without manual configuration file editing.

Stage 3: Swapping the Live Theme

After successful rendering, the script performs an atomic move operation, transferring the staged content to ~/.local/state/omarchy/current/theme. Simultaneously, it writes the theme name to theme.name and manages a lock-file to prevent race conditions during rapid successive changes. This swap is instantaneous and does not require closing applications.

Stage 4: Notifying the Running Shell

Finally, the pipeline triggers the theme-set hook located at ~/.config/omarchy/hooks/theme-set*. This hook mechanism broadcasts the change to the running shell and executes post-theme commands that restart or retint affected applications, including the terminal, status bar, browsers, and editors.

How to Apply a Theme Using the CLI

The command-line interface provides the most explicit control over theme activation and is ideal for scripting or precise selection.

Listing Available Themes

Before applying a theme, enumerate the installed options:

omarchy theme list

This command scans both system and user theme directories, presenting valid names that can be passed to the setter.

Setting a Theme Interactively

To apply a specific theme immediately, use the omarchy theme set subcommand:

omarchy theme set "Tokyo Night"

This internally invokes omarchy-theme-set "Tokyo Night", executing the full activation pipeline including staging, template rendering, and shell notification.

Headless Mode for Scripts

When automating theme changes from login scripts or cron jobs, suppress interactive UI updates by setting the OMARCHY_THEME_HEADLESS environment variable:

OMARCHY_THEME_HEADLESS=1 omarchy-theme-set "Tokyo Night"

This mode is demonstrated in install/user/theme.sh, which shows how to set a default theme during user login without graphical feedback.

How to Apply a Theme Using the Omarchy Menu

For graphical selection, the Omarchy menu provides intuitive navigation and hotkey shortcuts.

Using the Style Menu

1. Press Super + Space to open the Omarchy menu.
2. Navigate to Style → Theme (icon 󰸌).
3. Select your desired theme from the list.

The menu entry executes the following logic defined in default/omarchy/omarchy-menu.jsonc:

theme=$(omarchy-theme-switcher); [[ -n $theme ]] && omarchy-theme-set "$theme"

The omarchy-theme-switcher utility presents the selection interface, then pipes the chosen value to the setter.

Direct Hotkey Access

Bypass the menu hierarchy entirely by pressing Super + Ctrl + Shift + Space. This hotkey opens the theme picker directly; upon selection, the picker automatically invokes omarchy-theme-set with your choice.

Advanced: Using the Theme Switcher

The omarchy-theme-switcher binary provides a programmable interface for theme selection. While typically invoked by the menu system, you can use it manually in shell scripts:

theme=$(omarchy-theme-switcher) && [[ -n $theme ]] && omarchy-theme-set "$theme"

This pattern allows background plugins or status bars to offer theme switching capabilities without hardcoding theme names.

Customizing the Post-Theme Hook

After omarchy-theme-set completes the core pipeline, it executes any scripts matching ~/.config/omarchy/hooks/theme-set*. Place custom executable scripts here to handle application-specific retinting, such as reloading Neovim’s colorscheme via remote commands or restarting a custom compositor. The hook receives the environment context necessary to identify the newly activated theme.

Summary

• Theme locations: System themes reside in /usr/share/omarchy/themes/<name>/ and user themes in ~/.config/omarchy/themes/<name>/.
• Core command: bin/omarchy-theme-set drives the activation pipeline through staging, template rendering, atomic swapping, and shell notification.
• CLI method: Use omarchy theme set "<name>" for direct activation or OMARCHY_THEME_HEADLESS=1 omarchy-theme-set "<name>" for scripts.
• Graphical method: Press Super + Ctrl + Shift + Space or navigate to Style → Theme in the Omarchy menu (Super + Space).
• Customization: Add post-activation scripts to ~/.config/omarchy/hooks/theme-set* for application-specific updates.

Frequently Asked Questions

Where does Omarchy store the currently active theme?

The active theme files live in ~/.local/state/omarchy/current/theme/, while the theme name is recorded in theme.name within that directory. This state directory is populated atomically during the swap stage of the activation pipeline to ensure the desktop never references partially written configuration files.

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

omarchy-theme-set is the low-level executable located at bin/omarchy-theme-set that executes the four-stage activation pipeline. omarchy theme set is the high-level CLI subcommand that wraps the executable, providing a consistent interface with other omarchy management commands. Both initiate the same staging, rendering, and notification process.

How do I apply a theme automatically when I log in?

Create a login script that exports OMARCHY_THEME_HEADLESS=1 and calls omarchy-theme-set "<your-theme>". The install/user/theme.sh file in the Omarchy repository demonstrates this pattern, ensuring the theme applies silently without interactive prompts during session initialization.

Can I preview a theme before fully applying it?

The standard Omarchy workflow does not provide a separate preview mechanism; the staging pipeline at ~/.local/state/omarchy/current/next-theme prepares files atomically before the swap. However, the omarchy-theme-switcher interface allows you to browse available themes visually before confirming the selection, at which point the change applies immediately across all configured applications.

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