dotfiles

One declarative YAML file to manage dependencies, sync configuration files, and keep everything versioned.

Requirements

• macOS 13+
• Xcode Command Line Tools

Installation

git clone git@github.com:pkrll/dotfiles-cli.git
cd dotfiles-cli
make install

This builds a release binary and copies it to /usr/local/bin/dotfiles.

Quick start

dotfiles init                          # Create config at ~/.config/dotfiles/config.yml
dotfiles clone <repo-url>              # Clone your dotfiles repo
dotfiles install                       # Install all dependencies
dotfiles apply                         # Apply all configuration files

init creates a configuration file that stores the path to your dotfiles repository. clone clones the repo and registers that path automatically.

The Dotfile

Your dotfiles repository must contain a Dotfile at its root. This YAML manifest has two sections: install for dependencies and copy for configuration files.

install:
  - name: homebrew
    check: command -v brew
    install:
      - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  - name: packages
    requires: [homebrew]
    check: brew bundle check --file Brewfile
    install:
      - brew bundle --file Brewfile

copy:
  - name: zshrc
    source: config/zsh/.zshrc
    target: ~/.zshrc
    group: zsh

  - name: gitconfig
    source: config/git/.gitconfig
    target: ~/.gitconfig
    group: git
    skip_if_exists: true

install fields

Field	Required	Description
name	Yes	Unique identifier for the dependency
check	Yes	Shell command to test if already installed (exit 0 = installed)
install	Yes	Array of shell commands to run in sequence
requires	No	Array of dependency names that must succeed first

copy fields

Field	Required	Description
name	Yes	Display name, also used for filtering
source	Yes	Path relative to repo root (supports ~; can be a directory)
target	Yes	Destination path (supports ~; can be a directory)
group	No	Logical group name for bulk operations
skip_if_exists	No	If true, skip when target already exists

Commands

Command	Description
dotfiles init	Create the dotfiles configuration file at ~/.config/dotfiles/config.yml
dotfiles clone <url> [path]	Clone a dotfiles repository and register it locally. Defaults to ~/.config/dotfiles/repository
dotfiles install [name]	Install dependencies defined in the Dotfile. Optionally install a single dependency by name
dotfiles apply [names...] [-f]	Copy files from the repo to your system. Filter by name or group. -f overwrites without prompting
dotfiles save [names...] [-f]	Copy tracked files from your system back to the repo. Filter by name or group. -f overwrites without prompting
dotfiles push [-m message]	Stage, commit, and push the local repository. Default message: "Update dotfiles"
dotfiles pull [--rebase]	Pull latest changes from the remote. -r to rebase instead of merge
dotfiles config [key] [value] [-f]	Read or set a configuration value. -f creates the config file if it doesn't exist
dotfiles doctor	Check your setup: repo status, dependencies, and file sync

Global options

Flag	Description
-v, --verbose	Increase output detail
-q, --quiet	Suppress output

License

MIT