Omarchy CLI Commands for Package Management: A Complete Guide

Omarchy provides eight pkg subcommands that wrap Arch Linux package tools with automatic safety checks, idempotent installs, and unified help output.

Omarchy is an open-source Arch Linux configuration framework that automates system setup through a structured CLI. The package management commands are central to this workflow, exposing Arch's pacman and AUR helpers through a consistent, scriptable interface. All pkg commands live in dedicated binaries under bin/omarchy-pkg-* and are registered automatically by the core dispatcher in bin/omarchy.

How Omarchy Registers Package Commands

The Omarchy CLI uses a metadata-driven dispatcher pattern. Each command binary contains structured comments that the dispatcher parses at startup:

# omarchy:summary=Install Arch packages if they are missing

# omarchy:args=<packages...>

# omarchy:examples=omarchy pkg add jq ripgrep

# omarchy:requires-sudo=true

In bin/omarchy, the load_commands function scans all bin/omarchy-* files, extracts this metadata, and builds command routes. The resolve_route and dispatch_fast_or_help functions then map human-readable commands like omarchy pkg add to the underlying binary omarchy-pkg-add, handling --help and --json flags automatically.

This design means new package commands can be added by dropping a properly annotated binary into the bin/ directory — no manual registration required.

Core Package Installation Commands

omarchy pkg add: Idempotent Package Installation

pkg add installs Arch packages only if they are missing. It first calls pkg missing to filter the package list, then runs pacman -S for the remaining items.

# Install git, wget, and zsh only if not already present

omarchy pkg add git wget zsh

The implementation in bin/omarchy-pkg-add uses the pkg missing helper to avoid redundant pacman calls, making this command safe to run repeatedly in scripts.

omarchy pkg missing: List Uninstalled Packages

pkg missing returns the subset of requested packages that are not currently installed. This is the internal mechanism that enables pkg add's idempotency.

# Check which Python packages need installation

omarchy pkg missing python python-pip python-virtualenv

This command exits with success regardless of missing packages, outputting only the package names that require installation.

omarchy pkg present: Verify Installation Status

pkg present validates that all specified packages are installed, returning a non-zero exit code if any are missing. Use this for pre-flight checks in deployment scripts.

# Ensure required tools are available before proceeding

if ! omarchy pkg present curl jq; then
  echo "Required tools are missing"
  exit 1
fi

Package Removal Commands

omarchy pkg remove: Standard Package Removal

pkg remove wraps pacman -R for safe, interactive package removal. It preserves configuration files and asks for confirmation.

# Remove vim while keeping its configuration

omarchy pkg remove vim

omarchy pkg drop: Force Remove Without Confirmation

pkg drop provides non-interactive removal via pacman -Rns, purging configuration files and unused dependencies. This is the preferred command for automated cleanup.

# Silently remove Firefox and its dependencies

omarchy pkg drop firefox

The -Rns flags in bin/omarchy-pkg-drop ensure complete removal: -R for remove, -n for nosave (config files), -s for recursive dependency cleanup.

AUR Package Management Commands

omarchy pkg aur install and omarchy pkg aur add

pkg aur install installs packages from the Arch User Repository using the system's configured AUR helper (e.g., yay). pkg aur add is an alias that maintains naming consistency with the pkg add command.

# Install a package from AUR

omarchy pkg aur install visual-studio-code-bin

# Same operation using the alias

omarchy pkg aur add neovim-nightly

The underlying binary bin/omarchy-pkg-aur-install delegates to the detected AUR helper, abstracting away tool-specific syntax.

omarchy pkg aur accessible: Check AUR Helper Availability

pkg aur accessible verifies that an AUR helper is installed and functional on the system.

# Test if AUR operations are supported

if omarchy pkg aur accessible; then
  omarchy pkg aur install my-aur-package
else
  echo "AUR helper not available"
fi

This check prevents failures in environments where AUR support hasn't been configured.

Command Safety Features

All Omarchy package management commands implement three safety mechanisms:

• Automatic sudo escalation — Commands with omarchy:requires-sudo=true in their metadata prompt for or automatically use sudo when not running as root
• Idempotent operations — pkg add never reinstalls existing packages, preventing unnecessary system changes
• Unified error handling — The dispatcher in bin/omarchy standardizes exit codes and error formatting across all package commands

Complete Usage Examples

# Initialize a new development environment

omarchy pkg add git neovim tmux ripgrep fd

# Verify toolchain before building

omarchy pkg present base-devel cmake python || omarchy pkg add base-devel cmake python

# Clean up after migration to new editor

omarchy pkg drop vim gvim

# Install AUR-based development tools

omarchy pkg aur install jetbrains-toolbox google-chrome

# Script-friendly batch installation

MISSING=$(omarchy pkg missing docker docker-compose)
[ -n "$MISSING" ] && omarchy pkg add $MISSING

Summary

• Eight package commands are available under the omarchy pkg namespace: add, remove, drop, present, missing, aur install, aur add, and aur accessible
• Source files are located in bin/omarchy-pkg-* with metadata-driven registration via bin/omarchy
• Idempotent installs through pkg add prevent redundant pacman operations
• AUR support is abstracted through pkg aur subcommands with automatic helper detection
• Safety features include automatic sudo handling and unified error formatting

Frequently Asked Questions

What makes omarchy pkg add different from running pacman -S directly?

omarchy pkg add checks which packages are missing before invoking pacman, making it idempotent. You can run the same pkg add command multiple times without reinstalling existing packages. It also handles sudo automatically when omarchy:requires-sudo=true is set in bin/omarchy-pkg-add.

Where are the Omarchy package command implementations stored?

Each command is a dedicated executable in the repository's bin/ directory: bin/omarchy-pkg-add, bin/omarchy-pkg-remove, bin/omarchy-pkg-drop, bin/omarchy-pkg-present, bin/omarchy-pkg-missing, bin/omarchy-pkg-aur-install, bin/omarchy-pkg-aur-add, and bin/omarchy-pkg-aur-accessible.

How does Omarchy detect and use AUR helpers?

The omarchy-pkg-aur-accessible command checks for common AUR helpers like yay. When present, omarchy-pkg-aur-install and omarchy-pkg-aur-add delegate package operations to the detected helper, abstracting away tool-specific syntax while maintaining consistent exit codes and output formatting.

Can I add custom package management commands to Omarchy?

Yes. Create a new executable bin/omarchy-pkg-<yourcommand> with the required metadata comments (omarchy:summary, omarchy:args, omarchy:examples, and optionally omarchy:requires-sudo). The dispatcher in bin/omarchy will automatically register it as omarchy pkg <yourcommand> on next run.

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