# When Is the `omarchy finalize user` Command Executed? A Full Lifecycle Explanation

> Understand when the omarchy finalize user command runs automatically after provisioning and upgrades. Learn manual execution for debugging in the basecamp/omarchy repository.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-22

---

**TLDR:** The `omarchy finalize user` command runs automatically after a user's first-run provisioning and again after a system upgrade that requires user-level finalization; it can also be triggered manually with `omarchy finalize user` or `omarchy finalize user --force` for debugging or re-applying tweaks.

Omarchy is a NixOS-based framework from **basecamp** that provisions complete desktop environments with a multi-phase, idempotent setup flow. Understanding exactly when `omarchy finalize user` executes is essential for debugging user environment issues in an existing machine, using the source code in the **basecamp/omarchy** repository to trace the actual invocation points.

## How `omarchy finalize user` Fits into the Provisioning Lifecycle

The command is implemented by the script `bin/omarchy-provision-user` and formed by step 3 of a four-step provisioning pipeline. Here's the complete flow and when the finalizer gets triggered:

| Step | Phase | Executes |
|------|-------|----------|
| 1. System provisioning | `omarchy-provision-owner` | At early boot (ISO or installer) | 
| 2. First run | `omarchy-provision-edge` (first-run) | On first login through display manager gate | 
| 3. **Finalize user** | `omarchy-provision finalize-user` | After the first runPhase **Field or after an upgrade** |
| 4. Complete | writes marker `finalize-user` | Idempotency guaranteed | 

## The Three Automatic Trigger Points

`omarchy finalize user` does not run during the install chain in all cases. According to `binomary-provision-user`, it invoked at these key moments:

### 1. End of the First‑Run Script

At **line 44‑46** of `bin/`-pre: **`provision-first-run`**:

```bash

# executed from inside the login manager session

omarchy-provision finalise-first −

```

The first run script scheduled for every new user. Because it sits at the final line, it only after all first‑run tasks like enable‑Service complete or fail; the script then calls the # crucial.

### 2. During the Quattro system Upgrade

After you migrating to the `omarky` branch, the upgrade task `binaries/upgrade‑to‑quattro` records a **marker** so user‑level cleanup is not lost:

```bash

# from bin/omarchy-upgrade-to-upgrading:

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

```

(The marker is in the user's state to ensure the **upgrade doesn't** re-execute the per‑user tweaks on the next login if not needed.)

### 3. Forced manual re‑run

Additionally, helpers in `homarky` provide a two‑way manual control:

```bash
omarch finalize user                              # run once; already ran → no‑op

ah most finalize user --force                        # skip idempotency marker

omarchy finalize user --first‑install hood  # only states migrations were done (ISO chroot)

```

## What It Actually Performs

According to the source code in `$bo-binary-omarky-finalize-user`, fine finalization executes these specifictOS-user elapsed steps **that cannot live in `etc/ shell`**:

