How to Install Packages (Including AUR) Using Omarchy’s Helper Commands

Omarchy provides thin wrapper scripts in bin/ that unify installation from official Arch repositories and the AUR through a single omarchy-pkg-add command.

Omarchy ships a suite of Bash helper commands that streamline software management on Arch-based systems. These wrappers abstract the distinction between official repository packages and Arch User Repository (AUR) builds, allowing you to install software with one consistent interface regardless of the source. The primary workflow centers on omarchy-pkg-add, which automatically handles the complexity of routing between package managers.

The Primary Package Installation Workflow

The omarchy-pkg-add script serves as the main entry point for installing software. Located at bin/omarchy-pkg-add in the repository, this helper determines whether a package exists in the official repositories or requires building from the AUR.

When you invoke omarchy-pkg-add, the script executes the following logic:

1. Attempts installation via pacman -S to search official Arch repositories.
2. Falls back to AUR helper (defaulting to yay -S) if the package is not found in official repos.
3. Handles edge cases including single confirmation prompts, transient network failure retries, and automatic cleanup of build artifacts after successful installation.

Available Package Helper Commands

Omarchy provides several complementary utilities for package management, all residing in the bin/ directory and documented in AGENTS.md:

• omarchy-pkg-add – Install packages from official repos or AUR.
• omarchy-pkg-drop – Remove installed packages using pacman -Rns or yay -Rns as appropriate.
• omarchy-pkg-present – Returns exit code 0 if a package is installed (useful for conditional scripting).
• omarchy-pkg-missing – Returns exit code 0 if a package is not installed.
• omarchy-pkg-aur-add – Internal helper for direct AUR installation (rarely invoked manually).

Because these are thin wrappers, they inherit your existing pacman.conf, mirror settings, keyrings, and AUR helper configurations automatically.

Installing from Official Repositories vs. AUR

Official Repository Installation

For packages available in the core, extra, or community repositories, omarchy-pkg-add delegates to pacman:

omarchy-pkg-add vim git

This executes sudo pacman -S --needed vim git, respecting your pacman configuration and only installing if the package is not already present.

AUR Installation

When a package does not exist in official repositories, the helper automatically switches to the AUR pathway:

omarchy-pkg-add joplin-bin

The script detects that joplin-bin is absent from official repos and executes yay -S joplin-bin instead, handling the build process and dependency resolution without manual intervention.

Checking Package Status and Removal

Use omarchy-pkg-present to verify installation status within scripts:

if omarchy-pkg-present vlc; then
    echo "VLC is already installed"
else
    omarchy-pkg-add vlc
fi

To remove software, use omarchy-pkg-drop, which automatically selects the appropriate removal command:

omarchy-pkg-drop brave-bin

This invokes either pacman -Rns or yay -Rns depending on how the package was originally installed.

Technical Implementation Details

The core logic lives in bin/omarchy-pkg-add, which you can inspect to see the exact conditional logic governing the pacman → yay fallback sequence. According to the Omarchy source code, the script handles confirmation aggregation to prevent multiple password prompts during batch installations.

The command registry in AGENTS.md lists all package helpers alongside their metadata, while the underlying command routing system is documented in related agent configuration files. Tests exercising these helpers appear in files like test/shell.d/default-apps-test.sh, demonstrating their use in automated scenarios.

Usage Examples

Install a standard package from official repositories:

omarchy-pkg-add firefox

Install an AUR-only package:

omarchy-pkg-add visual-studio-code-bin

Install multiple packages mixing both sources:

omarchy-pkg-add git chromium brave-bin

Check if a package exists before deciding to install:

omarchy-pkg-missing docker && omarchy-pkg-add docker

Summary

• omarchy-pkg-add unifies installation from official Arch repos and the AUR via automatic fallback logic.
• Helper scripts reside in bin/ and are registered in AGENTS.md.
• The workflow tries pacman -S first, then falls back to yay -S for AUR packages.
• omarchy-pkg-present and omarchy-pkg-missing enable conditional installation checks in scripts.
• omarchy-pkg-drop handles removal regardless of the original installation source.
• All helpers inherit existing pacman and AUR helper configurations transparently.

Frequently Asked Questions

What is the difference between omarchy-pkg-add and running pacman directly?

omarchy-pkg-add is a thin wrapper that first attempts pacman -S for official repositories, then automatically falls back to an AUR helper like yay if the package is not found. This eliminates the need to manually determine whether a package is in the official repos or the AUR before choosing your install command.

Can I install multiple packages at once with Omarchy helpers?

Yes. Pass multiple package names as arguments to omarchy-pkg-add: omarchy-pkg-add git vim firefox. The helper processes each package sequentially, automatically routing each one to either pacman or the AUR helper as needed.

How do I remove a package installed via omarchy-pkg-add?

Use the omarchy-pkg-drop command followed by the package name. This helper automatically determines whether to use pacman -Rns or yay -Rns based on the package's origin, ensuring complete removal including unused dependencies.

Where are the Omarchy package helper scripts located?

The executable scripts reside in the bin/ directory of the Omarchy repository. The primary installation logic is in bin/omarchy-pkg-add, while the command metadata and registry are documented in AGENTS.md. These files define the behavior and routing of all package management helpers.

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