# Omarchy Provision User vs Reinstall Configs: Scope and Use Cases Explained

> Understand omarchy-provision-user vs omarchy-reinstall-configs. Learn when to use each for user provisioning and config resets in omarchy.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-09

---

**While `omarchy-provision-user` performs runtime finalization for new users by creating skill symlinks and configuring system handlers, `omarchy-reinstall-configs` merely refreshes static configuration files from `/etc/skel` for existing users who need to resync with defaults.**

The `omacom/omarchy` repository provides distinct utilities for managing user environments at different lifecycle stages. Understanding the difference between `omarchy-provision-user` and `omarchy-reinstall-configs` ensures proper automation of user onboarding and maintenance without disrupting runtime customizations.

## What Is omarchy-provision-user?

### Purpose and Runtime Finalization

The `bin/omarchy-provision-user` script executes per-user initialization steps that cannot be performed at the system level or via skeleton directories. According to the source implementation, it handles dynamic environment setup requiring an active `$HOME` context and running session.

### Key Operations

- **Skill symlink creation**: Establishes development-aware symlinks in `~/.agents/skills`, `~/.claude/skills`, and related directories
- **XDG directory setup**: Configures `xdg-user-dirs` and GTK bookmarks specific to the user's home path
- **Default handler installation**: Registers the default web browser and `mailto` protocol handler
- **User script execution**: Runs [`install/user/all.sh`](https://github.com/omacom/omarchy/blob/main/install/user/all.sh) for additional runtime tweaks
- **Idempotency marking**: Creates `~/.local/state/omarchy/done/finalize-user` to prevent duplicate execution

## What Is omarchy-reinstall-configs?

### Configuration Resynchronization

Located at `bin/omarchy-reinstall-configs`, this utility addresses the need to restore or update default configuration files for **existing** users. As noted in the documentation, it serves users "explicitly resyncing" their configurations, unlike the skeleton-based setup for new accounts.

### Core Functionality

- **Skeleton file deployment**: Copies configuration templates from `/etc/skel` into the user's home directory when files are missing or outdated
- **Explicit resync capability**: Allows users to voluntarily refresh defaults without affecting runtime-generated files
- **Non-destructive defaults**: Preserves existing user customizations unless explicitly forced with command-line flags

## Key Differences Between omarchy-provision-user and omarchy-reinstall-configs

**Execution Context**
- **`omarchy-provision-user`**: Runs automatically on first login or via `--first-install` flag during ISO installation. It requires an active user session with `$HOME` defined and accessible.
- **`omarchy-reinstall-configs`**: Executed manually by existing users or administrative scripts when configuration drift occurs or defaults need restoration.

**Scope of Changes**
- **`omarchy-provision-user`**: Creates dynamic runtime artifacts including symbolic links, XDG user directories, and desktop environment handlers. It modifies active session configurations that depend on runtime variables.
- **`omarchy-reinstall-configs`**: Handles static dotfiles and configuration templates only. It leaves runtime directories, symlinks, and session-specific settings untouched.

**Idempotency Behavior**
- **`omarchy-provision-user`**: Strictly idempotent via marker file `~/.local/state/omarchy/done/finalize-user`. Requires `--force` flag to rerun initialization steps.
- **`omarchy-reinstall-configs`**: Safe to run multiple times by design, with optional `--force` to overwrite existing configuration files.

## When to Use Each Command

Use **omarchy-provision-user** when:

- Provisioning new user accounts after system installation
- Running first-login initialization that requires `$HOME` context and active graphical session
- Setting up development environments with skill symlinks in `~/.agents/` and `~/.claude/`
- Executing per-user scripts located in [`install/user/all.sh`](https://github.com/omacom/omarchy/blob/main/install/user/all.sh)

Use **omarchy-reinstall-configs** when:

- Existing users need to restore default configuration files from `/etc/skel`
- Updating shipped configs after major Omarchy version upgrades
- Repairing corrupted or deleted default dotfiles without touching runtime data or skill configurations

## Practical Usage Examples

```bash

# First-time user finalization (typically runs automatically on first login)

omarchy-provision-user

# Force re-provisioning for troubleshooting or after manual deletion of marker file

omarchy-provision-user --force

# Restore missing default configs for existing user

omarchy-reinstall-configs

# Force overwrite of existing config files with skeleton templates

omarchy-reinstall-configs --force

```

## Implementation Details and File Locations

According to the source tree in `omacom/omarchy`:

- **`bin/omarchy-provision-user`**: Implements the finalize-user logic with idempotency checks and runtime configuration steps
- **`bin/omarchy-reinstall-configs`**: Handles the `/etc/skel` synchronization workflow for explicit resynchronization
- **[`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md)**: Documents the relationship between these utilities, noting that shipped configs are handled via `/etc/skel` for new users and `omarchy-reinstall-configs` for existing users
- **[`test/shell.d/provision-user-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/provision-user-test.sh)**: Provides automated test coverage for the provision-user script
- **`~/.local/state/omarchy/done/finalize-user`**: Marker file indicating successful completion of provision-user execution

## Summary

- **`omarchy-provision-user`** performs runtime finalization for new users, creating dynamic symlinks, XDG directories, and executing user-specific installation scripts that require active session context
- **`omarchy-reinstall-configs`** refreshes static configuration files from `/etc/skel` for existing users without modifying runtime environments or skill symlinks
- The provision script uses `~/.local/state/omarchy/done/finalize-user` for strict idempotency, while the reinstall command is inherently safe to rerun without force flags
- Choose provision-user for initial user setup and reinstall-configs for configuration recovery or updates after system upgrades

## Frequently Asked Questions

### Can I run omarchy-provision-user on an existing account without losing data?

Yes, but exercise caution. The script checks for `~/.local/state/omarchy/done/finalize-user` and skips execution unless you provide the `--force` flag. Forcing a rerun recreates skill symlinks and executes [`install/user/all.sh`](https://github.com/omacom/omarchy/blob/main/install/user/all.sh), which may overwrite existing runtime customizations established after the initial setup.

### Does omarchy-reinstall-configs overwrite my personal customizations?

By default, it only copies missing files from `/etc/skel` into your home directory. Existing files remain untouched unless you explicitly pass `--force`. This design preserves user modifications while allowing restoration of accidentally deleted default configurations.

### Why can't omarchy-provision-user use /etc/skel for all its tasks?

The `/etc/skel` directory only supports static file copying during account creation at the system level. Operations like creating symlinks to skill directories, configuring XDG user paths, and registering default applications require runtime environment variables and active user context that are not available during system-level user creation.

### Which command should I use after upgrading Omarchy to get new default configs?

Use `omarchy-reinstall-configs`. This command specifically refreshes your home directory with updated templates from `/etc/skel` without disrupting your existing runtime setup, skill configurations, or XDG directories established by `omarchy-provision-user`.