# Omarchy CLI Commands for Package Management: A Complete Guide

> Master Omarchy CLI commands for package management. Discover eight pkg subcommands offering safe, idempotent Arch Linux installs and unified help.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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:

```bash

# 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.

```bash

# 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.

```bash

# 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.

```bash

# 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.

```bash

# 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.

```bash

# 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.

```bash

# 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.

```bash

# 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

```bash

# 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.