↓ Skip to main content
Homie
Homie
  1. Documentation/

Quick start

Table of Contents

This walks through scaffolding a fresh Homie repo, putting your first dotfile under management, and bootstrapping the same environment on a second machine. About five minutes if you already have git + GitHub set up.

1. Install homie
#

One static binary, no runtime, no dependencies:

curl -fsSL https://homie.sh/install.sh | bash

Prefer not to pipe a script? See Install for manual download, version pinning, and building from source.

2. Scaffold a user environment repo
#

homie init writes a starter repo — homie.toml, a bootstrap.sh, an example dotfile, an example template, and a sample script — that’s yours to grow into.

homie init ~/dotfiles

It’ll ask for your name, email, and GitHub username so it can wire up bootstrap.sh with the right clone URL.

3. Push it to GitHub
#

Create an empty repo at github.com/<you>/dotfiles (or whatever you named it during homie init), then:

cd ~/dotfiles
git init -b main
git add -A
git commit -m "initial scaffold"
git remote add origin git@github.com:<you>/dotfiles.git
git push -u origin main

4. Apply on the machine you’re on
#

Reconcile your $HOME with the scaffolded repo:

homie apply

You’ll see Charm-styled progress as Homie installs the listed packages, symlinks your dotfiles, renders your templates, and runs your scripts.

5. Bootstrap on a fresh machine
#

On any other Linux or macOS box — bare metal, VM, container, Codespace — run:

curl https://raw.githubusercontent.com/<you>/dotfiles/main/bootstrap.sh | bash

That downloads the right homie binary for the OS and CPU, clones your repo, and runs homie apply. Done.

bootstrap.sh makes sure git is present first. On Linux it also installs ca-certificates if needed. On macOS git comes from the Xcode Command Line Tools (xcode-select --install), and Homebrew is not required — install it only if you declare [packages].

Even piped into bash, it hands your terminal down to homie, so a sudo password prompt from one of your setup scripts reaches you instead of failing. Run it in a container or CI, where there’s no terminal to hand down, and nothing changes.

Where to next?
#

  • Commands — every homie subcommand explained.
  • homie.toml — full config reference.
  • Dotfiles — symlinks, templates, tag-gated trees, overrides.
  • Recipes — concrete patterns for common setups.