How to Apply System Configurations in Omarchy: Using the `omarchy-refresh-config` Helper

Run omarchy-refresh-config <relative-path> 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.<timestamp> 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/<relative-path> 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 or 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:

omarchy-refresh-config hypr/bindings.lua

Refresh your Chromium command-line flags:

omarchy-refresh-config chromium-flags.conf

Run the comprehensive Hyprland refresh sequence, which invokes the helper for each Hyprland configuration file:

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 also leverage this helper to ensure specific user configurations exist before proceeding with system updates. The AGENTS.md file documents additional omarchy-refresh-* commands available in the repository.

Automated testing in 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 provides additional context on the refresh process and backup file handling strategies.

Summary

• Use omarchy-refresh-config <relative-path> 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.<timestamp> 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.<timestamp>. 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.

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