# How to Apply System Configurations in Omarchy: Using the `omarchy-refresh-config` Helper > Easily apply Omarchy system configurations using omarchy-refresh-config. Safely update your user directory with automatic backups for your customizations. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-05 --- **Run `omarchy-refresh-config ` to safely apply Omarchy's default system configurations to your user directory, with automatic backups protecting your existing customizations.** Omarchy, an open-source system configuration framework maintained at `omacom/omarchy`, provides a standardized method to apply system configurations through its refresh helper utilities. When you need to synchronize your local environment with upstream defaults or initialize your system after installation, the `omarchy-refresh-config` command handles validation, backup, and deployment automatically. ## How `omarchy-refresh-config` Works The core helper located at `bin/omarchy-refresh-config` manages the entire configuration deployment pipeline. According to the Omarchy source code, this utility performs four critical operations every time you invoke it. ### Configuration Validation First, the script validates that the requested file actually exists under `$OMARCHY_PATH/config`. If the source file is missing, the command immediately exits with a non-zero status, preventing accidental overwrites or errors from typos. ### Automatic Backup Creation Before any modifications occur, the helper checks if a file already exists at the destination path in your home directory. When it finds an existing configuration, it creates a timestamped backup using the pattern `*.bak.` adjacent to the original file. This ensures you never lose your current customizations during the refresh process. ### Safe File Deployment After securing your backups, the command copies the default configuration from `$OMARCHY_PATH/config/` into the corresponding location under `$HOME/.config/`. This atomic approach ensures that only validated, complete files reach your active configuration directory. ### Exit Status Reporting The command returns explicit exit codes: non-zero for validation failures and zero for successful completion. This design allows you to chain `omarchy-refresh-config` calls in shell scripts and automation workflows with predictable error handling. ## Common Use Cases for Configuration Refreshing You will typically use this command in three scenarios: 1. **Initial system setup** — After installing Omarchy, populate your `~/.config/` tree by refreshing individual files like [`hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hypr/hyprland.lua) or [`chromium-flags.conf`](https://github.com/omacom/omarchy/blob/main/chromium-flags.conf). 2. **Updating to new defaults** — When the upstream repository introduces updated defaults, re-run the refresh command to copy new versions while preserving your previous configurations as backups. 3. **Selective synchronization** — Target specific configuration groups using wrapper scripts that call the helper multiple times for related files. ## Practical Command Examples Apply the default Hyprland bindings configuration: ```bash omarchy-refresh-config hypr/bindings.lua ``` Refresh your Chromium command-line flags: ```bash omarchy-refresh-config chromium-flags.conf ``` Run the comprehensive Hyprland refresh sequence, which invokes the helper for each Hyprland configuration file: ```bash omarchy-refresh-hyprland ``` ## Automation and Wrapper Scripts The Omarchy codebase includes several utilities that build upon the core refresh helper to streamline common tasks. The `bin/omarchy-refresh-hyprland` script serves as a practical example of automation, calling `omarchy-refresh-config` repeatedly for each Hyprland configuration file in the default set. This pattern ensures consistency across related configuration files without manual intervention. Migration scripts like [`migrations/1786273938.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1786273938.sh) also leverage this helper to ensure specific user configurations exist before proceeding with system updates. The [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) file documents additional `omarchy-refresh-*` commands available in the repository. Automated testing in [`test/shell.d/refresh-config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/refresh-config-test.sh) validates the backup, copy, and validation behaviors, ensuring reliability across system updates. Technical documentation in [`plans/dots.md`](https://github.com/omacom/omarchy/blob/main/plans/dots.md) provides additional context on the refresh process and backup file handling strategies. ## Summary - **Use `omarchy-refresh-config `** to apply default configurations from `$OMARCHY_PATH/config` to your `~/.config/` directory. - **Automatic validation** prevents errors by verifying source files exist before any operations occur. - **Timestamped backups** protect existing customizations using the `*.bak.` naming convention. - **Wrapper scripts** like `omarchy-refresh-hyprland` demonstrate how to batch-refresh related configuration groups. - **Reliable exit codes** enable scripting and automation workflows with proper error handling. ## Frequently Asked Questions ### Where does Omarchy store its default configuration files? Omarchy maintains its default configuration templates under `$OMARCHY_PATH/config`. When you run `omarchy-refresh-config`, the command sources files from this directory and deploys them to the corresponding paths under your home directory, typically within `~/.config/`. ### What happens to my existing configuration when I refresh? The `omarchy-refresh-config` helper automatically creates a timestamped backup of any existing file before overwriting it, using the pattern `*.bak.`. Your original configuration remains safe in the same directory, allowing you to manually restore it if needed. ### Can I use this command in automated scripts? Yes, the command is designed for automation. It returns a non-zero exit status when validation fails (such as when a source file does not exist) and exits successfully upon completion. This behavior makes it safe to chain multiple refresh commands or include in migration scripts like those found in the `migrations/` directory. ### How do I refresh multiple related configuration files at once? While `omarchy-refresh-config` handles individual files, you can use wrapper scripts such as `omarchy-refresh-hyprland` to refresh entire configuration groups. These scripts simply invoke the core helper repeatedly for each file in the set, as documented in `bin/omarchy-refresh-hyprland` and listed in [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md).