# How to Apply a Theme in Omarchy: CLI, Menu, and Hotkey Methods > Learn how to apply a theme in Omarchy using CLI, menu, or hotkey. Instantly change your desktop's look with our simple guide. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-23 --- **Run `omarchy theme set ""` 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//`, while user-specific overrides reside in `~/.config/omarchy/themes//`. Each theme directory contains a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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: ```bash 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: ```bash 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: ```bash OMARCHY_THEME_HEADLESS=1 omarchy-theme-set "Tokyo Night" ``` This mode is demonstrated in [`install/user/theme.sh`](https://github.com/basecamp/omarchy/blob/main/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`: ```bash 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: ```bash 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//` and user themes in `~/.config/omarchy/themes//`. - **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 ""` for direct activation or `OMARCHY_THEME_HEADLESS=1 omarchy-theme-set ""` 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 ""`. The [`install/user/theme.sh`](https://github.com/basecamp/omarchy/blob/main/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.