# Testing Omarchy Theme Changes with `omarchy dev theme-preview`

> Easily test Omarchy theme changes with omarchy dev theme-preview. Instantly preview color palettes, check WCAG contrast ratios, and apply changes directly in your terminal.

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

---

**The `omarchy dev theme-preview` command is a Bash utility that renders Omarchy theme color palettes as terminal swatches, calculating WCAG contrast ratios and optionally applying the palette via OSC sequences to preview changes instantly.**

When customizing Omarchy appearances, developers need rapid visual validation of color choices without restarting their desktop session. The `omarchy dev theme-preview` utility in the `omacom/omarchy` repository provides terminal-based palette visualization that validates hex codes, computes accessibility metrics, and leverages the same [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) definitions used by the underlying theming system documented in [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md).

## How the Preview Script Works

The preview logic in `bin/omarchy-dev-theme-preview` executes a three-stage pipeline to transform raw theme definitions into visual output.

### Resolving the colors.toml File

The script first determines which color definition file to load through the `resolve_colors_file` function (lines 65-84). This resolver accepts multiple input types: a theme name (which maps to `themes/<name>/colors.toml`), a directory path, or an explicit file path. If no argument is provided, the script falls back to the currently active theme configuration, ensuring developers can quickly test iterative changes without specifying paths repeatedly.

### Loading Colour Definitions

Once the file is identified, the `load_colors` function (lines 98-110) invokes the `omarchy-theme-color` helper to parse the TOML structure. This loads both raw color values and fully-resolved palette variables into an associative array, including dark-mode variants such as `dark_background` and `darker_background` as defined in the Omarchy theming specification. The script stores these values for rendering while maintaining the semantic relationships between theme variables.

### Rendering Swatches and Contrast Ratios

The final stage generates visual output through several specialized helper functions. The `swatch` function (starting at line 92) prints colored blocks of configurable width directly to the terminal. For accessibility validation, the `contrast_ratio` function (lines 38-56) calculates WCAG-compliant contrast ratios between foreground and background colors, while `hex_valid` (lines 27-29) ensures all color values conform to the `#RRGGBB` format before processing.

## Terminal Palette Integration

Beyond static swatches, the script can temporarily reconfigure your terminal's actual color palette to match the theme being previewed. The `apply_terminal_osc` function (lines 77-88) calls `omarchy-theme-osc` to emit Operating System Command (OSC) escape sequences when stdout is a TTY. This behavior is controlled via command-line flags: `--osc` forces palette application even when piping output, while `--no-osc` suppresses it entirely. The `--no-color` flag disables all ANSI output for plain-text testing.

## Usage Examples

Preview the currently active theme without arguments:

```bash
omarchy dev theme-preview

```

Test a specific theme by name:

```bash
omarchy dev theme-preview tokyo-night

```

Validate a custom [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file directly:

```bash
omarchy dev theme-preview themes/gruvbox/colors.toml

```

Disable color output for accessibility testing in plain text:

```bash
omarchy dev theme-preview --no-color

```

Suppress OSC terminal palette changes while keeping colored swatches:

```bash
omarchy dev theme-preview --no-osc

```

Force OSC application even when redirecting output:

```bash
omarchy dev theme-preview --osc

```

## Summary

- The `omarchy dev theme-preview` command validates and visualizes theme palettes directly in the terminal using the same [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) files that configure the Omarchy desktop environment.
- Key functions include `resolve_colors_file` for path resolution, `load_colors` for parsing TOML definitions, and `contrast_ratio` for WCAG accessibility calculations.
- The script optionally applies themes to your terminal emulator via OSC sequences through `omarchy-theme-osc`, providing immediate visual feedback without session restarts.
- Developers can target specific themes, directories, or explicit files while controlling output formatting with `--no-color`, `--osc`, and `--no-osc` flags.

## Frequently Asked Questions

### How does `omarchy dev theme-preview` handle invalid color definitions?

The script validates all color values through the `hex_valid` function (lines 27-29 of `bin/omarchy-dev-theme-preview`), which enforces strict `#RRGGBB` formatting. Invalid hex codes will fail validation before rendering, preventing malformed palettes from generating misleading preview output.

### Can I preview themes that are not installed in the standard `themes/` directory?

Yes. The `resolve_colors_file` function accepts absolute or relative paths to any [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file. You can pass the path directly as an argument (e.g., `omarchy dev theme-preview /path/to/custom/colors.toml`) regardless of whether the theme resides in the standard Omarchy themes directory.

### What is the difference between `--osc` and `--no-osc` flags?

By default, the script automatically applies OSC sequences only when stdout is a terminal (TTY). The `--osc` flag forces this behavior even when piping or redirecting output, while `--no-osc` explicitly disables the OSC palette changes even in interactive terminals. Both flags control the `apply_terminal_osc` function (lines 77-88) independently of color swatch rendering.

### Where does the preview script source its color resolution logic?

The preview utility delegates TOML parsing and color resolution to the `omarchy-theme-color` helper script, which extracts both raw values and resolved variables from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) files. This ensures consistency with the broader Omarchy theming system documented in [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md), where templates use identical palette data to generate shell, Hyprland, and terminal configurations.