How to Run Omarchy User Provisioning Commands: The Complete Guide

Run omarchy-provision-user as a non-root user after first login to finalize your Omarchy environment, or use --force to re-run when switching development branches.

Omarchy's user provisioning system follows a three-stage architecture that separates system-level setup from per-user finalization. This guide explains how to run Omarchy user provisioning commands correctly, including when to use each flag and what happens under the hood based on the source code in omacom/omarchy.

The Three Stages of Omarchy User Provisioning

Omarchy's provisioning pipeline separates concerns across system creation, user finalization, and configuration resync.

• Seed stage: /etc/skel is copied into $HOME at user creation, providing baseline dotfiles and directory structure.
• Finalize stage: omarchy-provision-user runs once per user to create XDG directories, install skill symlinks, and execute per-user setup scripts.
• Resync stage: omarchy-reinstall-configs refreshes existing users with shipped defaults.

The finalize stage is where most administrators need direct control, and it's the focus of this guide.

Running the Main Provisioning Command

The primary interface is omarchy-provision-user located at bin/omarchy-provision-user. This script must execute as the target user, not root — it explicitly aborts if EUID == 0.

# Standard first-login finalization

omarchy-provision-user

The script writes an idempotency marker to ~/.local/state/omarchy/done/finalize-user to prevent duplicate runs. Check for this file if you're unsure whether provisioning completed.

Command-Line Options

Option	Purpose	Use Case
--force	Bypass idempotency check and re-run	Switching $OMARCHY_PATH to a dev checkout
--first-install	ISO provisioning mode with OMARCHY_SETUP_CONTEXT=iso-chroot	Only during chroot installation

# Force re-provisioning after environment changes

omarchy-provision-user --force

# ISO installation mode (normally automated)

omarchy-provision-user --first-install

Both flags can combine: omarchy-provision-user --force --first-install is how bin/omarchy-provision-owner invokes the command during initial system setup.

What omarchy-provision-user Actually Does

Inside bin/omarchy-provision-user, the script performs these concrete actions:

1. Create skill symlinks — Links default/agents/skills/* into ~/.agents/skills, ~/.claude/skills, and other dev-aware skill directories (lines 84-96).

2. Populate XDG user directories — Runs xdg-user-dirs-update and writes GTK bookmarks for ~/Downloads, ~/Pictures, etc. (lines 98-107).

3. Execute per-user install script — Sources install/user/all.sh for fonts, applications, and user-level tooling (line 109).

4. Refresh desktop integration — Runs omarchy-refresh-applications, sets Chromium as default browser, and registers HEY.desktop for mailto: URIs (lines 111-114).

5. Mark migrations complete — Touches placeholder files so migration scripts don't re-run on first install (lines 15-20).

6. Record completion — Calls omarchy-done mark finalize-user to write the idempotency marker (lines 22-24).

Alternative Invocation Methods

Using the Omarchy CLI Router

The omarchy command provides a shortcut alias:

# Equivalent to omarchy-provision-user

omarchy finalize user

# With force flag

omarchy finalize user --force

First-Run Wrapper for ISO Safety

bin/omarchy-provision-first-run wraps the main command with failure tolerance — it forwards to omarchy-provision-user but ignores non-zero exits, allowing ISO builds to continue even if user finalization encounters issues (line 46).

# Normally called automatically by the ISO

omarchy-provision-first-run

Automated and System-Managed Invocation

You don't always need to run these commands manually. Omarchy includes automated triggers:

• First boot after ISO install: The systemd service omarchy-provision-owner.service runs omarchy-provision-owner, which ultimately calls omarchy-provision-user --force --first-install (line 851 of bin/omarchy-provision-owner).

• Pending provisioning flag: The ISO leaves /var/lib/omarchy/provisioning/pending to defer finalization until first boot.

Troubleshooting Common Issues

"Cannot run as root" error

The script checks EUID and aborts if zero (lines 26-30). Switch to the target user:

# Wrong

sudo omarchy-provision-user

# Correct

su - username
omarchy-provision-user

Provisioning skipped unexpectedly

Check for the idempotency marker:

ls ~/.local/state/omarchy/done/finalize-user

If present, use --force to override.

Summary

• Primary command: omarchy-provision-user (never run as root)
• Force re-run: Add --force flag when changing environments
• ISO mode: --first-install for chroot provisioning contexts
• Shortcut: omarchy finalize user provides equivalent functionality
• Idempotency: Tracked at ~/.local/state/omarchy/done/finalize-user
• Automated runs: Handled by omarchy-provision-owner.service on first boot

Frequently Asked Questions

Can I run omarchy-provision-user as root with sudo?

No. The script explicitly checks EUID == 0 and aborts with an error message. You must run it as the target user because it creates files in $HOME with correct ownership and executes user-specific installation scripts that expect a real home directory environment.

What's the difference between --force and --first-install?

--force simply bypasses the idempotency check to allow re-running. --first-install implies --force but additionally sets OMARCHY_SETUP_CONTEXT=iso-chroot, which triggers ISO-specific behaviors like marking all migrations complete. Use --force for normal re-provisioning; reserve --first-install for actual ISO builds.

How do I know if my user has already been provisioned?

Check for the marker file: ~/.local/state/omarchy/done/finalize-user. If it exists, the omarchy-provision-user command will exit immediately unless you use --force. You can also inspect ~/.agents/skills/ and ~/.config/gtk-3.0/bookmarks — their presence indicates successful completion.

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