How to Update the Omarchy CLI: A Complete Guide to Safe System Upgrades

Run omarchy update to execute an atomic upgrade of the CLI and system packages with automatic Btrfs snapshots, or append the -y flag for unattended automation.

The Omarchy command-line interface provides a sophisticated update mechanism that coordinates package upgrades, system migrations, and safety checks in a single command. This guide explains how to update the Omarchy CLI using the built-in omarchy update command, its safety features, and the underlying scripts that ensure reliable system maintenance.

Running the Basic Omarchy CLI Update

To initiate a standard interactive update, execute the primary entry point located at bin/omarchy-update:

omarchy update

This command orchestrates the entire upgrade process, prompting for confirmation before critical steps and providing colored feedback through a built-in error trap. The script first acquires an exclusive lock via bin/omarchy-update-lock to prevent race conditions with other package managers, then proceeds through a coordinated sequence of sub-scripts.

Pre-Update Safety Mechanisms

Before modifying any system components, the update process performs mandatory safety checks to ensure system stability.

Lock and Disk Space Verification

The omarchy-update-lock script guarantees that only one update instance runs at any time, eliminating conflicts with concurrent package operations. Immediately after acquiring the lock, the system runs omarchy-update-requires-free-space to verify sufficient disk capacity exists for the upgrade.

Btrfs Snapshot Creation

If Snapper is present, the update sequence executes omarchy-snapshot create to generate a restore point before any changes occur. This atomic upgrade approach means you can revert the entire system state if the update introduces regressions.

The Omarchy CLI Update Execution Chain

The bin/omarchy-update script executes a fixed, idempotent chain of sub-commands that separate concerns into discrete, testable operations:

1. omarchy-update-pkg-prune – Cleans the package cache to free disk space
2. omarchy-snapshot create – Captures a Btrfs snapshot for rollback capability
3. omarchy-update-stay-awake start – Prevents system sleep during the upgrade
4. omarchy-update-dev – Refreshes development tools
5. omarchy-update-keyring – Updates GPG keyrings for package validation
6. omarchy-update-system-pkgs – Upgrades core Arch packages via pacman
7. omarchy-migrate – Executes pending database or configuration migrations
8. omarchy-hook post-update – Triggers user-defined post-update hooks
9. omarchy-update-aur-pkgs – Handles Arch User Repository package updates
10. omarchy-update-mise – Updates mise tool versions
11. omarchy-update-orphan-pkgs – Removes orphaned dependencies
12. omarchy-update-analyze-logs – Inspects logs for errors
13. omarchy-update-status – Updates the UI availability indicator
14. omarchy-update-restart – Reboots the system if necessary

This architecture ensures each step completes successfully before the next begins, making the CLI update reliable and predictable.

Automating Unattended Updates

For scripting and automation scenarios where user interaction is impossible, Omarchy supports unattended mode:

omarchy update -y

Passing the -y flag sets the environment variable OMARCHY_UPDATE_UNATTENDED=1, automatically confirming all prompts and allowing the update to run in CI/CD pipelines or scheduled maintenance windows.

Checking Update Availability

To determine whether updates are pending without starting the installation process, use the check command:

omarchy update-available

When updates are available, the Omarchy UI displays a circle-arrow icon next to the system clock, providing visual feedback without requiring terminal access. Detailed documentation for this workflow appears in manual/30-updates.md.

Rolling Back Failed Updates

If an update introduces system instability, the Btrfs snapshot captured during omarchy-snapshot create can be restored. Unlike other operations performed via the CLI, rollback happens at the boot loader level rather than through a terminal command. Restart the system and select the pre-update snapshot from the boot menu to revert to the previous system state instantly.

Summary

• Primary command: omarchy update initiates the full upgrade sequence via bin/omarchy-update
• Automation: Append -y or set OMARCHY_UPDATE_UNATTENDED=1 for unattended execution
• Safety: Exclusive locking via bin/omarchy-update-lock and Btrfs snapshots prevent system corruption
• Components: The process updates system packages, AUR packages, mise tools, and runs migrations atomically
• Recovery: Failed updates can be reverted using boot-time Btrfs snapshot restoration

Frequently Asked Questions

What is the command to update the Omarchy CLI?

Execute omarchy update in your terminal. This calls the main script at bin/omarchy-update, which coordinates package upgrades, snapshot creation, and system migrations in a single atomic operation.

How do I run an Omarchy update without interactive prompts?

Append the -y flag: omarchy update -y. This enables unattended mode by setting OMARCHY_UPDATE_UNATTENDED=1, automatically confirming all prompts and suitable for cron jobs or automation scripts.

What protects against failed or interrupted updates?

The bin/omarchy-update-lock script prevents concurrent update attempts that could corrupt the package database, while mandatory Btrfs snapshots created via omarchy-snapshot create provide a boot-time rollback path if the upgrade fails.

Where is the Omarchy update logic implemented in the source code?

The entry point resides in bin/omarchy-update, with individual phases separated into dedicated scripts like bin/omarchy-update-system-pkgs for pacman operations and bin/omarchy-update-aur-pkgs for AUR handling. User-facing documentation is maintained in manual/30-updates.md.

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