# Idempotency Marker for omarchy-provision-user: File Location and Implementation Guide

> Discover the idempotency marker for omarchy-provision-user, the finalize-user file, and learn how to prevent duplicate executions. Understand its implementation and `--force` flag.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-29

---

**The idempotency marker for `omarchy-provision-user` is the file `~/.local/state/omarchy/done/finalize-user`, which prevents duplicate execution of user finalization steps unless the script is invoked with the `--force` flag.**

The `omarchy-provision-user` script in the **basecamp/omarchy** repository implements idempotent per-user provisioning by tracking completion state through a marker file. This mechanism ensures that potentially destructive or time-consuming setup steps run exactly once per user account, making the script safe to execute repeatedly in automated workflows.

## What Is the Idempotency Marker for omarchy-provision-user?

The marker is a zero-byte or timestamp file located at:

```bash
~/.local/state/omarchy/done/finalize-user

```

According to the source code at line 22 of `bin/omarchy-provision-user`, this file serves as a persistent flag indicating that user finalization has completed successfully. When present, the script exits early to avoid re-running configuration steps that might overwrite custom user settings or regenerate credentials unnecessarily.

## How the Idempotency Check Works in bin/omarchy-provision-user

The script checks for the marker at startup using the `omarchy-done` helper utility. The logic explicitly tests for the marker and a non-forced execution state:

```bash
if omarchy-done check finalize-user && (( force == 0 )); then
    echo "User finalization already complete (rerun with --force to refresh)."
    exit 0
fi

```

**`omarchy-done check finalize-user`** returns a zero exit code if the marker file exists, causing the script to print a status message and terminate immediately. This check runs before any provisioning logic executes, guaranteeing that idempotency is enforced at the entry point.

## Marking Completion with omarchy-done mark

After successfully completing all provisioning steps, the script creates the idempotency marker:

```bash
omarchy-done mark finalize-user

```

This command ensures that subsequent invocations of `omarchy-provision-user` will detect the existing state and skip to completion. The marker persists in the user's home directory under `.local/state/`, following the XDG Base Directory Specification for state data.

## Bypassing the Marker with --force

Administrators can override the idempotency protection to re-provision a user or refresh configurations:

```bash

# Force re-provisioning regardless of marker status

omarchy-provision-user --force

```

When `--force` is supplied, the script sets `force=1`, which causes the conditional `(( force == 0 ))` to evaluate as false. This bypasses the early exit and executes the full provisioning routine, eventually rewriting the marker upon successful completion.

## Key Files and Helper Utilities

The idempotency system relies on three components documented in the basecamp/omarchy repository:

- **`bin/omarchy-provision-user`** – The main provisioning script that defines the marker logic at line 22 and orchestrates the user setup workflow.

- **`bin/omarchy-done`** – A helper utility that abstracts marker file operations, providing `check`, `mark`, and directory-creation subcommands for state management.

- **[`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md)** – Documentation specifying the location and purpose of marker files within the `~/.local/state/omarchy/` directory hierarchy.

## Summary

- The idempotency marker for `omarchy-provision-user` is the file `~/.local/state/omarchy/done/finalize-user`.
- The script checks this marker via `omarchy-done check finalize-user` at line 22 of `bin/omarchy-provision-user`.
- If the marker exists and `--force` is not provided, the script exits immediately without performing work.
- Use `omarchy-provision-user --force` to ignore the marker and re-run all provisioning steps.

## Frequently Asked Questions

### What is the exact file path of the idempotency marker?

The marker file is located at `~/.local/state/omarchy/done/finalize-user`. This path is hardcoded in `bin/omarchy-provision-user` and managed through the `omarchy-done` helper script.

### How do I force omarchy-provision-user to run again?

Invoke the script with the `--force` flag: `omarchy-provision-user --force`. This overrides the idempotency check and executes all provisioning steps regardless of whether the marker file exists.

### What is the omarchy-done utility?

`omarchy-done` is a helper program in the basecamp/omarchy repository that manages state markers. It provides subcommands like `check` to test for file existence and `mark` to create marker files, ensuring consistent state tracking across omarchy scripts.

### Where is the state directory for these markers documented?

The file layout and state directory structure are documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) within the omarchy repository. This file specifies that runtime state, including idempotency markers, belongs in `~/.local/state/omarchy/`.