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

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:

omarchy-toggle example on

Disable a feature:

omarchy-toggle example off

Toggle (flip) the current state:

omarchy-toggle example

Querying Feature States in Scripts

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

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:

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:

omarchy-toggle-nightlight

Check detailed status:

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 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 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

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.

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