A universal dotfile and system configuration manager built in Rust

Heimdal automatically manages your dotfiles, installs packages, and keeps your development environment in sync across multiple machines. Built with Rust for performance and reliability.

📖 Full Documentation | 💬 Discussions

Homebrew (macOS)

brew install limistah/tap/heimdal

APT (Debian/Ubuntu)

# One-line setup
curl -fsSL https://raw.githubusercontent.com/limistah/heimdal/main/scripts/install-deb.sh | bash

# Or manual
curl -fsSL https://limistah.github.io/heimdal/gpg | sudo gpg --dearmor -o /usr/share/keyrings/heimdal-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/heimdal-archive-keyring.gpg] https://limistah.github.io/heimdal/deb stable main" | sudo tee /etc/apt/sources.list.d/heimdal.list
sudo apt update && sudo apt install heimdal

Cargo (All Platforms)

cargo install heimdal

Universal installer

curl -fsSL https://raw.githubusercontent.com/limistah/heimdal/main/install.sh | bash

More installation options: Installation Guide →

New to dotfiles?

heimdal wizard

The interactive wizard guides you through:

• Smart scanning with real-time progress
• Interactive file and package selection
• Smart profile names (auto-generated from hostname/OS)
• Git sync setup with remote configuration

Migrating from Stow, dotbot, chezmoi, yadm, or homesick?

heimdal wizard  # Choose "Import existing dotfiles"
heimdal import --path ~/.dotfiles --preview  # Preview before importing

Cloning to a new machine?

git clone <your-dotfiles-repo> ~/.dotfiles
cd ~/.dotfiles
heimdal apply

Learn more →

• 📦 Universal Package Management - One config for Homebrew, APT, DNF, Pacman, and Mac App Store
• 🔗 Intelligent Symlinking - GNU Stow-compatible with automatic conflict resolution
• 🎯 Smart Package Discovery - Native OS package manager search (brew, apt, dnf, pacman, apk)
• 🔐 Secret Management - Secure storage using OS keychains (macOS Keychain, Linux Secret Service)
• 🎨 Template System - Machine-specific configs with variable substitution
• 🌿 Git-Based Sync - Keep configs in sync across machines with automatic conflict detection
• 🎭 Profile System - Different configs for work, personal, and server machines
• 🤖 Interactive Wizard - Guided setup with smart defaults
• 🚀 Import Support - Migrate from Stow, dotbot, chezmoi, yadm, homesick
• 🔄 Rollback Support - Easily revert to previous configurations
• 🪝 Hooks System - Run custom scripts before/after installation
• 🔍 Dry-Run Mode - Preview changes before applying them

Explore all features →

Packages are declared directly in heimdal.yaml using a packages: section. Use common: for packages with the same name across all OS package managers, or per-manager keys (homebrew:, apt:, dnf:, pacman:, apk:) when names differ or a package is OS-specific. A top-level packages: section applies to all profiles; each profile can also define its own packages:.

heimdal:
  version: "1"
  repo: "[email protected]:you/dotfiles.git"

packages:
  common: [git, curl, vim, tmux]  # same name everywhere, every profile
  homebrew: [mas]                  # mac only, every profile

profiles:
  default:
    packages:
      common: [ripgrep, fzf]
      homebrew: [iterm2]
      apt: [build-essential]

  work:
    extends: default
    packages:
      homebrew: [slack, zoom]

# Search via the native OS package manager
heimdal packages search neovim

# Add a package to heimdal.yaml
heimdal packages add neovim

• macOS: Homebrew (formulae + casks), Mac App Store (via mas)
• Debian/Ubuntu: APT
• Fedora/RHEL/CentOS: DNF/YUM
• Arch/Manjaro: Pacman
• Alpine: apk

• ✅ Dependency detection and suggestions
• ✅ Installation status checking

The main CLI tool - installation, configuration, and management commands.

Contribute here for:

• 🐛 Bug fixes and issue reports
• ✨ New CLI features and commands
• 🔧 Core functionality improvements
• 📚 Documentation updates

Development Guide →

User → Heimdal CLI → Package Manager (brew/apt/dnf/pacman/apk)
                    ├─→ Dotfile Management (GNU Stow compatible)
                    ├─→ Secret Management (OS Keychain)
                    └─→ Git Sync (with state management)

• 📖 Quick Start Guide
• 📦 Package Management
• 🎭 Profile System
• 📁 Dotfile Management
• 🎨 Template System
• 🔐 Secret Management
• 🌿 Git Sync
• ⚙️ Configuration Reference
• 🐛 Troubleshooting

• 🔧 CLI Development Guide
• 🧪 Testing Guide
• 🤝 Contributing Guide

• 🏗️ Architecture Overview
• 🔒 State Management - Locking, conflict resolution
• 🗺️ Module Guide - Codebase structure

Here's a minimal heimdal.yaml to get started:

heimdal:
  version: "1"
  repo: "[email protected]:you/dotfiles.git"

packages:
  common: [git, curl, vim, tmux]  # same name everywhere, every profile
  homebrew: [mas]                  # mac only, every profile

profiles:
  default:
    packages:
      common: [ripgrep, fzf]
      homebrew: [iterm2]
      apt: [build-essential]

  work:
    extends: default
    packages:
      homebrew: [slack, zoom]

More examples:

• Minimal configuration
• Full-featured setup
• Cross-platform configuration

# Initialize a new dotfiles repository
heimdal wizard

# Apply your configuration
heimdal apply

# Sync changes to/from Git
heimdal sync

# Check status
heimdal status

# Switch profiles
heimdal profile switch personal

# Validate configuration
heimdal validate

# Search for packages via the native OS package manager
heimdal packages search ripgrep

# Add a package to heimdal.yaml
heimdal packages add ripgrep

# List installed packages
heimdal packages list --installed

# Dry-run before applying
heimdal apply --dry-run

# Import from existing dotfiles
heimdal import --path ~/old-dotfiles

# Rollback to previous state
heimdal rollback

# View sync history
heimdal history

# Manage secrets
heimdal secret set API_KEY "secret-value"
heimdal secret get API_KEY

See full CLI reference →

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 💬 Questions: GitHub Discussions

We welcome contributions! Here's how to get involved:

1. Fork this repository
2. Clone your fork: git clone <your-fork-url>
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Make your changes
5. Run tests: cargo test
6. Run clippy: cargo clippy --all-targets
7. Commit your changes: git commit -m 'Add amazing feature'
8. Push to your fork: git push origin feature/amazing-feature
9. Open a Pull Request

See full CLI development guide →

Heimdal uses the following directories:

• ~/.heimdal/ - Heimdal state and data
  • state.json - Current state (active profile, last sync, etc.)
  • backups/ - Backup of overwritten files
• ~/.dotfiles/ - Default dotfiles directory (customizable via config)
• /usr/local/bin/heimdal - Heimdal binary (or ~/.cargo/bin/heimdal)

MIT License - see LICENSE for details

• Inspired by GNU Stow, Homebrew, and various dotfile management tools
• Built with Rust for performance and reliability
• Thanks to all contributors and users!

• Main Repository: https://github.com/limistah/heimdal
• Documentation: https://github.com/limistah/heimdal/wiki
• Crates.io: https://crates.io/crates/heimdal
• Changelog: CHANGELOG.md

Built by @limistah