macstrap

Bootstrap a modern macOS dev environment, in one command

Reproducible, profile-aware macOS setup on chezmoi and mise. One repo for personal and work machines — secrets never committed.

---

How it works

Set up a Mac or fork this repo — same flow:

install once → pick a profile → dotfiles + runtimes + tools → health check → maintain

1. Install once — one-liner installs Homebrew, clones the repo, links macstrap onto PATH.
2. Pick a profile — personal or work drives git identity, packages, and signing.
3. Configure — dotfiles (chezmoi), runtimes (mise), core toolchain, apps, health check. Idempotent.
4. Add tools on demand — macstrap apps / macstrap cli; selections replay on the next Mac.
5. Maintain — macstrap doctor, macstrap diff, macstrap apply, macstrap update, macstrap report.

Preview with macstrap install --dry-run. Revert with macstrap uninstall. Identity and keys stay in machine-local config.

Quick start

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/XavierAgostino/macstrap/main/install.sh)"

Already have Homebrew? brew install XavierAgostino/tap/macstrap gets the binary; the one-liner above does the full bootstrap.

Open a new terminal:

macstrap install              # default stack (asks: personal or work?)
macstrap install --minimal    # shell, git, chezmoi, mise, CLI core only
macstrap install --work --apps
macstrap doctor               # health check
macstrap apps                 # pick GUI apps
macstrap cli                  # pick optional project CLIs
macstrap update               # pull latest and apply

Full walkthrough: docs/SETUP.md.

Tip

Dry run: macstrap install --dry-run. Quiet by default — add --verbose for full output.

What's installed

Core toolchain — chezmoi · mise · starship · ghostty · git · gh · eza · bat · fd · ripgrep · fzf · zoxide · jq · tmux · pnpm · uv · 1Password

Default apps

Cursor	VS Code	Claude Code	Ghostty
Chrome	Raycast	Rectangle	1Password
OrbStack	TablePlus	Figma	Slack
Zoom	Notion	Obsidian	Spotify

Customize via brew/Brewfile.{core,apps,personal,work} · full list in SETUP §7

The TUI

Run macstrap with no arguments — dashboard, Doctor, searchable Apps/CLI pickers, Report, Security, Logs, and an Install dry-run preview.

macstrap            # interactive dashboard
macstrap doctor     # scriptable — add --json for machines
macstrap logs       # step logs from the last run

See it in action

Scripted walkthroughs — macstrap demo <name> installs nothing.

Demo	Command
Setup preview	macstrap demo
App picker	macstrap demo apps
CLI picker	macstrap demo cli
Doctor	macstrap demo doctor

App picker

CLI picker

Doctor

CLI catalog: SETUP §6 · Regenerate GIFs: DEMOS.md

Manual setup and env vars

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
eval "$(/opt/homebrew/bin/brew shellenv)"
git clone https://github.com/XavierAgostino/macstrap.git ~/Developer/workspaces/macstrap
bash ~/Developer/workspaces/macstrap/scripts/bootstrap.sh

Env vars for agents and CI: MODE=minimal|default|interactive|headless|doctor, PROFILE=personal|work, APPS=0|default|interactive|a,b,c, DRY_RUN=1. Example: PROFILE=work APPS=cursor,orbstack bash scripts/bootstrap.sh. See docs/AGENT-USAGE.md.

Profiles (personal vs work)

One profile at chezmoi init drives git identity, Brewfiles, and signing — docs/work-separation.md.

Important

With signing enabled, 1Password must be unlocked to commit. Bypass once with git commit --no-gpg-sign.

Make it yours

1. Fork this repo.
2. Edit brew/Brewfile.*, dot_config/*, and ai/*.
3. Run REPO_SLUG=you/macstrap bash scripts/bootstrap.sh.

Name, email, and signing keys live in machine-local chezmoi config — never committed.

Maintenance

macstrap report        # what macstrap manages
macstrap security      # secrets, signing, hook posture
macstrap doctor --json # machine-readable health
macstrap uninstall     # dry-run back-out (--apply to perform)

uninstall.sh backs up before removing; it never touches Homebrew packages, 1Password, runtimes, or your data.

Documentation

If you…	Start here
Just installed	SETUP.md
Work laptop	work-separation.md
Fork / customize	docs/README.md
Automate / agent	AGENT-USAGE.md
Something broke	TROUBLESHOOTING.md

Contributing

Bug reports, catalog additions, and PRs are welcome — see CONTRIBUTING.md for local setup, the checks CI runs, and conventions. Security issues go through SECURITY.md, never public issues.

License

MIT