How omarchy-reinstall-configs Resets Your Omarchy Configuration to Defaults

The omarchy-reinstall-configs command performs a destructive resynchronization that overwrites your $HOME configuration with the pristine defaults stored in /etc/skel.

In the basecamp/omarchy repository, this utility serves as the nuclear option for configuration management. It explicitly restores a user's home directory to the exact state shipped with the distribution, making it essential for troubleshooting broken setups or recovering from incompatible customizations.

What omarchy-reinstall-configs Does

The command implements an explicit resync pattern described in docs/file-layout.md. It clobbers existing user configurations by copying skeleton files directly from /etc/skel into the user's $HOME directory, effectively performing a factory reset on your environment settings.

The Destructive Sync Process

When executed, the script at bin/omarchy-reinstall-configs performs two critical operations:

1. Identifies conflicts – Locates configuration files in $HOME that also exist in /etc/skel
2. Overwrites with defaults – Copies the skeleton directory contents into $HOME, destroying any existing customizations

According to plans/dots.md, this behavior explicitly "clobbers everything back to /etc/skel defaults."

When to Use This Command

As documented in agents/skills/install-scripts.md, this destructive resynchronization is intended for:

• Recovering from broken configuration states
• Upgrading between major Omarchy versions
• Troubleshooting environment issues requiring a clean slate

How to Run omarchy-reinstall-configs

Standalone Execution

To reset your configuration immediately, run:

omarchy-reinstall-configs

As Part of Full Reinstall

The command also functions as a step in the broader reinstall pipeline:

omarchy-reinstall

This higher-level utility executes omarchy-reinstall-pkgs, followed by omarchy-reinstall-configs, and additional system restoration steps.

Previewing What Will Be Replaced

Since the operation destroys data, preview the skeleton files first:

ls -1 /etc/skel

Implementation Details

The command logic resides in bin/omarchy-reinstall-configs. Documentation across the repository clarifies its architectural role:

• docs/file-layout.md defines the "explicit resync" concept linking /etc/skel to user homes
• plans/dots.md places the command within the overall reinstall workflow
• agents/skills/install-scripts.md explains its function in user-provisioning and configuration finalization

Summary

• omarchy-reinstall-configs destructively resynchronizes $HOME with /etc/skel defaults
• The operation overwrites existing files without prompting, requiring careful use
• Execute it standalone for config-only resets or via omarchy-reinstall for full system restoration
• Preview skeleton contents using ls -1 /etc/skel before execution
• Source documentation spans docs/file-layout.md, plans/dots.md, and agents/skills/install-scripts.md

Frequently Asked Questions

What does omarchy-reinstall-configs actually delete?

The command identifies configuration files in your $HOME directory that share names with files in /etc/skel and overwrites them with the skeleton versions. It effectively destroys local customizations to restore the shipped defaults as implemented in bin/omarchy-reinstall-configs.

Is omarchy-reinstall-configs safe to run?

Only if you accept data loss. As noted in the basecamp/omarchy source code, this is a destructive operation intended specifically for situations requiring a clean-slate configuration, such as recovering from broken setups or major version upgrades.

How is this different from omarchy-reinstall?

While omarchy-reinstall chains multiple steps including package reinstallation, omarchy-reinstall-configs focuses exclusively on configuration files. The full reinstall utility calls omarchy-reinstall-configs as part of its sequential workflow to ensure configurations match the system's current defaults.

Can I see what will be overwritten before running the command?

Yes. List the contents of /etc/skel using ls -1 /etc/skel to identify which default files will replace your current home directory configurations. This preview step helps you identify exactly which dotfiles and settings will be lost during the resync.

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