How Omarchy's `env-bootstrap` Mechanism Prepares Your Shell Environment

env-bootstrap is a lightweight Bash script in default/bash/env-bootstrap that sets OMARCHY_PATH and constructs a clean, priority-ordered PATH before any Omarchy commands run.

The Omarchy env-bootstrap mechanism ensures every shell session starts with predictable environment variables and command resolution. Whether you're running a default installation or an active development checkout, this script guarantees Omarchy resources are found first without polluting your system. Let's examine how it works by analyzing the source code in basecamp/omarchy.

How OMARCHY_PATH Gets Resolved

The first job of env-bootstrap is determining where Omarchy resources live. The script handles two distinct modes:

• Default mode: Resolves to the system installation at /usr/share/omarchy
• Linked mode: Resolves to your active development checkout directory (e.g., /home/user/omarchy/quattro/active)

This dual-mode behavior is verified by tests in test/shell.d/dev-env-path-test.sh, which confirm the script reports the correct path in both scenarios.

PATH Construction Rules

The Omarchy env-bootstrap mechanism builds PATH through a specific ordering strategy that prioritizes Omarchy commands while preserving user customizations.

Prepend Omarchy Binaries

The script prepends $OMARCHY_PATH/bin so Omarchy commands take precedence over system equivalents:

# After sourcing, $OMARCHY_PATH/bin appears first

PATH="/home/user/omarchy/quattro/active/bin:/usr/bin:..."

Preserve Existing Entries

Unrelated entries already in your PATH are preserved exactly as they were. The script does not strip or reorder non-Omarchy paths.

Append User-Level Locations

Common user directories are appended for accessibility:

• ~/.local/share/mise/shims
• ~/.local/bin

Eliminate Duplicates

The linked_duplicate_path test confirms that duplicate entries are removed to prevent PATH bloat when sourcing multiple times.

Edge Case Handling

The env-bootstrap script anticipates several real-world scenarios:

Scenario	Behavior
Empty original PATH	Builds clean PATH from Omarchy bin plus user directories
zsh shell	zsh_path test ensures identical ordering and preservation rules
Multiple sourcing	Idempotent execution—safe from multiple startup files
Missing source file	Guarded by [ -r … ] check before sourcing

Safety and Idempotency

The script is deliberately lightweight and guards against errors:

# Typical sourcing pattern from /etc/profile.d/omarchy.sh

if [[ -r /usr/share/omarchy/default/bash/env-bootstrap ]]; then
  . /usr/share/omarchy/default/bash/env-bootstrap
fi

This pattern from etc/profile.d/omarchy.sh demonstrates how the bootstrap integrates with system-wide shell initialization.

Key Files in the env-bootstrap System

File	Purpose
default/bash/env-bootstrap	Core bootstrap logic implementation
test/shell.d/dev-env-path-test.sh	Automated tests documenting expected behavior
etc/profile.d/omarchy.sh	System-wide entry point for sourcing
default/bash/envs	Interactive shell wrapper ensuring bootstrap loads
docs/file-layout.md	Documentation referencing bootstrap location and purpose

Verification Examples

After the Omarchy env-bootstrap mechanism runs, verify your environment:

# Check resolution results

echo "OMARCHY_PATH → $OMARCHY_PATH"
echo "PATH → $PATH"

# Example linked checkout output:

# OMARCHY_PATH → /home/user/omarchy/quattro/active

# PATH → /home/user/omarchy/quattro/active/bin:/usr/bin:/home/user/.local/share/mise/shims:/home/user/.local/bin

Summary

• default/bash/env-bootstrap implements the core Omarchy env-bootstrap mechanism
• Resolves OMARCHY_PATH for both default (/usr/share/omarchy) and linked (active checkout) modes
• Constructs PATH by prepending Omarchy binaries, preserving existing entries, appending user directories, and removing duplicates
• Handles edge cases including empty PATH, zsh compatibility, and safe re-sourcing
• Integrated via etc/profile.d/omarchy.sh and tested in test/shell.d/dev-env-path-test.sh

Frequently Asked Questions

Where is the env-bootstrap script located in Omarchy?

The script lives at default/bash/env-bootstrap in the repository. According to the Omarchy source code, this path is referenced from etc/profile.d/omarchy.sh for system-wide initialization and from default/bash/envs for interactive shells. The location is also documented in docs/file-layout.md.

How does Omarchy handle development checkouts versus default installations?

The env-bootstrap mechanism detects linked mode and resolves OMARCHY_PATH to your active checkout directory rather than /usr/share/omarchy. Tests in test/shell.d/dev-env-path-test.sh verify both resolution behaviors, ensuring developers work against their current code while default installations use system resources.

Why does my PATH have Omarchy directories first after sourcing?

This is intentional design. The script prepends $OMARCHY_PATH/bin to ensure Omarchy commands shadow system equivalents of the same name. Your original entries are preserved after this prefix, and user directories like ~/.local/bin are appended at the end.

Is env-bootstrap safe to run multiple times?

Yes. The script is idempotent and lightweight. The linked_duplicate_path test specifically validates that duplicate entries are removed, so repeated sourcing does not inflate your PATH with redundant entries.

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