# How to Refresh User Configurations to Default Settings in Omarchy

> Easily refresh user configurations to default settings in Omarchy using the omarchy-refresh-config utility. Automatically back up existing files before restoring defaults.

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

---

**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`](https://github.com/omacom/omarchy/blob/main/hypr/bindings.lua) or [`tmux/tmux.conf`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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:

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

```

Restore the complete Hyprland configuration set using the wrapper:

```bash
omarchy-refresh-hyprland

```

Revert tmux settings to defaults:

```bash
omarchy-refresh-tmux

```

Reset Omarchy shell definitions:

```bash
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.