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.