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

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 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

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

# 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: 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: 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, 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.

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