Package Management

Package Management

Heimdal provides a unified interface for managing packages across multiple package managers. Packages are defined directly in heimdal.yaml under each profile's packages: section — there is no external package database, no network fetching, and no local cache.

Table of Contents

• Overview
• Supported Package Managers
• Basic Commands
• Package Search
• Configuration
• Top-Level Packages
• Troubleshooting

Overview

Heimdal's package system:

• Config-driven — packages live in heimdal.yaml; add/remove commands modify the config file directly
• Native search — packages search delegates to the native package manager (brew search, apt-cache search, etc.)
• Per-manager lists — each manager has its own list; no cross-platform name mapping
• common key — use common: for packages that share the same name on all platforms; Heimdal installs them via the first available package manager on the current OS

Supported Package Managers

Heimdal automatically detects your platform and installs only from the appropriate manager(s):

Key	Manager	Platform
common	Detected PM	Any — installs via the first available PM
homebrew	Homebrew formulae	macOS / Linux
homebrew_casks	Homebrew casks	macOS
apt	APT	Debian / Ubuntu
dnf	DNF	Fedora / RHEL
pacman	Pacman	Arch Linux
apk	APK	Alpine Linux
mas	Mac App Store	macOS

Keys for managers not available on the current OS are silently skipped.

Basic Commands

Add a Package

# Add to config and install immediately
heimdal packages add neovim --manager homebrew

# Add to config only (skip installation)
heimdal packages add neovim --manager homebrew --no-install

Remove a Package

# Remove from config and uninstall from system
heimdal packages remove neovim

# Remove from config only (leave installed on system)
heimdal packages remove neovim --no-uninstall

List Packages

# List all packages defined in the current profile's config
heimdal packages list

# List only packages that are currently installed on the system
heimdal packages list --installed

Get Package Information

# Shells out to the native PM's info command
heimdal packages info neovim

Package Search

packages search shells out directly to the native package manager — there is no local database:

heimdal packages search ripgrep

What this does per platform:

Platform	Command run
macOS	brew search <query>
Debian/Ubuntu	apt-cache search <query>
Fedora/RHEL	dnf search <query>
Arch Linux	pacman -Ss <query>
Alpine	apk search <query>

If the native PM is not available on the current OS, Heimdal displays the command you would need to run manually.

Configuration

Packages in heimdal.yaml

Packages are organized under packages: within each profile:

profiles:
  default:
    packages:
      common: [git, curl, vim]         # installed on any OS via detected PM
      homebrew: [ripgrep, fzf]         # macOS/Linux — Homebrew
      homebrew_casks: [iterm2]         # macOS only — Homebrew casks
      apt: [ripgrep, fzf, build-essential]  # Debian/Ubuntu
      dnf: [ripgrep, fzf, gcc]         # Fedora/RHEL
      pacman: [ripgrep, fzf, base-devel]    # Arch Linux
      apk: [ripgrep, fzf, alpine-sdk]  # Alpine Linux
      mas:
        - { id: 497799835, name: Xcode }
        - "Amphetamine"

Profile-Specific Packages

Add packages only for certain profiles:

profiles:
  work:
    extends: default
    packages:
      homebrew: [slack, zoom, kubectl]
      homebrew_casks: [postman]

  personal:
    extends: default
    packages:
      homebrew_casks: [spotify, discord]

When work extends default, packages are unioned: the effective homebrew list for work includes both the default packages and the work-specific ones.

Top-Level Packages

You can define packages outside any profile, at the top level. These are applied to every profile:

# Applied to ALL profiles on ALL machines
packages:
  common: [git, curl, vim]
  homebrew: [mas]

profiles:
  default:
    packages:
      common: [ripgrep]
  work:
    extends: default
    packages:
      homebrew: [slack]

On a macOS machine running the work profile, Heimdal installs: git, curl, vim (common), mas (homebrew top-level), ripgrep (common from default), and slack (homebrew from work).

Troubleshooting

Package manager not found

which brew    # or apt-get, dnf, pacman, apk

If Homebrew is missing on macOS:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Package not found

Use search to verify the correct package name:

heimdal packages search <partial-name>
# or directly:
brew search <name>
apt-cache search <name>

Package already installed warning

This is informational — Heimdal skips packages that are already installed. It is not an error.

---

Next: Dotfile Management

See also: Configuration Reference