What Is the Omarchy-Dev-Link Workflow? A Complete Developer's Guide

The omarchy-dev-link workflow is a development-only helper that re-targets the Omarchy runtime to a local source checkout by overriding the sudo secure_path and persisting the checkout location, requiring only a reboot to activate.

The omarchy-dev-link workflow enables developers to test local modifications in a live Omarchy environment without rebuilding or reinstalling the package. Located in the omacom/omarchy repository at bin/omarchy-dev-link, this utility redirects system binaries and configuration paths to your working directory through targeted overrides. Understanding this workflow is essential for anyone contributing to core development or testing changes in the omacom/omarchy codebase.

How the Omarchy-Dev-Link Workflow Works

This workflow operates through four tightly-coupled actions that safely redirect system resources to your development checkout.

Validation and Security Checks

The script begins by validating the execution context to prevent environment contamination. It explicitly rejects execution under sudo to avoid polluting the root environment, as implemented in lines 10-13 of bin/omarchy-dev-link. This safeguard ensures that development paths remain isolated from privileged system contexts during the linking process.

Secure Path Override Mechanism

The workflow constructs a temporary sudoers fragment that prepends your checkout's bin/ directory to the system secure_path. This fragment is written to /etc/sudoers.d/omarchy-dev-path only after passing a visudo syntax check (source lines 99-105). The effect is immediate: subsequent sudo omarchy-* commands resolve to the checkout's binaries rather than the packaged system versions.

Persisting the Checkout Location

The absolute path of your checkout is saved to /etc/omarchy.conf as the OMARCHY_PATH environment variable (source lines 109-113). Many Omarchy components—including shell scripts in shell/, theme assets in themes/, and default configurations in default/—resolve paths relative to this variable, making the redirection comprehensive across the application stack.

Reboot Activation

Because the OMARCHY_PATH variable affects the running user session, a reboot is required to fully activate the linked environment. Unless invoked with the --no-reboot flag, the script presents an interactive reboot prompt using gum confirm and triggers omarchy-system-reboot upon affirmation (source lines 21-23).

Using the Omarchy-Dev-Link Command

Basic usage requires only the path to your local checkout:

# Point Omarchy at a checkout and trigger a reboot prompt

omarchy dev link ~/src/omarchy

For automation or chaining commands, suppress the reboot prompt:

# Suppress reboot – useful when the next command handles restarting

omarchy dev link ~/src/omarchy --no-reboot

To restore the original system configuration, use the companion unlink command:

# Undo the link and remove overrides

omarchy dev unlink

Verify the configuration took effect by inspecting the persisted files:

# Check the persisted path in the configuration

cat /etc/omarchy.conf

# Verify the secure_path override in sudoers

sudo cat /etc/sudoers.d/omarchy-dev-path

Scope and Limitations of the Workflow

The omarchy-dev-link workflow deliberately limits its scope to resources that are path-resolved via OMARCHY_PATH. This includes directories such as bin/, default/, shell/, themes/, applications/, and config/ within your checkout.

Fixed-system assets remain untouched. Files under /etc/ (outside the omarchy.conf entry) or /usr/lib/systemd/ are not modified by this workflow. If you need to test changes to these system-level components, you must rebuild the package using omarchy-dev-pkg-test instead.

Summary

• The omarchy-dev-link workflow connects local source checkouts to the running Omarchy system without package reinstallation or rebuilding.
• It creates a sudoers fragment at /etc/sudoers.d/omarchy-dev-path to override the secure_path for elevated commands, routing sudo omarchy-* calls to your checkout.
• The checkout location is persisted to /etc/omarchy.conf as OMARCHY_PATH for system-wide path resolution across shell scripts and assets.
• A reboot is required to activate the changes in the user session, though the --no-reboot flag allows deferring this step when chaining commands.
• Use omarchy-dev-unlink (via omarchy dev unlink) to restore the original system configuration and remove all path overrides.

Frequently Asked Questions

What is the difference between omarchy-dev-link and omarchy-dev-pkg-test?

omarchy-dev-link redirects path-resolved resources to a local checkout by modifying OMARCHY_PATH and the sudo secure_path, requiring only a reboot to test changes. In contrast, omarchy-dev-pkg-test performs a full package rebuild and installation, which is necessary when modifying fixed-system assets like files under /etc/ or systemd units that cannot be resolved through path variables.

Why does omarchy-dev-link require a reboot?

The workflow persists the checkout location to /etc/omarchy.conf as OMARCHY_PATH, which many components reference during session initialization. Since environment variables for running processes cannot be modified retroactively, a reboot ensures that the new user session and all Omarchy services initialize with the correct path context derived from your linked checkout.

How do I undo a dev link and restore the system configuration?

Execute omarchy dev unlink to remove the sudoers fragment at /etc/sudoers.d/omarchy-dev-path and delete the /etc/omarchy.conf file, restoring the system's default binary paths. This command is implemented in bin/omarchy-dev-unlink and immediately restores the original configuration without requiring a package reinstall.

Is it safe to run omarchy-dev-link multiple times?

Yes, running the command multiple times is safe. Each execution overwrites the previous configuration in /etc/omarchy.conf and /etc/sudoers.d/omarchy-dev-path with the new checkout path after passing the same visudo validation checks. However, you must reboot after each change to ensure the running session reflects the latest OMARCHY_PATH variable.

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