How OMARCHY_PATH Is Set and Why Omarchy Commands Rely on It Instead of $HOME

The OMARCHY_PATH environment variable is injected by the uwsm session manager or defaulted to /usr/share/omarchy by the bootstrap script, serving as the single source of truth for locating Omarchy binaries and configuration files independent of the user's $HOME directory.

The omacom/omarchy repository uses OMARCHY_PATH to establish a reliable, immutable reference to the installation root, ensuring scripts can locate binaries, default configurations, and plugins regardless of user context or privilege level. This variable is initialized early in the session lifecycle and validated before any command execution, preventing path resolution errors that would occur if commands relied on $HOME inference.

How OMARCHY_PATH Is Initialized

UWSM Session Injection

In standard graphical sessions, the uwsm (Universal Wayland Session Manager) process explicitly injects OMARCHY_PATH into the environment before spawning the shell. According to the source comments in shell/shell.qml at line 26, this value is "provided by the uwsm" and made available to all descendant processes. This ensures the variable is present before any user interaction begins.

Bash Bootstrap Fallback

When OMARCHY_PATH is not present—such as in headless sessions or SSH connections—the default/bash/env-bootstrap script supplies a safe system-wide default. Lines 1‑24 of this file define and export the variable:

# Located in default/bash/env-bootstrap

export OMARCHY_PATH="${OMARCHY_PATH:-/usr/share/omarchy}"

This fallback assumes a standard system package installation, though the script also checks for /etc/omarchy.conf to allow administrators to override the path globally.

System Configuration Overrides

The bootstrap mechanism sources /etc/omarchy.conf if it exists, allowing the variable to be persistently customized without modifying shell profiles. Additionally, the bin/omarchy-dev-link and bin/omarchy-dev-unlink utilities manipulate this configuration file to dynamically switch between a system package (/usr/share/omarchy) and a local development checkout.

Why Commands Prefer OMARCHY_PATH Over $HOME

Commands throughout the codebase explicitly check for and utilize OMARCHY_PATH rather than inferring locations from $HOME for five critical architectural reasons:

Installation Isolation
Hardcoding paths relative to $HOME would bind Omarchy resources to the user's personal directory, preventing clean system-wide installations where binaries live under /usr/share. OMARCHY_PATH decouples the installation location from the user's home entirely.

Multiple Concurrent Checkouts
A developer may simultaneously run a stable system package at /usr/share/omarchy and a development build at ~/dev/omarchy. By setting OMARCHY_PATH per-session or per-terminal, each invocation unambiguously targets the correct tree without $HOME collisions.

Privilege Escalation Consistency
Many Omarchy utilities execute with elevated privileges via sudo or pkexec, which reset $HOME to /root. Because OMARCHY_PATH is explicitly passed through the environment (or re-derived from /etc/omarchy.conf), privileged commands continue to locate resources correctly even when the root home directory differs from the invoking user's.

Centralized Path Management
The bootstrap script handles complex PATH manipulation—prepending $OMARCHY_PATH/bin while removing duplicates—in a single location. If each command computed paths from $HOME, this logic would be scattered and prone to drift. Instead, etc/profile.d/omarchy.sh sources the bootstrap once, ensuring consistent path construction.

Security and Integrity Validation
Several administrative commands, including omarchy-update-dev, verify that OMARCHY_PATH points to a valid git checkout or trusted location before proceeding. These checks would be meaningless if the path were inferred from $HOME, as arbitrary user directories could impersonate system resources.

Implementation in Source Files

The enforcement of OMARCHY_PATH is visible in several critical source locations:

• bin/omarchy-shell (line 40): Performs an early sanity check that aborts execution with a clear error message if the variable is unset or empty.
• default/bash/env-bootstrap (lines 1‑24): Defines the default value as /usr/share/omarchy and handles the /etc/omarchy.conf override logic.
• etc/profile.d/omarchy.sh: Sources the bootstrap script for all interactive login shells, ensuring the variable is available in terminal sessions.
• shell/shell.qml (line 26): Documents that the variable is provided by uwsm for graphical sessions.
• bin/omarchy-dev-link / bin/omarchy-dev-unlink: Rewrite /etc/omarchy.conf to redirect the system-wide default to a development checkout.

Practical Usage Examples

Inspect the current value injected by your session manager or bootstrap script:

echo "$OMARCHY_PATH"

# Output: /usr/share/omarchy

Temporarily switch to a development checkout for testing:

export OMARCHY_PATH="/home/alice/projects/omarchy"

# Subsequent omarchy commands now use the development tree

Verify the variable is set before executing a command programmatically, matching the validation pattern in bin/omarchy-shell:

if [[ -z "${OMARCHY_PATH}" ]]; then
  echo "Error: OMARCHY_PATH is not set" >&2
  exit 1
fi

"${OMARCHY_PATH}/bin/omarchy-shell" --help

Summary

• OMARCHY_PATH is initialized by uwsm in graphical sessions or defaulted to /usr/share/omarchy by default/bash/env-bootstrap in shell environments.
• The variable allows multiple installations to coexist and enables privileged commands to locate resources correctly despite $HOME changes during elevation.
• Path manipulation and security checks are centralized in the bootstrap script rather than distributed across individual utilities.
• Commands like omarchy-shell validate the variable's presence at startup, failing fast with a clear error if it is missing.
• Development workflows use omarchy-dev-link to rewrite /etc/omarchy.conf, changing the default path without altering user dotfiles.

Frequently Asked Questions

What happens if OMARCHY_PATH is not set?

Commands will abort with a diagnostic error. For example, bin/omarchy-shell explicitly checks for the variable at line 40 and exits with status 1 if it is unset, preventing execution against an undefined installation root.

Can I use OMARCHY_PATH for multiple development checkouts?

Yes. By exporting different values in separate terminal sessions (e.g., export OMARCHY_PATH=~/work/omarchy-feature-x in one window and export OMARCHY_PATH=~/work/omarchy-feature-y in another), you can run distinct versions simultaneously without installation conflicts.

How does OMARCHY_PATH handle privilege escalation?

When you run sudo, the $HOME environment variable typically changes to /root, which would break path resolution if Omarchy relied on home directory inference. However, OMARCHY_PATH is either preserved through the environment or re-read from /etc/omarchy.conf, ensuring elevated processes still locate the correct /usr/share/omarchy resources.

Where is the default OMARCHY_PATH defined?

The default value /usr/share/omarchy is hardcoded in default/bash/env-bootstrap at lines 1‑24. This script is sourced by etc/profile.d/omarchy.sh for interactive shells, ensuring the fallback is available even when uwsm is not managing the session.

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