How to Trigger Omarchy Migrations: Complete Command Reference and Automation Guide

Omarchy migrations are triggered by running the omarchy-migrate command, which executes pending shell scripts from the migrations/ directory and records completion state per-user under ~/.local/state/omarchy/migrations/.

Understanding how to trigger Omarchy migrations is essential for keeping your Arch Linux-based system up to date. Migrations are small shell scripts that handle per-user upgrades and system repairs after package updates, making them a core part of the Omarchy maintenance workflow according to the omacom/omarchy source code.

What Omarchy Migrations Are and Where They Live

Migration scripts in Omarchy serve as automated, idempotent upgrade procedures. Each script lives in the repository's migrations/*.sh directory and performs specific transition tasks when the system or user configuration needs to change.

State tracking happens per-user. When a migration completes successfully, Omarchy creates a marker file under ~/.local/state/omarchy/migrations/<script-name>. This prevents re-execution and ensures each migration runs exactly once per user account.

The omarchy-migrate Command: Core Trigger Mechanism

The primary way to trigger Omarchy migrations is through the omarchy-migrate script located at bin/omarchy-migrate. This thin wrapper handles discovery, locking, and execution with strict error handling.

What the Command Does

• Waits for pacman transactions – Ensures no package manager conflicts
• Scans migrations/ directory – Identifies scripts without completion markers
• Executes with bash -euo pipefail – Strict mode: exits on any error
• Records success or failure – Creates state marker regardless of outcome

Running Migrations Manually

To trigger all pending migrations immediately:

omarchy-migrate

This executes every migration that lacks a completion marker in your user state directory, stopping at the first failure.

Checking Pending Migrations Without Running Them

Use the diagnostic flag to preview what's queued:

omarchy-migrate --pending

Exit status 0 means migrations are waiting; non-zero means you're fully up to date. This flag powers automation tools and notification systems.

Automatic Trigger Points: When Migrations Run Without Manual Action

Omarchy provides three built-in trigger mechanisms beyond manual invocation.

After Package Updates via omarchy update

The standard omarchy update command automatically triggers migrations once Pacman finishes. The sequence is: update packages, then run omarchy-migrate. No separate step required.

# This triggers migrations automatically after pacman completes

omarchy update

Post-Manual Pacman Upgrade

If you run pacman directly, trigger migrations afterward:

sudo pacman -Syu    # standard Arch system update

omarchy-migrate     # apply any new migrations the update introduced

Desktop Notification Service

A per-user systemd unit handles GUI environments. The omarchy-migrate-notify.service (defined at default/systemd/user/omarchy-migrate-notify.service) runs at login and:

• Monitors for pending migrations using omarchy-migrate --pending
• Displays a clickable desktop notification when work is needed
• Launches omarchy-migrate when the user clicks the notification

No configuration required—this provides zero-friction migration triggering for desktop users.

Migration Script Structure and Requirements

Understanding script anatomy helps when debugging or writing custom migrations.

Standard Migration Template

#!/usr/bin/env bash
set -euo pipefail

# Migration work here

# -e: exit on error

# -u: treat unset variables as errors

# -o pipefail: pipeline fails if any command fails

# Create directories, update configs, etc.

mkdir -p ~/.config/omarchy/custom

# Exit 0 marks completion (success or handled failure)

Privilege Handling

Migrations run as the current user. For tasks requiring root access, delegate to helper scripts that request administrator rights through standard mechanisms. The migration marks complete regardless of privilege-helper success to avoid infinite prompting loops.

Migration State and Idempotency

The completion tracking system enforces single execution per user.

State Directory Layout

~/.local/state/omarchy/migrations/
├── 001-fix-paths.sh      # marker file exists = completed

├── 002-update-themes.sh  # missing = pending

└── 003-new-defaults.sh   # missing = pending

Idempotency Guarantees

• Script absence from state directory → eligible for execution
• Script presence in state directory → skipped permanently
• Failed scripts still create markers → no retry without manual intervention

To re-run a migration, manually remove its marker file from the state directory.

Troubleshooting Migration Triggers

Migrations Not Running Automatically

1. Verify the notification service is enabled: systemctl --user status omarchy-migrate-notify.service
2. Check for pending migrations manually: omarchy-migrate --pending
3. Review the update process documentation at docs/update-process.md

Migration Failures Abort the Queue

When one migration fails, subsequent migrations do not run. Fix the failing script or temporarily bypass it by creating its marker file manually (not recommended for production systems).

State Directory Permissions

Ensure ~/.local/state/omarchy/ is owned by your user. Migration recording will fail silently if the state directory is unwritable.

Summary

• Primary trigger command: omarchy-migrate executes pending migration scripts from migrations/*.sh
• Automatic triggers: omarchy update and systemd notification service (omarchy-migrate-notify.service)
• State tracking: Per-user completion markers in ~/.local/state/omarchy/migrations/<script-name>
• Diagnostic mode: omarchy-migrate --pending lists queued work without executing
• Execution model: bash -euo pipefail with fail-fast behavior across the migration queue

Frequently Asked Questions

How do I know if I have pending Omarchy migrations?

Run omarchy-migrate --pending. Exit code 0 indicates pending migrations exist; non-zero means all migrations are complete. The notification service also visualizes this status graphically on desktop environments.

Can I run Omarchy migrations as root?

Migrations are designed for per-user execution and run as the calling user. Root execution would create state markers in root's home directory, not your user's. For privileged operations, migrations should call privilege-escalation helpers rather than running as root directly.

What happens if a migration fails?

The failing migration creates its completion marker to prevent retry loops, and omarchy-migrate exits immediately without running subsequent migrations. You must fix the underlying issue manually or remove the marker file to reattempt that specific migration.

How are migrations triggered after a manual pacman update?

The omarchy-migrate command does not automatically detect manual pacman -Syu runs. You must invoke it manually after package updates when using pacman directly instead of omarchy update, which handles the trigger automatically.

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