Hofii

An orchestration tool for managing dotfiles and packages declaratively on Linux.

---

Overview

Hofii is a declarative dotfile manager for Linux that helps you:

• Manage symlinks for configuration files across your system
• Install packages from multiple package managers (pacman, AUR, Flatpak)
• Detect your environment automatically (distro, package manager, AUR helper)
• Track state with a lock file for reproducible configurations

Installation

Prerequisites

• Bun (v1.0+)
• Linux (Arch-based distributions fully supported)

bun add -g hofii

Only support with bun

Commands

Command	Alias	Description
hofii scan	s	Detect system environment (OS, package manager, AUR helper, Flatpak)
hofii validate [dir]	v	Validate configuration files
hofii switch [dir]	sw	Switch to new configuration (apply symlinks)

Configuration Reference

Settings

[settings]
aur_helper = "yay"    # AUR helper: "yay" or "paru"
backup = true         # Backup existing files before creating symlinks
flatpak = true        # Enable Flatpak support (auto-detected)

Symlinks

[[symlinks]]
source = "./config/nvim"    # Relative to config.toml directory
target = "~/.config/nvim"   # Target path (~ expands to $HOME)
sudo = false                # Use sudo for creation (default: false)

Imports (Modular Config)

Split your config across multiple files:

# config.toml
imports = ["home.toml", "work.toml"]

[[symlinks]]
source = "./config/shared"
target = "~/.config/shared"

# home.toml
[[symlinks]]
source = "./config/hyprland"
target = "~/.config/hyprland"

Project Structure

hofii/
├── src/
│   ├── commands/      # CLI commands (scan, validate, switch)
│   ├── core/
│   │   ├── config/    # Config parsing & validation (schema, parser)
│   │   ├── detect.ts  # Environment detection
│   │   ├── diff.ts    # Config diffing
│   │   └── symlink.ts # Symlink operations
│   ├── data/
│   │   ├── env.ts     # Environment variables
│   │   ├── metadata.ts # Lock file management (~/.cache/hofii/)
│   │   └── os.ts      # OS/Package manager detection
│   ├── pm/
│   │   └── pacman.ts  # Pacman package operations
│   ├── types/         # TypeScript types
│   └── utils/         # Utilities (fs, path, spawn)
├── example/           # Example configurations
├── dist/              # Built output
└── index.ts           # Entry point

Lock File

Hofii maintains a lock file at ~/.cache/hofii/hofii-lock.json that tracks:

• Applied symlinks (source, target, sudo)
• Configuration state

This enables:

• Diffing between current and desired state
• Safe removal of symlinks no longer in config
• Reproducible deployments

Example Configuration

See the example/ directory for a complete working configuration:

example/
├── config.toml          # Main config with symlinks
├── home.toml            # Additional config (imported)
├── config/
│   ├── fastfetch/
│   ├── btop/
│   └── ...
└── .state/              # Example lock file

Supported Distributions

Distribution	Package Manager	Status
Arch Linux	pacman	✅ Full support
EndeavourOS	pacman	✅ Full support
Manjaro	pacman	✅ Full support
Garuda	pacman	✅ Full support
CachyOS	pacman	✅ Full support
Fedora	dnf	🔄 Planned
Nobara	dnf	🔄 Planned

License

MIT License - see LICENSE for details.

---

Note: Hofii is in early development. Use with caution and always review the diff before applying changes.