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

> Discover what the omarchy finalize user command does. Learn about per user runtime finalization, symlinks, directory setup, and application defaults for your omarchy setup.

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

---

**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](https://github.com/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.

```bash

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

```bash

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