What Does the `omarchy finalize user` Command Do? Complete Guide to Per-User Setup

The omarchy finalize user command runs per-user runtime finalization that cannot be handled by /etc/skel, including dev-aware skill symlinks, directory setup, GTK bookmarks, and application defaults.

The omarchy finalize user command is a core utility in the Omacom/omarchy repository that completes user environment configuration after initial system installation. Unlike files copied from /etc/skel during account creation, this command handles dynamic setup that requires runtime logic—such as creating symbolic links to development checkouts and registering desktop preferences.

How omarchy finalize user Works

The command is implemented by the omarchy-provision-user script located at bin/omarchy-provision-user. When invoked, it executes eight distinct phases of user configuration, with built-in idempotency to prevent duplicate work.

Safety Checks and Idempotency

Before performing any changes, the script validates the runtime environment. It aborts if executed as root (since per-user setup must run as the target user) and skips all work if the marker file ~/.local/state/omarchy/done/finalize-user already exists.

# Normal run – safe to call multiple times, only executes once

omarchy finalize user

# Force re-execution after configuration changes

omarchy finalize user --force

The idempotency check appears at lines 26–33 in bin/omarchy-provision-user, with marker writing at lines 130–131.

Environment Setup

The script establishes the Omarchy environment by defining OMARCHY_PATH and prepending OMARCHY_PATH/bin to $PATH. It also respects the OMARCHY_SETUP_CONTEXT variable, applying special handling for ISO chroot environments (lines 64–73).

Dev-Aware Skill Symlinks

One of the most important functions is creating symbolic links for agent skills. For each skill directory under default/agents/skills/, the script creates symlinks in multiple agent locations:

• ~/.agents/skills
• ~/.claude/skills
• And other agent-specific directories

This ensures developers working from an Omarchy checkout use live skill files directly, rather than baked copies from /etc/skel (lines 84–100).

User Directories and GTK Bookmarks

The command prepares standard $HOME directories—Downloads, Pictures, Videos, and others—then updates xdg-user-dirs configuration. It also populates ~/.config/gtk-3.0/bookmarks with convenient links to these folders (lines 106–115).

User-Level Installation Script

The bulk of configuration is delegated to install/user/all.sh, which handles fonts, icons, toolchains, and other per-user assets (lines 117–119). This separation keeps the provision script focused on orchestration while the install script manages specific packages.

Application Defaults and Desktop Integration

After installation, the script:

1. Calls omarchy-refresh-applications to update desktop entries
2. Forces Chromium as the default web browser
3. Registers a mailto: handler using HEY.desktop (lines 119–122)

Migration Handling for First Installs

When executed with --first-install (typically during ISO installation), the script creates empty marker files for every migration script in the migrations/ directory. This prevents migration steps from re-running on fresh systems (lines 123–128).

# Usage during ISO installation

omarchy finalize user --first-install

Key Files and Their Roles

Component	Path	Purpose
Main implementation	bin/omarchy-provision-user	Executes all user finalization steps
User install logic	install/user/all.sh	Fonts, icons, toolchains, and assets
Migration scripts	migrations/*.sh	System update scripts marked complete during --first-install
CLI registration	bin/omarchy	Exposes finalize as top-level command via GROUP_DESCRIPTIONS[finalize]
Design documentation	docs/file-layout.md	Describes idempotency marker system

When to Run omarchy finalize user

Run this command in these scenarios:

• After creating a new user account – completes setup that /etc/skel cannot provide
• After modifying skill packages – use --force to refresh symlinks
• During ISO builds – use --first-install to prepare the installation image
• After repository updates – re-run with --force to apply new defaults

Summary

• omarchy finalize user runs per-user configuration that requires runtime logic beyond /etc/skel copying
• The command is idempotent by default, skipping work if already completed unless --force is used
• Dev-aware symlinks ensure developers use live skill files from their checkout
• The script delegates to install/user/all.sh for fonts, icons, and toolchains
• --first-install mode marks migrations complete during ISO preparation
• All state is tracked in ~/.local/state/omarchy/done/ for reliable re-runnability

Frequently Asked Questions

Can omarchy finalize user be run multiple times?

Yes, the command is designed for safe re-execution. On subsequent runs, it exits early when finding the idempotency marker at ~/.local/state/omarchy/done/finalize-user. Use the --force flag to bypass this check and reapply all configuration steps.

Why can't this setup happen in /etc/skel?

/etc/skel only supports static file copying. The omarchy finalize user command performs dynamic operations—like creating symlinks to the current Omarchy checkout path and detecting the ISO chroot context—that require runtime evaluation of the actual environment.

What happens if I run omarchy finalize user as root?

The script aborts with an error. Per-user finalization must run as the target user account to ensure correct ownership of created files and proper resolution of $HOME and user-specific paths.

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

Use --first-install only when building ISO images or preparing pristine system images. This flag creates empty markers for all migration scripts, preventing them from executing on what is already a complete, up-to-date installation.

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