Automated, idempotent, and non-destructive macOS bootstrapping and baseline provisioning.
This repository provides a single-command setup for brand-new Macs as well as existing, secondary, or work machines. It is designed to be purely additive and repository-independent:
- Minimal & Independent: Runs a complete baseline environment with zero dotfiles repository required.
- Any Dotfiles Repository: Bring your own Chezmoi repo (public or private, personal or work) or use none at all.
- Non-Destructive: Never overwrites your existing
~/.zshrcor personalized configs; only appends guarded power tools if missing. - Additive Software Installation: Uses
Brewfilewithadopt: trueso it only installs missing tools and never deletes or replaces existing applications.
If you are using an AI coding assistant (such as Antigravity, Claude Code, or Cursor), point the agent to AGENT.md:
"Bootstrap this Mac following AGENT.md"
The agent executes the Ponytail-refined 4-phase protocol:
- 1-Question Upfront Flow: Asks once whether you want a dotfiles repository applied or a Minimal (core tools only) setup.
- Headless Execution: Runs
./bootstrap.sh [--minimal|--dotfiles <url>] --no-dumpdeterministically with zero terminal hangs. - Automated Verification: Runs health checks across runtimes (
node,go,python3.12), power tools (rex,fzf,zoxide,eza,bat,lazygit), and Homebrew bundle integrity. - Smart Follow-ups: Checks if unmanaged packages exist before prompting about
~/.Brewfileand configures Git author identity if missing.
Run directly in Terminal:
/usr/bin/env bash -c "$(curl -fsSL https://raw.githubusercontent.com/dragosmiron/bootstrap-mac/main/bootstrap.sh)"During execution, it installs the baseline environment and prompts whether you want to apply a Chezmoi dotfiles repository ([y/N]) and allows specifying any repo URL.
You can control exactly how much or how little is applied:
| Command | Behavior |
|---|---|
./bootstrap.sh --minimal |
Minimal Setup Only: Installs core tools, shell ergonomics, and defaults; requires no dotfiles repo and no GitHub login. |
./bootstrap.sh --dotfiles <url> |
Custom Dotfiles Sync: Applies baseline stack and pulls Chezmoi dotfiles from a Git clone URL — git@github.com:you/dotfiles.git or https://github.com/you/dotfiles.git (public or private). |
./bootstrap.sh --cli-only |
Headless / Server Mode: Installs only CLI runtimes and tools; skips all GUI casks and Rex Terminal. |
./bootstrap.sh --dump |
Refresh Brewfile: Dumps/updates ~/.Brewfile with all currently installed packages on the machine. |
./bootstrap.sh --no-dump |
Skip Brewfile Dump: Skips the Brewfile dump prompt without asking. |
# Minimal setup only (no dotfiles repo, zero auth required):
/usr/bin/env bash -c "$(curl -fsSL https://raw.githubusercontent.com/dragosmiron/bootstrap-mac/main/bootstrap.sh)" -- --minimal
# Setup with any custom public or work dotfiles repo (paste the clone URL):
/usr/bin/env bash -c "$(curl -fsSL https://raw.githubusercontent.com/dragosmiron/bootstrap-mac/main/bootstrap.sh)" -- --dotfiles https://github.com/mycompany/mac-dotfiles.git
# Full personal setup:
/usr/bin/env bash -c "$(curl -fsSL https://raw.githubusercontent.com/dragosmiron/bootstrap-mac/main/bootstrap.sh)" -- --dotfiles git@github.com:dragosmiron/dotfiles-private.git- Xcode Command Line Tools: Checks and prompts for installation if missing.
- Homebrew: Installs Homebrew non-interactively if missing and configures
$PATH. - Baseline Software (
Brewfile): Installs CLI developer tools and GUI casks (uses localBrewfileif cloned, or fetches the baseline manifest via raw GitHub). - Shell Ergonomics (
~/.zshrc): Appends a clearly marked# >>> bootstrap-mac >>>block with Zoxide, FZF, and modern aliases. If the block already exists, it is untouched. - Rex Terminal: Installs Rex Beta and creates the CLI symlink at
~/.local/bin/rex(skipped if--cli-only). - macOS System Defaults: Sets screenshot routing, fast key repeats, Finder pathbar, and
.DS_Storesuppression. - Optional Chezmoi Dotfiles: If specified, verifies if the repo is public (clones immediately) or private (prompts 1-click GitHub CLI login), then applies dotfiles via Chezmoi.
- Runtimes:
node,go,python@3.12 - Productivity & Search:
fzf,zoxide,bat,eza,lazygit,gh,chezmoi,bitwarden-cli - Shell: Zsh with
zsh-autosuggestionsandzsh-syntax-highlighting
- Essentials & Windows: Raycast, AltTab, KeepingYouAwake
- Security & Privacy: Bitwarden, Little Snitch, NordVPN, NetBird, AdGuard
- Productivity & Notes: Obsidian, Google Chrome, Zed
- Virtualization: OrbStack
- Utilities & Media: Keka, Pearcleaner, VLC, Calibre, Stremio
- Rex Terminal Beta: Installed from direct preview DMG and symlinked to
~/.local/bin/rex.
To verify the installation on an active machine:
# Check CLI runtimes & tools
which fzf zoxide bat eza lazygit node go python3.12 rex
# Verify Homebrew bundle state
brew bundle check --no-upgrade --file="./Brewfile"
# Run automated bootstrap test suite
./test/test_bootstrap.sh
# Test shell syntax
zsh -n ~/.zshrc