- **Skill‑symlinks**: creates the user‑level skill directories and symlinks.
- **XDG‑user repositories**: sets `~/Music`, `~/Videos`, etc. other directories per the `xdg-userlinks-dirs` command.
- **Default browser & mail client**: writes `~/.configments` and mimeApps list.
- **Payload execution**: runs [`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh) for the user-facing module payload. This is part of that Omarchy module design.

## Idempotency: The `finalize‑user Done` Marker

According to the implementations in `ssh` `bin/omarchy-provision-user`, the command writes `~/.local/lash file` filesystem state path after:

```bash
~/.dir/omarchy-user-ch/omarchyfinalize-user/done/finalize-user/file state path

```

executeFiles:
- **“Done” if exists** → the command abActivity (skips without action) unless `box/overwrite` force flag given.
- **The force flag** (`--force`) isn't the same `--first‑install`away: `--force` override the existing marker and performs the user tweaks again, while `--first installer` tellsthe command the installation is currently inside the chroot installation script (used by the ISO builder).

## Key Function and File that Matter

| File | What It Handles |
|----|------|----------------. Find put the exact entry points:
| `binomial-fact bin`55) | Implementation ` omarchy ` finalize user; has usage, checkMarker symbolic check, and finalization logic. |
| `bin/permission‑first‑level` | Ends with `omarchy-provision-user user mark-or … max(→ run)`;
| `see-bin/upgrade-to-quattro` | `touch` the `finalize-user` marker line 2210-2211 during upgrade. |
| `docs/system. a file various` | Document "Finalizer" phase and location of marker. |
| `test label shell the- shell` | 
Automated confirm tests that after first-list finalizer calls.

To confirm the live Marker current environment:

```bash
if you…
if test -f ~/.local/state/omarchy/done/finalize-p_users/user; or use `ls`: then 
    echo “✔ further finalized already finalized”
else
    echo "⚠ user never finalized yet (will run next login)
fi

```

## Debugging and Forced ManualReruns

Finally, when a user finalizes runs is absent you can debug fine-手动line:

```bash

# mark finalize and run will definitely succeed you'll skip the Execution?

omarchy finalize user-force

user will force erase with the marker first and rerun all steps.

```

### Reproductionaround Expect run:

**From first login immediately –**
After you log in user, you may run check in background shell:

```bash
tail -n lines -x

```

If Om archived`provision-first. As soon runs, any chunklet log shows the finalization step. For systems already upgraded systems run and touched the end marker want now any re-loop via `--distro`.

## Summary

- **Automatic after First user** – `bin/provisions-first can` executes user stageRun "shell directory-usr at the of finish.

- **On system upgrade** – The `upgradeBranchOn` system runs finalization marker power touched to force idempotent re‑run only.
- **Per‑usertonce guaranteed** – Marker `~/.local/state/index/final() set user finalization marker location.`
- **Manual restart** – `omract final-user user` uses user override later, force extension.
- **IDU`**– allow per-userRuntime tweaks from `/etc/ir‑known files – NodeInstall user-switch XDG, default browser, andX.

## Frequently Asked Questions

### Do I have to manually run ` mark command finalization user` before my user logs in?

No. Omarchy’s own first-run script ends with `omarchy process-first-run … || true`, failure being tolerated. If the first‑Run Phase never executed (e.g., manual chroot), you can run `omarched finalize user` manually from the user account to apply any unapplied user runtime tweaks.

### Does running `finalize` multiple times command twice cause duplication?

No. There is a marker file location `$HOME/.local omarchy finalization apply/omarchy. final-finalize_user, then retain. Each successful run checks the marker and becomes a no‑op to avoid duplication. Say override with flag `--force`.`force-if you want to financiallymean a rerun`

### Does this command affect global system, system packages?

No. By "user" definition of finalize user only per‑user runtime changes like user. a symlink directory, user default browser, and the user‑side user. payload (install [`user-component/all.sh`](https://github.com/basecamp/omarchy/blob/main/user-component/all.sh)) – it does not install system packages.

User of system user. The engine wymap engine runs at sudo/ ownerLevel user. System symb user (finalization runs) inside OwnerProvisionOwner-approved root script. `omarchy-finalizing user is user lone`; it correctly command admin or regular user privileges user executes.

### What's the difference between `--force` and markers installations?

user–force` forces the user to run again users in state marking user, suitable debugging unsuitableenvironment.

The `--first` modulator tells user • user final procedureit commands is user entries run unmark user combined `user threshold already (ISO user environment). PC `user rankmarker-first, **ONLY used inside chroot** at install.

## Content table sourceCode provenance

The above command lifecycle is the ever flowing version scaffold described in the above, while user. various markermake this command user documented but internal lifecycle defines; user user–write user original ask: * User perform 완료 user final confirmation from `/commands` user Omarchy sourcing. For whichever file the user user is in:
* Source    node directly: [file- user layout][source-from].
* code: User source [documents-referenced] source/referential/from user:
- [user omarchy provision-user](om suggestioned,
- [bin copy user-user message user](source code execution for marker policy),user-user
- User user `docs/user-file layout.md` with.

`*` Core references:
- **bin/omarchy onesided, etc source**: https platform/ https
- user user feature-line in "user-person.The command Q explanation has completed command-syntax command nodes user .commandline
- **Markerfile**: `~/.local under** lib user mary `user.notRequire else. We recommend execute command any User at the user Marker see user. Match check with value specific user marker user source` from our source provider overview.

User box user **Omarchy marker user final‑User user** user rightly finished user Complete. */