# How the omarchy-dev-link and omarchy-dev-unlink Commands Set Up a Development Checkout > Learn how omarchy-dev-link and omarchy-dev-unlink commands manage your OMARCHY_PATH and sudo secure_path to easily switch between packaged Omarchy and local development checkouts. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-09 --- **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`](https://github.com/omacom/omarchy/blob/main//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`](https://github.com/omacom/omarchy/blob/main//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: ```bash omarchy dev link ~/omarchy ``` Link without the reboot prompt when managing restart timing manually: ```bash omarchy dev link ~/omarchy --no-reboot ``` Return to the packaged version after completing development: ```bash omarchy dev unlink ``` Or unlink without immediate reboot: ```bash 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`](https://github.com/omacom/omarchy/blob/main//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`](https://github.com/omacom/omarchy/blob/main//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`](https://github.com/omacom/omarchy/blob/main//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`](https://github.com/omacom/omarchy/blob/main//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`](https://github.com/omacom/omarchy/blob/main//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.