# How to Toggle Features On or Off in Omarchy: A Complete Guide to the Flag-File System

> Learn how to toggle features on or off in Omarchy using its flag-file system. This guide explains the simple commands to enable, disable, and manage your Omarchy features easily.

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

---

**Omarchy uses a lightweight flag-file system where the presence of a file in `$HOME/.local/state/omarchy/toggles/<feature-name>` indicates an enabled feature, and its absence indicates a disabled feature. Use the `omarchy-toggle` command to enable, disable, or flip these states.**

Omarchy is an open-source Linux distribution that manages user preferences through a simple yet robust toggle system. Whether you want to enable night-light mode or activate custom desktop features, understanding how to toggle features on or off in Omarchy is essential for customization. This guide explains the flag-file architecture and the core shell scripts that manage feature states according to the `omacom/omarchy` source code.

## Understanding the Omarchy Toggle Architecture

### Flag File Storage Location

Omarchy stores toggle states as empty flag files in the user's local state directory. Each feature corresponds to a single file at `$HOME/.local/state/omarchy/toggles/<flag-name>`.

- Presence of file = **enabled**
- Absence of file = **disabled**

This filesystem-based approach eliminates the need for databases or complex configuration parsers, making state inspection trivial.

### Core Toggle Scripts

The system relies on three main components in the repository's `bin/` directory:

- **`bin/omarchy-toggle`** – The primary interface that creates or removes flag files based on command arguments.
- **`bin/omarchy-toggle-enabled`** – A query helper that exits with status 0 if the flag file exists, enabling conditional logic in shell scripts.
- **`bin/omarchy-toggle-nightlight`** – A feature-specific wrapper that extends the generic pattern with custom logic for color temperature management.

## Using omarchy-toggle to Manage Features

The `omarchy-toggle` script accepts a flag name and an optional action. When no action is specified, it defaults to toggling (flipping) the current state.

Enable a feature:

```bash
omarchy-toggle example on

```

Disable a feature:

```bash
omarchy-toggle example off

```

Toggle (flip) the current state:

```bash
omarchy-toggle example

```

### Querying Feature States in Scripts

Use `omarchy-toggle-enabled` to check if a feature is active before executing conditional code:

```bash
if omarchy-toggle-enabled example; then
  echo "Example feature is enabled"
else
  echo "Example feature is disabled"
fi

```

Alternatively, you can test the file directly:

```bash
if [ -f "$HOME/.local/state/omarchy/toggles/example" ]; then
  echo "Feature is active"
fi

```

## Feature-Specific Wrappers

Some features require additional logic beyond simple flag files. The night-light implementation in `bin/omarchy-toggle-nightlight` demonstrates this pattern by managing color temperature (4000K warm vs 6500K daylight) while still respecting the flag-file convention for persistence.

Toggle night-light mode:

```bash
omarchy-toggle-nightlight

```

Check detailed status:

```bash
omarchy-toggle-nightlight --status

# Outputs JSON: {"enabled":true, "temperature":4000}

```

## How the Toggle System Works Under the Hood

According to the source code in the [omacom/omarchy](https://github.com/omacom/omarchy) repository, the `omarchy-toggle` script parses the flag name and optional action parameter. When you run `omarchy-toggle example on`, the script creates an empty file at `$HOME/.local/state/omarchy/toggles/example`. Conversely, the `off` action removes this file. The `toggle` action checks for file existence and performs the opposite operation.

The `omarchy-toggle-enabled` helper provides a clean interface for other scripts to test states without directly checking filesystem paths. This ensures consistency across the Omarchy desktop environment.

The test suite in [`test/shell.d/toggle-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/toggle-test.sh) validates these behaviors, confirming that the generic toggle correctly handles enable, disable, and toggle operations.

## Summary

- Omarchy uses a **flag-file system** stored in `$HOME/.local/state/omarchy/toggles/`
- Use **`omarchy-toggle <name> [on|off|toggle]`** to manage states
- Query states with **`omarchy-toggle-enabled <name>`** for conditional scripting
- Feature-specific wrappers like `omarchy-toggle-nightlight` extend the base pattern for complex features
- The system is validated by automated tests in [`test/shell.d/toggle-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/toggle-test.sh)

## Frequently Asked Questions

### Where does Omarchy store feature toggle states?

Omarchy stores toggle states as empty flag files in the `$HOME/.local/state/omarchy/toggles/` directory. Each feature has a dedicated file; if the file exists, the feature is enabled. If the file is absent, the feature is disabled. This approach avoids complex databases and allows easy manual inspection or scripting.

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

Use the `omarchy-toggle-enabled` utility followed by the feature name. This command exits with status 0 (success) if the flag file exists, or status 1 if it does not. You can use it in shell conditionals like `if omarchy-toggle-enabled nightlight; then ... fi` to run commands only when features are active.

### Can I manually create or delete toggle files instead of using omarchy-toggle?

Yes. Since Omarchy uses simple file presence detection, you can manually create an empty file at `$HOME/.local/state/omarchy/toggles/<feature-name>` to enable a feature, or delete it to disable. However, using `omarchy-toggle` ensures consistent path handling and triggers any associated hooks that feature-specific wrappers might execute.

### What is the difference between omarchy-toggle and feature-specific wrappers like omarchy-toggle-nightlight?

The `omarchy-toggle` script provides generic enable/disable functionality for any feature name. Feature-specific wrappers like `bin/omarchy-toggle-nightlight` extend this pattern with additional logic—such as adjusting screen temperature or outputting JSON status—while still maintaining the underlying flag-file state in the standard location. Use the generic tool for simple boolean features and wrapper scripts for complex multi-state features.