Set up a new Mac for development with one command, then manage everything
through a small CLI called mac.
New here? Read this file once, top to bottom. It explains what’s included, how to install it, and which commands you can run afterward.
MacDevSetup is an opinionated, personal macOS setup, shared so anyone can reuse or fork it. It fits you if you want a reproducible, one-command Mac setup and are comfortable in the terminal.
There are two ways in:
- Start lean with
--profile minimal— a neutral core of shell, Git, and command-line tools that suits almost everyone. - Take the full workstation with
--profile full— the maintainer's exact stack: a PHP/Symfony toolchain, quality linters, GUI apps, and a French keyboard layout. Great if your needs overlap; otherwise start minimal.
New here and unsure? Use minimal and add what you need. To make this your own
setup, see Make it yours.
install.sh sets up a small mac CLI. Its commands install your tools and keep
your machine in a known state — and everything is reversible.
Next step — set up your projects. bootstrap-web-setup is the logical continuation of MacDevSetup, one level down: once your machine is tooled here, it drops a standardized quality / CI / security config into your web projects (Symfony, optionally + JS/TS front) — driven by the very binaries MacDevSetup installs (pre-commit, gitleaks, shellcheck, PHPStan, PHP-CS-Fixer, Rector, …). Same author, same conventions: the two are maintained together and evolve in lock-step.
curl -fsSL https://raw.githubusercontent.com/labault/mac-dev-setup/main/install.sh | bash
# open a new terminal tab/window
mac setup --profile minimal # lean core; omit --profile to install the full workstationThis is the fastest path. Keep reading for profiles, managed files, rollback, and the full command reference.
- Who this is for
- How it works at a glance
- Quick start (30 seconds)
- What's included
- Installation
- Make it yours
- The
macCLI — command reference - Going further
- License
Each tool has a dedicated page covering installation, configuration, and removal.
Two quick commands work for most tools listed here:
tldr <tool> # short, example-first cheatsheet (works offline)
brew info <tool> # description, version, and homepageThese run in the terminal and improve on macOS built-ins.
| Tool | What it does | Documentation |
|---|---|---|
antidote |
Zsh plugin manager | docs/zsh/antidote.md |
autojump |
Jump to a frequent directory with j <partial-name> |
docs/cli/autojump.md |
bat |
cat with syntax highlighting and Git annotations |
docs/cli/bat.md |
duf |
Disk space overview (friendlier df) |
docs/cli/duf.md |
dust |
Show what is taking up disk space (friendlier du) |
docs/cli/dust.md |
glances |
Real-time system monitor (CPU, memory, disk, network) | tldr glances |
lsd |
ls with colors, icons, and a tree view |
docs/cli/lsd.md |
terminal-notifier |
Send macOS notifications from shell scripts | docs/macos/terminal-notifier.md |
tldr |
Short, example-first manual pages — installed as tlrc formula |
tldr tldr |
tokei |
Count lines of code by language | docs/cli/tokei.md |
tree |
Show a directory as a tree | docs/cli/tree.md |
| Tool | What it does | Documentation |
|---|---|---|
gh |
GitHub from the terminal: open PRs, create issues, clone repos | gh --help |
git-delta |
Readable, colored Git diffs | docs/git/git-delta.md |
gitleaks |
Scan your repo for accidentally committed secrets | docs/security/gitleaks.md |
| Gitmoji | Emoji + Conventional Commit convention (enforced by a commit-msg shell hook) | docs/git/gitmoji.md |
| KeeWeb | KeePass-compatible password manager (desktop app) | docs/security/keeweb.md |
These are only installed with the full profile.
| Tool | What it does | Documentation |
|---|---|---|
composer |
PHP dependency manager | docs/php/php.md |
| pcov | Fast PHP code coverage (project-level, replaces Xdebug for CI) | docs/php/coverage.md |
| Pest | Modern PHP test framework | docs/php/pest.md |
php |
PHP runtime (Homebrew-managed, Apple Silicon native) | docs/php/php.md |
| PHP-CS-Fixer / Rector | Autoformat and auto-refactor PHP code | docs/php/coding-standards.md |
| PHPStan / Psalm | Static analysis — catch bugs before running the code | docs/php/static-analysis.md |
symfony-cli |
Create, run, and manage Symfony projects | docs/php/php.md |
xdebug |
Step debugger for PHP | docs/php/xdebug.md |
Linting and quality tools run automatically before each commit via pre-commit.
| Tool | What it does | Documentation |
|---|---|---|
act |
Run GitHub Actions locally (no push needed to test a workflow) | docs/github-actions/act.md |
actionlint |
Validate GitHub Actions workflow files | docs/github-actions/actionlint.md |
ctop |
Live container resource monitor, top-style |
docs/docker/ctop.md |
editorconfig-checker |
Enforce .editorconfig rules across the repo |
docs/quality/editorconfig-checker.md |
hadolint |
Lint Dockerfiles | docs/docker/hadolint.md |
lychee |
Find broken links in documentation | docs/quality/lychee.md |
markdownlint-cli2 |
Enforce consistent Markdown formatting | docs/quality/markdownlint-cli2.md |
| OrbStack | Fast, lightweight Docker Desktop replacement | docs/docker/orbstack.md |
pre-commit |
Run quality checks automatically before every git commit |
docs/quality/pre-commit.md |
shellcheck |
Find bugs and bad patterns in shell scripts | docs/quality/shellcheck.md |
| App | What it does | Documentation |
|---|---|---|
| Sublime Text | Lightweight editor for quick edits and large files | docs/editors/sublime-text.md |
| Visual Studio Code | Primary code editor | docs/editors/vscode.md |
| Warp | Modern terminal with AI autocompletion | docs/warp/warp.md |
| App | What it does | Documentation |
|---|---|---|
| Beekeeper Studio | SQL editor with a clean interface (PostgreSQL, MySQL, SQLite) | docs/database/beekeeper-studio.md |
| App | What it does | Documentation |
|---|---|---|
| CleanShot X | Screenshot and screen recording with annotation and OCR | docs/productivity/cleanshot.md |
| GIMP | Open-source image editor for retouching and export | docs/productivity/gimp.md |
| Ice | Menu bar manager — hide, organise, and reorder menu bar icons | docs/macos/menu-bar.md#ice |
| Notion | Collaborative workspace for notes, databases, and project tracking | docs/productivity/notion.md |
| Obsidian | Local-first Markdown note-taking app | docs/productivity/obsidian.md |
| Pearcleaner | Cleanly uninstall apps and their leftover files | docs/macos/pearcleaner.md |
| Raycast | Launcher that replaces Spotlight: clipboard history, snippets, window management | docs/productivity/raycast.md |
| Stats | System monitor in the menu bar (CPU, memory, network) | docs/macos/menu-bar.md#stats |
| SwiftBar | Turn any shell script into a menu bar item with auto-refresh | docs/macos/menu-bar.md#swiftbar |
| App | What it does | Documentation |
|---|---|---|
| Bruno | Git-friendly API client — collections stored as plain files in your repo | docs/web/bruno.md |
| Excalidraw | Hand-drawn-style diagrams in the browser or VS Code | docs/web/excalidraw.md |
| Firefox | Secondary browser for cross-browser testing | docs/web/firefox.md |
| Google Chrome | Primary development browser | docs/web/chrome.md |
| RealFaviconGenerator | Generate favicons for all platforms from a single source image | docs/web/favicons.md |
| remove.bg | Remove image backgrounds automatically | docs/web/image-services.md |
| Tool | What it does | Documentation |
|---|---|---|
| Claude (desktop app + CLI) | AI assistant for reasoning, writing, design, and agentic coding | docs/ai/claude.md |
| Codex (CLI) | OpenAI's coding assistant, installed globally via npm |
docs/ai/codex.md |
| CodexBar | Menu bar app tracking token usage and cost across AI providers | docs/ai/codexbar.md |
| Ollama | Run large language models locally (Mistral, Llama, etc.) | docs/ai/ollama.md |
| Tool | What it does | Documentation |
|---|---|---|
| Sentry | Error tracking and performance monitoring for Symfony projects | docs/monitoring/sentry.md |
| SwiftBar + custom scripts | Lightweight VPS and site uptime monitoring in the menu bar | docs/macos/menu-bar.md#swiftbar |
The complete package inventory (USED / INSTALLED / TOOLING) lives in docs/homebrew/inventory.md.
Before starting, make sure you have:
- macOS (Apple Silicon or Intel)
- Git — comes pre-installed on macOS; check with
git --version - An internet connection
- Permission to install software (admin account)
You do not need to install Homebrew beforehand — the setup does it for you. On a fresh Mac, macOS will prompt to install the Command Line Tools the first time Homebrew runs; accept that prompt and let it finish.
Open Terminal (or Warp, iTerm2, etc.) and run:
curl -fsSL https://raw.githubusercontent.com/labault/mac-dev-setup/main/install.sh | bashThis command:
- Downloads this repository to
~/.mac-dev-setup. - Creates a
maccommand available from anywhere in your terminal. - Adds
~/.local/binto your shellPATH.
It does not install tools yet — that happens in Step 4.
Prefer to read the script before running it? Download and inspect it first:
curl -fsSL https://raw.githubusercontent.com/labault/mac-dev-setup/main/install.sh -o install.sh
less install.sh # review what it does
bash install.shClose and reopen your terminal (or open a new tab), then confirm mac is
available:
mac helpYou should see a list of commands. If mac is not found, open a new tab — your
shell likely hasn’t reloaded yet.
mac: command not foundafter installation Open a new terminal tab/window and runmac helpagain. If needed, reload your shell profile manually (source ~/.zprofile).- Homebrew install fails due to permissions
Complete any pending macOS/Xcode Command Line Tools prompts, then rerun
mac setup. - Network/proxy blocks package downloads
Retry on a stable network or configure your proxy settings first, then run
mac setup --dry-runto preview.
For deeper diagnostics, see docs/troubleshooting/troubleshooting.md.
A profile decides which tools are installed. New here? Start with
minimal — you can always add the rest later.
| Profile | Best for | What you get |
|---|---|---|
minimal |
Lightweight shell + Git workflow | Core CLI tools, Git helpers, gh, node, pre-commit (14 Homebrew packages) |
full |
The maintainer's complete workstation (the default) | Everything in minimal + PHP/Symfony stack, quality linters, GUI apps, containers, databases, AI tools (51 Brewfile entries: 29 formulae, 21 casks, 1 tap) |
The exact lists live in
profiles/minimal/Brewfile and
profiles/full/Brewfile. To change what either
profile installs, see Make it yours.
mac setup --profile minimal # or: mac setup --profile fullRunning mac setup without --profile installs the full profile.
This is the main step:
- Installs Homebrew if it is not already on your machine.
- Installs every package from your selected profile.
- Configures Git through a managed global include.
- Installs the Zsh configuration and shell completion for
mac.
Expect a few minutes on first run while Homebrew downloads and builds packages.
mac setup is safe to rerun. It reapplies managed config and only updates
files when needed; user files are backed up before replacement when content
differs.
Want to preview what it would do without changing anything?
mac setup --dry-run
These commands change system or app settings. They are not run automatically:
mac defaults # apply curated macOS Finder / Dock / keyboard tweaks
mac keyboard # install the Français OSS Mac keyboard layout (French typists only)
mac vscode # install the curated VS Code extensions
mac vscode --with-optional # also install the optional extension setTo configure shell and Git, MacDevSetup may create or update these user-level files:
~/.zprofile,~/.zshrc,~/.zsh_plugins.txt,~/.p10k.zsh~/.shell/alias.sh~/.zsh/completions/_mac- a global Git
include.path
Existing files are backed up before replacement when they differ from the
versioned ones. Backups go to ~/Documents/Backups/mac-dev-setup/zsh.
- Undo managed CLI/config changes:
mac uninstall --dry-runthenmac uninstall(add--remove-configonly if you want managed config files removed when they are unchanged from the versioned copies). - Restore your previous shell files: use the backup copies in
~/Documents/Backups/mac-dev-setup/zsh. - Remove the local repository clone:
mac uninstall --remove-install-dir. - Keep installed tools/apps: uninstalling MacDevSetup does not remove Homebrew packages or installed applications.
The full profile reflects one developer's choices. Forking and adapting it is
expected — here is where to change things:
- Add or remove tools: edit
profiles/minimal/Brewfileandprofiles/full/Brewfile. Each line is a Homebrewbrew/cask/tapentry;mac doctorreports anything installed but not declared. - Create your own profile: add
profiles/<name>/Brewfile, thenmac setup --profile <name>. Profiles are discovered from the directory, so no code change is needed. - Keep machine-specific or private shell config out of the repo: put it in
~/.shell/local.zsh, which the managed.zshrcsources automatically and which is never overwritten. See docs/zsh/zsh.md. - Skip the parts you don't need: the keyboard layout, macOS defaults, and VS
Code extensions are all opt-in commands (
mac keyboard,mac defaults,mac vscode) — simply don't run them. - Point the installer at your own fork: set
MAC_DEV_SETUP_REPO_URLbefore runninginstall.shto clone from your repository instead.
Every command supports --help:
mac <command> --help| Command | What it does |
|---|---|
mac help |
List all available commands |
mac setup |
Install or reapply the full development environment |
mac doctor |
Check your machine against the selected profile — reports what is missing, out of date, or drifted |
mac php |
Manage PHP development helpers (Xdebug on/off) |
mac update |
Update MacDevSetup itself to the latest version |
mac uninstall |
Remove the mac CLI and its managed configuration |
mac defaults |
Apply curated macOS Finder / Dock / keyboard defaults (opt-in) |
mac keyboard |
Install the Français OSS Mac keyboard layout (opt-in) |
mac vscode |
Install the curated VS Code extensions (opt-in) |
Installs and configures the development environment.
mac setup # install everything (full profile)
mac setup --profile minimal # install the minimal profile only
mac setup --dry-run # preview what would happen, change nothingChecks your machine against the expected state. Useful after switching machines, pulling updates, or debugging.
mac doctor # check your machine (uses your current profile)
mac doctor --profile minimal # check against the minimal profile specifically
mac doctor --fix # print the commands that would fix each issue (does not run them)
mac doctor --summary # collapse long lists to a count (handy when many tools drift)mac doctor reports three things:
- Missing — a tool declared in the profile is not installed.
- Drift — a managed config file differs from the versioned copy.
- Undeclared — a tool is installed but not declared in any profile.
Manages PHP-specific helpers without touching Homebrew directly.
mac php xdebug status # show whether Xdebug is enabled or disabled
mac php xdebug enable # enable Xdebug (for local debugging)
mac php xdebug disable # disable Xdebug (for performance / CI)Xdebug is kept disabled by default — it adds overhead to every request. Enable it only when you are actively debugging.
Pulls the latest version of MacDevSetup from GitHub and fast-forwards your local copy.
mac update # update to the latest version
mac update --dry-run # preview the update, change nothing
If you have uncommitted changes, mac update refuses to proceed to avoid
overwriting your work.
Removes MacDevSetup from your machine. Installed tools (Homebrew packages and
apps) are not removed — only the mac CLI and its managed entries.
mac uninstall # remove the CLI + managed PATH entry
mac uninstall --remove-config # also remove managed config files (only if identical to the versioned copies)
mac uninstall --remove-install-dir # also remove ~/.mac-dev-setup
mac uninstall --dry-run # preview what would be removed, change nothing
Full documentation lives in docs/ — start at the
documentation index for the complete, browsable map. Good
entry points:
- Setup walkthrough
- Homebrew & the package inventory
- Zsh configuration — plugins, Powerlevel10k theme, aliases
- Git configuration
- SSH configuration
- macOS defaults reference — what
mac defaultsapplies - Français OSS keyboard layout — what
mac keyboardinstalls - CI and GitHub Actions — the quality pipeline
- How the CLI is built
- Troubleshooting
MacDevSetup is released under the MIT License. See LICENSE for
details.