What Does `omarchy-provision-user` Do? Automating Per-User Setup in Omarchy

omarchy-provision-user is a hidden Omarchy command that performs idempotent per-user finalization steps—such as creating skill symlinks, configuring XDG directories, and setting default applications—that cannot be completed by the system-wide /etc/skel skeleton.

When deploying the Omarchy desktop environment from the basecamp/omarchy repository, system-wide skeleton files in /etc/skel handle only static initialization. The omarchy-provision-user script bridges this gap by executing runtime finalization logic directly within the logged-in user's $HOME directory, ensuring consistent developer environments and desktop integration.

Core Responsibilities of omarchy-provision-user

The script is implemented in bin/omarchy-provision-user and orchestrates seven distinct finalization tasks that require a live user context.

Idempotent User Finalization

To prevent redundant execution, the command checks for a marker file at ~/.local/state/omarchy/done/finalize-user using the helper bin/omarchy-done. If this marker exists, the script exits immediately unless the --force flag is supplied, guaranteeing safe, repeatable runs.

Environment Preparation

The script establishes core Omarchy environment variables required by downstream tools. It sets OMARCHY_PATH, OMARCHY_INSTALL, and OMARCHY_SETUP_CONTEXT, then prepends the Omarchy binary directory to the user's $PATH to ensure local tooling takes precedence over system packages.

Development-Aware Skill Symlinks

For developer workflows, omarchy-provision-user creates symbolic links under user-specific skill directories—including ~/.agents/skills and ~/.claude/skills—that point to the canonical skill definitions within the repository. This allows developers to work directly from a checkout without copying files into $HOME, keeping skills synchronized with the upstream source.

XDG Directories and GTK Bookmarks

The command ensures standard user directories exist (Downloads, Pictures, Videos), updates XDG user-dir settings, and populates ~/.config/gtk-3.0/bookmarks with convenient shortcuts. This guarantees that file managers and GTK applications present a consistent navigation experience immediately after login.

User-Level Installation Scripts

After environment preparation, the script sources install/user/all.sh to execute centralized user-level installation logic. It then refreshes desktop entries, sets Chromium as the default web browser, and registers the HEY.desktop mailto handler, completing the desktop integration loop.

First-Install Handling for ISO Deployments

When invoked with --first-install (typically used by the ISO chroot during image creation), the script marks all migration scripts as "already applied." This prevents the new user account from re-running migration logic that was already executed during system installation, ensuring clean state for fresh deployments.

Completion Marker

Upon successful execution of all steps, the script records the finalization marker via omarchy-done mark and prints a success message. This atomic completion guarantees that partial runs due to interruptions will resume correctly on next invocation.

Usage Examples

Run the provisioner once per user account; the command is idempotent and safe to rerun.

# Standard usage – exits silently if already finalized

omarchy-provision-user

# Force refresh of all user-level steps

omarchy-provision-user --force

# Initialize a fresh user during ISO installation

omarchy-provision-user --first-install

Typical output:

User finalization complete.

If already executed:

User finalization already complete (rerun with --force to refresh).

Source Code and Key Files

The implementation relies on several canonical paths within the basecamp/omarchy repository:

• bin/omarchy-provision-user – Main orchestration script containing the finalization logic.
• bin/omarchy-done – Idempotency helper that checks and records marker files in ~/.local/state/omarchy/done/.
• install/user/all.sh – Centralized user installation routines sourced by the provisioner.
• default/agents/skills/ – Source directory for skill definitions that are symlinked into user-specific paths.

These components work together to ensure that user environments remain reproducible and synchronized with the Omarchy distribution.

Summary

• omarchy-provision-user finalizes user accounts after system-wide skeletons complete their work.
• It operates idempotently via marker files in ~/.local/state/omarchy/done/ and supports --force for refreshes.
• The script configures environment variables, creates development skill symlinks, and establishes XDG directories.
• It sources install/user/all.sh to set default applications like Chromium and HEY.
• The --first-install flag prevents duplicate migrations during ISO-based installations.

Frequently Asked Questions

How do I force omarchy-provision-user to run again?

Pass the --force flag to bypass the idempotency check. This deletes the marker file at ~/.local/state/omarchy/done/finalize-user and re-executes all finalization steps, useful when updating skill definitions or repairing user configuration.

What is the difference between omarchy-provision-user and /etc/skel?

/etc/skel copies static files into $HOME at account creation time, but cannot perform runtime logic such as setting environment variables or creating symlinks to a developer's live Omarchy checkout. omarchy-provision-user runs after login to execute these dynamic, user-specific finalization tasks.

When should I use the --first-install flag?

Use --first-install only during automated ISO installations or chroot environments where the Omarchy system is being pre-configured for a user who does not yet exist. This flag prevents migration scripts from running twice—once during image build and again on first boot.

Where does omarchy-provision-user store its completion state?

The script stores a marker file at ~/.local/state/omarchy/done/finalize-user using the omarchy-done utility. Existence of this file indicates that finalization succeeded on a previous run, causing subsequent invocations to exit immediately unless --force is specified.

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