MacBook to Mission Control Part 1: Bootstrap a Fresh MacBook for Development

Seven parts. Seven layers of setup, tooling, configuration, and workflow that take a factory-fresh MacBook and turn it into a machine a professional developer actually wants to sit down at. If you're starting a new role, rebuilding after a hardware swap, or just tired of your current setup feeling like a pile of accumulated accidents, this series walks the full path from first boot to a documented, repeatable development environment you can reconstruct in an afternoon.

Why This Series Exists

What the series covers

Most setup guides fall into one of two failure modes. Either they hand you a wall of commands with no explanation of why any of it matters, or they cover three tools and call it a day. Neither approach gives you something you can trust, reproduce, or hand to a teammate. This series exists to close that gap.

MacBook to Mission Control runs seven parts. Part 1 builds the stable base: macOS security, Finder configuration, Xcode Command Line Tools, and Homebrew. Part 2 covers terminal setup and shell configuration. Part 3 handles Git identity and credential management. Part 4 installs and organizes development languages and runtimes. Part 5 builds out the tmux workflow for session management. Part 6 ties the environment together with dotfiles and automation. Part 7 is a reference appendix: commands, paths, and decisions documented in one place.

"The goal isn't a perfect machine. The goal is a machine you understand well enough to rebuild."

What Part 1 focuses on

Part 1 is intentionally foundational. It's not the glamorous section. You won't install a single development language here. What you will do is make every subsequent part work correctly by establishing the security posture, the file system conventions, and the package management infrastructure that everything else depends on. Skip this part or rush through it, and you'll spend the next six parts debugging problems that trace back to something you glossed over in the first hour.

Start With the Basics: macOS Security and Identity

Update macOS first

Before you install anything, update macOS. This isn't a formality. Running an outdated OS before you start layering tools on top of it introduces compatibility problems that are genuinely hard to trace later. Homebrew formula definitions, compiler behavior, and SDK paths all have opinions about which version of macOS they're running on. Get current first, then build.

Open System Settings, navigate to General, then Software Update, and let it run. If a major version update is available, take it. If only security patches are pending, still take them. Come back when the machine is current.

Enable FileVault

FileVault is full-disk encryption built into macOS. On a developer machine, this isn't optional. Your machine holds SSH keys, API credentials, .env files with production secrets, and local database copies. Without FileVault, anyone with physical access to your Mac can pull that data off the drive in minutes, regardless of your login password.

Enable it in System Settings under Privacy and Security. The encryption process runs in the background and takes an hour or two on a full drive. Store the recovery key somewhere you'll actually find it, which means your password manager, not a sticky note.

Set up Touch ID and confirm admin access

Touch ID for sudo is one of those small things that removes just enough friction to matter. To enable it, open /etc/pam.d/sudo in a text editor with admin privileges and add auth sufficient pam_tid.so as the first line. After that, sudo commands prompt for a fingerprint instead of a password.

While you're here, confirm your account has administrator privileges. Open System Settings, go to Users and Groups, and verify your account shows as Admin. Several tools in this series require admin rights during installation.

Install a password manager

Install a password manager before you create any other accounts or credentials on this machine. A password manager is a developer tool. It stores API keys, SSH passphrases, database passwords, service logins, and the dozens of tokens that accumulate over the course of a real project. Without one, those credentials end up in a text file, a notes app, or your memory, and none of those are acceptable.

1Password and Bitwarden are both solid choices. 1Password has better native macOS integration; Bitwarden is open source and free for personal use. Pick one and commit to it before you move forward.

Finder and macOS Quality-of-Life Settings

Show file extensions and hidden files

Finder hides file extensions by default. That's fine for casual users. For developers, it's a liability. When you're working with .env, .json, .yaml, and .sh files, you need to see what you're actually looking at. Open Finder, go to Settings (Command + Comma), click Advanced, and check "Show all filename extensions." Do this before you open a single project.

Hidden files are a separate toggle. Press Command + Shift + Period inside any Finder window to show or hide files and folders that start with a dot. You'll use this constantly when working with dotfiles, .git directories, and configuration files that macOS hides by default. It's not a setting you change permanently; it's a shortcut you'll reach for whenever you need to see what's actually in a directory.

Set default Finder view and sidebar shortcuts

List view is the right default for development work. It shows filenames, modification dates, and sizes in a format that scans quickly across deep project directories. Open a Finder window, press Command + 2 to switch to List view, then go to View and select "Show View Options." Check "Always open in list view" and click "Use as Defaults."

