Installation

dotfix ships as two pieces: the dotfix command-line tool and an optional menubar app. The command-line tool is the one that matters — the background check runs it, and it can do everything the app can.

Requirements

macOS	13 (Ventura) or later, Apple silicon or Intel
Homebrew	Required. dotfix manages packages through it and will not set up without it.
Git	Required. Your configuration is an ordinary Git repository.
GitHub CLI (gh)	Optional. Only used to offer creating the remote repository for you during setup.

With Homebrew

The usual way:

brew tap NoiXdev/tap
brew install dotfix

brew upgrade dotfix from then on. The tap carries final releases only, so this will never hand you a pre-release — which is also why a beta has to come from the release page below.

From the release page

For a pre-release, or when you would rather not use Homebrew. Find the version you want on the releases page and set it once:

VERSION=1.0.0

The command-line tool

base="https://github.com/NoiXdev/dotfix/releases/download/v$VERSION"
curl -fsSLO "$base/dotfix-v$VERSION-macos-universal.tar.gz"
curl -fsSLO "$base/checksum.txt"
shasum -a 256 -c checksum.txt

tar -xzf "dotfix-v$VERSION-macos-universal.tar.gz"
sudo mv dotfix /usr/local/bin/
dotfix --version

Caution

Download it with curl, not through a browser. The binary carries only an ad-hoc signature, and macOS quarantines anything a browser downloads — Gatekeeper then refuses to run it. If you already have a quarantined copy, clear the flag with xattr -d com.apple.quarantine dotfix. Installing through Homebrew avoids this entirely.

The menubar app

Open dotfix_<version>_universal.dmg from the same release and drag dotfix into Applications. The app is signed with a Developer ID and notarized, so it opens without a warning.

Run it from /Applications — it registers itself as a login item only from there, so a copy left in a build directory cannot claim your login item and then disappear on the next clean build.

Build from source

If you would rather compile it yourself, see Build from source. The LaunchAgent note below applies either way.

Note

The background check runs through a LaunchAgent, which does not inherit your interactive shell’s PATH. dotfix records the PATH it was installed with, and dotfix doctor checks that the agent can still find everything it needs.

Updating

brew upgrade dotfix, or download the new tarball and replace the binary the same way. dotfix about says whether a newer release exists — it asks only when you run it, never on a timer. From source:

git pull
cargo install --path crates/cli --force

Next steps

• Set up your first machine.
• Already have a dotfix repository? Add another Mac.