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

> Learn how omarchy-reinstall-configs resets your Omarchy configuration to defaults by overwriting your home directory with pristine /etc/skel files. Understand this destructive resynchronization.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash
omarchy-reinstall-configs

```

### As Part of Full Reinstall

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

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

```bash
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`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md)** defines the "explicit resync" concept linking `/etc/skel` to user homes
- **[`plans/dots.md`](https://github.com/basecamp/omarchy/blob/main/plans/dots.md)** places the command within the overall reinstall workflow
- **[`agents/skills/install-scripts.md`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md), [`plans/dots.md`](https://github.com/basecamp/omarchy/blob/main/plans/dots.md), and [`agents/skills/install-scripts.md`](https://github.com/basecamp/omarchy/blob/main/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.