Add your home folder to the Finder sidebar. Open Finder Settings, go to the Sidebar tab, and enable your home directory under Favorites. While you're there, drag your Projects folder into the sidebar once you've created it. Fast sidebar access to the two directories you'll use most is worth the thirty seconds it takes to set up.

Create your project workspace folder

Run this command in Terminal:

mkdir -p ~/Projects

That's it. One command, one folder, and every part of this series assumes it exists. All project repositories, cloned codebases, and local development work live under ~/Projects. The path is consistent across machines, easy to back up as a single directory, and clean enough that you'll never have to remember where you put something.

A dedicated project root also makes tools like fzf, zoxide, and shell aliases dramatically more useful. When everything lives under one predictable path, navigation becomes fast and scriptable.

Install Xcode Command Line Tools

Why Xcode Command Line Tools matter

Xcode Command Line Tools are not the same thing as Xcode. The full Xcode IDE is a multi-gigabyte download that most developers don't need unless they're building iOS or macOS applications. The Command Line Tools are a separate, much smaller package that provides the compilers, build tools, and SDKs that nearly every development tool on macOS depends on.

The package includes clang, make, git, python3, and the system headers that tools compile against. Homebrew checks for these tools before it installs most packages. Many language runtimes and native extensions won't build without them. Installing them now means you won't hit a wall later when something tries to compile and can't find a compiler.

Install and verify

Run this command in Terminal:

xcode-select --install

A GUI prompt will appear asking you to install the Command Line Developer Tools. Click Install, not "Get Xcode." The download is around 1.8 GB and takes a few minutes depending on your connection. When it completes, verify the installation:

xcode-select -p

A successful output looks like this:

/Library/Developer/CommandLineTools

If you see that path, the tools are installed and the system knows where to find them. If the command returns an error or an empty string, the installation didn't complete and you'll need to run the install command again.

Install Homebrew: The Foundation of Your Mac Setup

Why Homebrew is the right choice

Homebrew is the package manager macOS should have shipped with. It installs command-line tools, desktop applications, language runtimes, and development utilities from a single interface, with dependency resolution, version tracking, and update management handled automatically. The alternative is downloading installers manually, which means no consistent update path, no easy way to audit what's installed, and no mechanism for reproducing your setup on another machine.

The reproducibility argument matters more than it sounds. Later in this series, you'll create a Brewfile that lists every package you've installed. Rebuilding your environment on a new machine becomes a single command. Manual installs don't give you that.

Install Homebrew

Paste this command into Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The installer will ask for your password, confirm what it's about to install, and walk through the process. On Apple Silicon Macs, it installs to /opt/homebrew. On Intel Macs, it uses /usr/local. Pay attention to which one applies to your machine because the next step depends on it.

Add Homebrew to PATH

This is the step most guides either skip or bury, and it's the reason Homebrew appears to work during install and then fails the moment you open a new terminal window. On Apple Silicon, the shell doesn't know where Homebrew lives until you tell it.

Add these lines to your ~/.zprofile:

eval "$(/opt/homebrew/bin/brew shellenv)"

Then reload your shell:

source ~/.zprofile

After that, brew should resolve from any terminal session. If you're on an Intel Mac, Homebrew is already in /usr/local/bin, which is on the default PATH, so this step doesn't apply. Skipping the PATH configuration on Apple Silicon is the single most common reason people report that Homebrew "doesn't work" after a clean install.

Verify with brew doctor

Run this immediately after setup:

brew update && brew doctor

brew update pulls the latest formula definitions. brew doctor checks your Homebrew configuration for common problems and reports anything that needs attention. A clean install on a properly configured machine returns "Your system is ready to brew." If it returns warnings, read them. Most are actionable and come with instructions.

Don't skip brew doctor and assume everything is fine. A warning left unaddressed here can surface as a confusing error three parts from now when you're trying to install a language runtime and the problem traces back to a PATH conflict you ignored on day one.

Part 2 takes everything built here and puts a proper terminal on top of it. That means installing iTerm2, configuring Zsh with a real plugin manager, setting up a prompt that gives you useful context without slowing down your shell, and building the shell configuration files that will carry through the rest of the series. The foundation is in place. Now it's time to make the terminal worth opening.

Seven parts. Seven layers of configuration, tooling, workflow design, and automation. By the end of this series, a factory-fresh MacBook will be running a complete, professional development environment with a configured shell, version control, editor setup, cloud CLI tools, and a repeatable provisioning workflow you can rebuild from scratch in under an hour. That's the destination. Part 1 is the foundation that makes every subsequent part possible.

