# What Does `omarchy-provision-user` Do? Automating Per-User Setup in Omarchy > Discover what omarchy-provision-user does. Automate per-user setup in Omarchy by creating symlinks, XDG directories, and default apps that /etc/skel cannot handle. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-27 --- **`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`](https://github.com/basecamp/omarchy/blob/main/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. ```bash # 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.