How the omarchy-dev-link and omarchy-dev-unlink Commands Set Up a Development Checkout

The omarchy-dev-link and omarchy-dev-unlink commands manage the OMARCHY_PATH environment variable and sudo secure_path to switch between a packaged Omarchy installation and a local development checkout.

The omacom/omarchy repository includes specialized CLI tooling that allows developers to test changes without rebuilding or reinstalling the entire package. The omarchy-dev-link and omarchy-dev-unlink commands form the core mechanism for setting up a development checkout, enabling seamless transitions between stable system directories and live code repositories.

Understanding the Development Checkout Workflow

Omarchy resolves its installation location through the OMARCHY_PATH environment variable, which is typically set to /usr/share/omarchy in production environments. When developing new features or debugging issues, developers need the system to reference a local checkout—such as ~/omarchy—instead of the immutable system directory. The omarchy-dev-link command performs this redirection by rewriting system configuration files, while omarchy-dev-unlink provides a safe rollback mechanism.

How omarchy-dev-link Configures the System

The omarchy-dev-link script, located at bin/omarchy-dev-link in the omacom/omarchy repository, performs atomic configuration changes to redirect both user-level and privileged operations.

Updating the Core Configuration File

First, the command writes a new /etc/omarchy.conf that explicitly sets OMARCHY_PATH to the user-provided checkout directory. This ensures that shell sessions, systemd services, and application launchers initiated after a reboot will resolve Omarchy resources from the development location rather than /usr/share/omarchy.

Injecting the Development Bin Directory into secure_path

Simultaneously, the script creates a temporary sudoers file at /etc/sudoers.d/omarchy-dev-path. This drop-in prepends the checkout's bin directory to the secure_path variable used by sudo. This configuration maintains a critical separation: unprivileged omarchy-* calls execute from the development checkout, while sudo operations continue using the packaged version until the system reboots and reloads the environment.

Validation and Safety Checks

Before writing any system files, the script validates that the target directory contains a valid Omarchy structure. It builds a safe sudoers entry syntax to prevent configuration errors that could lock users out of privileged operations.

How omarchy-dev-unlink Reverts to Production

The omarchy-dev-unlink command, implemented in bin/omarchy-dev-unlink, reverses the linking process. It restores /etc/omarchy.conf to point OMARCHY_PATH back to /usr/share/omarchy and removes the /etc/sudoers.d/omarchy-dev-path drop-in file. This immediately restores the default secure_path for sudo, ensuring that subsequent privileged operations use the production binaries.

Like its counterpart, this command supports the --no-reboot flag to skip the interactive reboot prompt when you plan to restart the system manually later.

Practical Examples for Daily Development

Link a local checkout to begin testing modifications:

omarchy dev link ~/omarchy

Link without the reboot prompt when managing restart timing manually:

omarchy dev link ~/omarchy --no-reboot

Return to the packaged version after completing development:

omarchy dev unlink

Or unlink without immediate reboot:

omarchy dev unlink --no-reboot

Understanding the Reboot Requirement

Configuration changes only take full effect after a system reboot because the running Hyprland session, systemd services, active shells, and application launchers all cache the original OMARCHY_PATH value. While new terminal sessions may pick up changes to /etc/omarchy.conf, the desktop environment and background services require a restart to synchronize all layers. Both commands optionally prompt for an immediate reboot to ensure consistent behavior across the entire stack.

Summary

• omarchy-dev-link rewrites /etc/omarchy.conf to point OMARCHY_PATH at your development checkout and creates /etc/sudoers.d/omarchy-dev-path to prepend the checkout's bin directory to the sudo secure_path.
• omarchy-dev-unlink restores the default configuration, setting OMARCHY_PATH back to /usr/share/omarchy and removing the custom sudoers drop-in.
• Both commands validate target directories and support --no-reboot to skip the restart prompt.
• Changes require a reboot to synchronize the Hyprland desktop environment, systemd services, and cached environment variables across the system.

Frequently Asked Questions

What is the difference between the OMARCHY_PATH used by regular users versus sudo after running omarchy-dev-link?

After linking, unprivileged omarchy-* commands resolve from your development checkout via the updated OMARCHY_PATH, while sudo continues using the packaged version in /usr/share/omarchy until reboot. This safety mechanism prevents breaking privileged operations with potentially unstable development code.

Where does omarchy-dev-link store its configuration changes?

According to the omacom/omarchy source code, the command writes the environment variable to /etc/omarchy.conf and creates a sudoers drop-in at /etc/sudoers.d/omarchy-dev-path to modify the secure_path variable.

Can I switch between multiple development checkouts without rebooting?

You can run omarchy dev link with a new path at any time to update /etc/omarchy.conf, but the changes only take full effect after rebooting. Active sessions continue using the previously cached OMARCHY_PATH until the system restarts.

Is it safe to run omarchy-dev-unlink if I deleted the development checkout directory?

Yes. The omarchy-dev-unlink command in bin/omarchy-dev-unlink simply removes the sudoers drop-in and resets /etc/omarchy.conf to the default production path. It does not require the original checkout to exist, making it safe to run as a cleanup operation even after deleting the development directory.

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