How to Refresh User Configurations to Default Settings in Omarchy

Use the omarchy-refresh-config utility to restore any user configuration file to its shipped default by passing the relative path from the Omarchy repository, which automatically backs up your existing settings with a timestamped extension before overwriting.

Omarchy, an open-source Linux distribution configuration framework maintained in the omacom/omarchy repository, provides a dedicated mechanism for reverting user customizations. The refresh system ensures that you can safely return to known-good defaults without losing your previous work, leveraging POSIX-compliant shell tools for maximum compatibility.

Understanding the omarchy-refresh-config Command

The core utility bin/omarchy-refresh-config serves as the single entry point for all configuration reset operations. It expects a relative file path—such as hypr/bindings.lua or tmux/tmux.conf—and resolves this against the OMARCHY_PATH environment variable to locate the original default.

When invoked, the script performs strict validation: if the specified file does not exist under $OMARCHY_PATH/config, the operation aborts immediately with an error message. This guardrail prevents accidental restoration of non-existent or third-party configurations, as verified by the test suite in test/shell.d/refresh-config-test.sh.

How the Refresh Process Works

The reset operation follows a deterministic three-phase pipeline designed to protect user data while ensuring atomic replacement.

Locating Default Files

The command constructs the source path by appending the user-provided relative path to $OMARCHY_PATH/config. For example, supplying hypr/bindings.lua targets $OMARCHY_PATH/config/hypr/bindings.lua. If this source file is missing, the utility exits with a non-zero status, ensuring only officially shipped defaults can be propagated.

Backup Behavior

Before any overwrite occurs, omarchy-refresh-config preserves the existing user file located at ~/.config/<relative-path>. The utility renames the current file using the pattern *.bak.<timestamp>, appending the current date and time to prevent clobbering previous backups. This timestamped backup strategy allows you to roll back multiple iterations of customizations if needed.

Copying Defaults

Once the backup is secured, the utility copies the default file from the Omarchy repository to the user's configuration directory using standard cp operations that preserve file permissions. The destination path is always resolved relative to $HOME/.config, maintaining consistency with XDG Base Directory specifications.

Using Convenience Wrappers

While omarchy-refresh-config operates on individual files, Omarchy provides domain-specific wrapper scripts for common reset scenarios. These wrappers invoke the core utility for predefined file sets, simplifying bulk restoration.

• omarchy-refresh-hyprland – Refreshes all Hyprland window manager configurations, including hypr/bindings.lua and related settings.
• omarchy-refresh-tmux – Restores the terminal multiplexer configuration files to their original state.
• omarchy-refresh-shell – Reverts Omarchy-specific shell definitions and environment JSON files.

Each wrapper automatically sets the required OMARCHY_PATH and HOME environment variables, making them safe to run directly from an interactive shell or automation scripts.

Practical Code Examples

The following examples demonstrate both direct invocation of the refresh utility and usage of the convenience wrappers.

Refresh a single Hyprland binding file directly:

OMARCHY_PATH="$HOME/.local/share/omarchy" \
HOME="$HOME" \
omarchy-refresh-config hypr/bindings.lua

Restore the complete Hyprland configuration set using the wrapper:

omarchy-refresh-hyprland

Revert tmux settings to defaults:

omarchy-refresh-tmux

Reset Omarchy shell definitions:

omarchy-refresh-shell

Summary

• omarchy-refresh-config is the primary utility for reverting individual configuration files to their default state as shipped in the omacom/omarchy repository.
• The command requires the OMARCHY_PATH environment variable to locate default files under the config/ subdirectory.
• Existing user configurations are automatically backed up with a *.bak.<timestamp> suffix before replacement.
• Convenience wrappers (omarchy-refresh-hyprland, omarchy-refresh-tmux, omarchy-refresh-shell) streamline bulk restoration of specific subsystems.
• All operations use standard POSIX tools and validate source file existence before executing, ensuring safe, predictable behavior.

Frequently Asked Questions

What is the OMARCHY_PATH environment variable?

OMARCHY_PATH is an environment variable that points to the root directory of the Omarchy repository installation on your system. The omarchy-refresh-config utility uses this path to locate default configuration files under the config/ subdirectory. If unset, the tool cannot determine which files constitute the "default" state.

How does Omarchy backup existing configurations?

Before overwriting any user file, Omarchy renames the existing configuration to a backup name following the pattern filename.bak.YYYYMMDD-HHMMSS (or similar timestamp). This creates a dated snapshot in the same directory as the original file, allowing you to restore previous customizations manually if the new defaults are unsatisfactory.

Can I refresh multiple configuration files at once?

While omarchy-refresh-config operates on single files, you can refresh multiple configurations sequentially by calling the command multiple times or by using the provided convenience wrappers. For example, omarchy-refresh-hyprland internally calls omarchy-refresh-config for each Hyprland-related file, effectively batching the operation.

Where are the default configuration files stored?

Default configuration files reside in the config/ directory within the Omarchy repository (specifically at $OMARCHY_PATH/config). These files represent the pristine, unmodified settings shipped by the omacom/omarchy project. The refresh utility validates that requested files exist in this location before attempting any restoration.

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