# How to Run Omarchy User Provisioning Commands: The Complete Guide

> Learn how to run Omarchy user provisioning commands like omarchy-provision-user. Complete your Omarchy environment setup efficiently after initial login. Use --force to re-run.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`.

```bash

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

```bash

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

```bash

# 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).

```bash

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

```bash

# Wrong

sudo omarchy-provision-user

# Correct

su - username
omarchy-provision-user

```

### Provisioning skipped unexpectedly

Check for the idempotency marker:

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