# How Feature Toggles Work with the toggle-* Command Prefix in Omarchy

> Discover how Omarchy uses feature toggles with the toggle-* command prefix. Learn to manage feature flags efficiently via simple file presence in your state directory.

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

---

**Omarchy implements feature toggles as empty flag files stored in `$HOME/.local/state/omarchy/toggles/`, where file presence indicates an enabled feature and absence indicates a disabled one, managed entirely through the `toggle-*` command suite.**

The omacom/omarchy repository provides a lightweight, file-based feature toggle architecture that persists state across sessions without requiring databases or complex configuration parsers. This system relies on simple POSIX presence-check semantics that function identically across Bash scripts, QML plugins, and systemd service files.

## The Flag-File Architecture

Omarchy’s toggle system abandons traditional key-value configuration in favor of **empty marker files** whose existence alone encodes binary state. This design prioritizes atomic operations and universal accessibility across different runtime environments.

### State Directory Structure

All toggle states reside under a single hierarchy:

```bash
$HOME/.local/state/omarchy/toggles/

```

Individual features are identified by filename. For example, enabling the `nightlight` feature creates an empty file at `~/.local/state/omarchy/toggles/nightlight`, while disabling it removes that file entirely. Hyprland-specific toggles extend this pattern by storing Lua configuration snippets under `toggles/hypr/$NAME.lua`.

### Enable/Disable Semantics

The system operates on strict binary logic:

- **Enabled**: The flag file exists (contents are ignored).
- **Disabled**: The flag file does not exist.

This convention allows any component—whether a Bash script, QML property binding, or systemd unit condition—to query state using standard filesystem tests like `[[ -f ... ]]` or `ConditionPathExists`.

## Core toggle-* Commands

The command-line interface provides thin wrappers around these filesystem operations, ensuring consistent state management across the desktop environment.

### General-Purpose Toggle (omarchy-toggle)

Located at `bin/omarchy-toggle`, this script implements the primary state mutation logic. It accepts a target name as `$1` and an optional action as `$2` (`toggle`, `on`, or `off`). The internal `enable()` function creates the flag file using `touch`, while `disable()` removes it with `rm`. When invoked without an explicit action, the command toggles the current state—creating the file if absent or removing it if present.

### Query Helper (omarchy-toggle-enabled)

The `bin/omarchy-toggle-enabled` utility provides idempotent state inspection. It returns exit status `0` (success) if the specified toggle is enabled and a non-zero exit code otherwise. The implementation performs a single filesystem test:

```bash
[[ -f "$HOME/.local/state/omarchy/toggles/$1" ]]

```

This makes it ideal for conditional logic in shell scripts and CI pipelines.

### Feature-Specific Wrappers

Omarchy distributes convenience scripts following the `omarchy-toggle-<feature>` naming convention (e.g., `omarchy-toggle-touchpad`, `omarchy-toggle-input-device`). These wrappers invoke the core `omarchy-toggle` command with preset names, sometimes performing additional side effects such as writing to subdirectories for Hyprland device management.

### Hyprland-Specific Toggles

The `bin/omarchy-hyprland-toggle` command manages dynamic configuration injection for the Hyprland compositor. Rather than creating empty files, it copies Lua source snippets from `$OMARCHY_PATH/default/hypr/toggles/` into `~/.local/state/omarchy/toggles/hypr/$NAME.lua`. The companion command `omarchy-hyprland-toggle-disabled` removes these Lua files, allowing runtime toggling of window manager behaviors without restarting the session.

## System Integration Points

The flag-file architecture enables broad interoperability across Omarchy’s component stack.

### Shell and QML Components

Desktop shell plugins read toggle states directly from the filesystem. For example, `shell/plugins/bar/Bar.qml` checks for the existence of `~/.local/state/omarchy/toggles/bar-off` to conditionally hide the panel. This eliminates the need for IPC mechanisms or D-Bus queries when querying simple feature states.

### systemd Service Conditions

Systemd units leverage the same paths using `ConditionPathExists` directives. The `default/systemd/user/omarchy-crash-watch.service` file demonstrates this pattern:

```ini
ConditionPathExists=!%h/.local/state/omarchy/toggles/crash-capture-off

```

This declarative rule prevents the crash-watching service from starting when the user has explicitly disabled crash capture via the toggle system.

### Hyprland Configuration Snippets

The [`default/hypr/toggles.lua`](https://github.com/omacom/omarchy/blob/main/default/hypr/toggles.lua) file defines a dynamic include path that Hyprland evaluates at runtime. When `omarchy-hyprland-toggle` copies a Lua module into the state directory, Hyprland immediately applies the configuration changes, enabling features like `window-no-gaps` without requiring a full configuration reload.

## Working with Feature Toggles

The following examples demonstrate common operations against the toggle system:

```bash

# Toggle a feature (creates file if absent, removes if present)

omarchy-toggle nightlight

# Explicitly enable without toggling

omarchy-toggle nightlight on

# Explicitly disable

omarchy-toggle nightlight off

# Check state in a script

if omarchy-toggle-enabled nightlight; then
    echo "Nightlight is active"
else
    echo "Nightlight is disabled"
fi

# Enable a Hyprland-specific behavior

omarchy-hyprland-toggle window-no-gaps

# Disable the Hyprland behavior

omarchy-hyprland-toggle-disabled window-no-gaps

```

All commands inherit the same atomic semantics: filesystem creation and deletion operations define state, ensuring consistency even when multiple processes query or modify toggles concurrently.

## Summary

- Omarchy stores feature toggles as empty flag files in `~/.local/state/omarchy/toggles/`, where presence equals enabled and absence equals disabled.
- The `bin/omarchy-toggle` script provides general-purpose state management with `enable()`, `disable()`, and toggle logic.
- `bin/omarchy-toggle-enabled` offers a lightweight query mechanism returning shell exit codes based on file existence.
- Hyprland integration uses `bin/omarchy-hyprland-toggle` to manage Lua configuration snippets in a sub-directory.
- The architecture supports cross-cutting concerns: QML plugins read flags directly, systemd units use `ConditionPathExists` guards, and migration scripts preserve state across upgrades.

## Frequently Asked Questions

### How do I check if a specific feature toggle is currently enabled?

Use the `omarchy-toggle-enabled` helper script followed by the toggle name. This command exits with status `0` if the flag file exists (enabled) and non-zero otherwise, making it suitable for use in `if` statements and shell conditionals without parsing text output.

### What is the difference between omarchy-toggle and omarchy-hyprland-toggle?

`bin/omarchy-toggle` manages simple empty flag files for binary state, while `bin/omarchy-hyprland-toggle` specifically handles Lua configuration modules for the Hyprland window manager. The Hyprland variant copies source files from the defaults directory rather than creating empty markers, allowing dynamic injection of configuration code.

### Where does Omarchy store feature toggle states persistently?

All toggle states are stored in the user’s state directory at `$HOME/.local/state/omarchy/toggles/`. Hyprland-specific toggle Lua files reside in the `hypr/` subdirectory within that path. This location conforms to the XDG Base Directory Specification and survives across login sessions.

### Can I create custom feature toggles for my own scripts?

Yes. Any script can participate in the toggle system by creating or removing files in `~/.local/state/omarchy/toggles/`. For example, running `touch ~/.local/state/omarchy/toggles/my-custom-feature` enables the toggle, which can then be queried by other components using standard filesystem tests or the `omarchy-toggle-enabled` helper.