Install Essential Command-Line Tools

The Base Toolkit

Homebrew is installed. The PATH is configured. Now you put it to work. This single command installs everything the base system needs before the series goes deeper:

brew install git gh curl wget tree jq

Six tools. One command. That's intentional. The philosophy here is to install only what the base system actually needs right now and layer everything else in the part where it becomes relevant. Part 3 covers shell upgrades and that's where tools like ripgrep, fzf, eza, and bat belong. Installing them now, before the shell is configured to use them, creates noise without payoff.

What Each Tool Does

git is version control. Every project in this series lives in a git repository. It's the foundation of the entire workflow, not optional, not something you configure later.

gh is the GitHub CLI. Part 4 covers authentication and repository management in detail. Installing it now means it's available when that configuration happens.

curl and wget are HTTP clients. You'll use them to download files, test API endpoints, and build scripts that fetch remote resources. They're not interchangeable in every situation, so having both matters.

tree visualizes directory structure. It shows up throughout the series whenever a project layout needs to be clear at a glance.

jq parses and inspects JSON. Working with APIs, reading config files, and debugging tool output all get significantly easier once you have a proper JSON processor on the command line.

The rest comes later, when the context is right.

Verify the Base Setup

Run the Verification Commands

Installing tools is not the same as confirming they work. Run all three of these before moving on:

1git --version
2gh --version
3brew --version

Then confirm which binary is actually running:

which brew
which git

These five commands take about ten seconds. They save hours of debugging later.

What Good Output Looks Like

Healthy output from git --version looks like git version 2.x.x. The exact version number matters less than seeing a version number at all. gh --version returns something like gh version 2.x.x (YYYY-MM-DD) with a build date. brew --version returns Homebrew 4.x.x.

which brew should return /opt/homebrew/bin/brew on Apple Silicon or /usr/local/bin/brew on Intel. If it returns nothing, the PATH configuration from the earlier setup step didn't take effect. Open a new terminal window and run it again. If it still returns nothing, the shell profile edit needs to be revisited.

which git should return the Homebrew path, not /usr/bin/git. The system stub at /usr/bin/git exists to prompt Xcode Command Line Tools installation. Once git is properly installed via Homebrew, the Homebrew version should take precedence.

Verification isn't a formality. If something is broken at this stage, every part that follows inherits that breakage.

Common Mistakes on a Fresh Machine

Skipping the Homebrew PATH Instructions

This is the most common mistake and the most disruptive. After Homebrew installs, it prints explicit instructions for adding itself to the PATH. A lot of people scroll past them or assume it's handled automatically. It isn't. The result is a terminal where brew works in the session where it was installed and then disappears the next time a new window opens. Every tool installed after that point appears broken, even when it isn't.

Installing Tools Before the Base Is Stable

Running brew install on a long list of tools before verifying that Homebrew itself is working correctly creates a messy situation. If something goes wrong mid-install, it's hard to know whether the problem is with Homebrew, with a specific package, or with a dependency conflict introduced by installing things out of order. Install the base toolkit. Verify it. Then move forward.

Ignoring brew doctor Warnings

brew doctor is not cosmetic feedback. Warnings about stale symlinks, conflicting paths, or outdated Xcode tools indicate real conditions that compound as more packages get installed. A warning that seems harmless on a fresh machine can become a genuine blocker three parts into the series when a tool depends on a clean environment.

Not Creating a Dedicated Project Folder

Skipping ~/Projects sounds minor. It isn't. Without a consistent root folder for all project work, files end up on the Desktop, in Downloads, or scattered across home directory subfolders. Relative paths break. Terminal navigation gets inconsistent. When Part 5 introduces scripting that references project directories, a consistent folder structure is assumed.

Part 1 Completion Checklist

Before starting Part 2, confirm every item on this list. If anything is unchecked, go back and complete it. Part 2 builds directly on this foundation.

Every item on that list represents a decision that affects something downstream. The macOS update matters because security patches occasionally change system behavior. FileVault matters because an unencrypted development machine is a liability. The Homebrew PATH matters because nothing else works without it. None of this is busywork.

Part 2 takes this clean base and builds a shell environment on top of it. That means configuring Zsh, installing Oh My Zsh, setting up a prompt that shows useful context, and establishing the aliases and functions that make daily terminal work faster. The base is ready. The shell is next.