Getting Started

Requirements

Before you begin, make sure your system meets the following requirements. These scripts are designed to work on modern macOS systems and require a few basic prerequisites to function properly. If you are unsure about any of these, read through the notes below each item for guidance.

• macOS 12.0 (Monterey) or later — Both Intel and Apple Silicon Macs are fully supported. The scripts automatically detect your processor architecture and adjust Homebrew paths accordingly. You can check your macOS version by clicking the Apple menu and selecting "About This Mac."
• Administrator privileges — You will be prompted for your password during installation. Homebrew requires administrator access to install packages into system directories. If you are not an administrator on your Mac, you will need to ask someone who is to enter their credentials when prompted.
• Internet connection — A stable connection is needed to download Homebrew itself as well as any packages and applications you choose to install. Wired or strong Wi-Fi connections are recommended, especially for the initial setup which may download several hundred megabytes of data.
• At least 1GB free disk space — Homebrew, its cache, and the applications you install will need room on your drive. The actual space required depends on how many applications you choose to install. You can check your available storage in System Settings under General > Storage.

If your system does not meet one or more of these requirements, the scripts will detect the issue during the pre-flight check and let you know what needs to be resolved before continuing.

Step 1 — Download

There are two ways to get the scripts onto your Mac. Choose the option that best fits your workflow. If you are comfortable with Git and want to receive updates easily, cloning is the way to go. If you just want to grab the files quickly and do not plan to track upstream changes, downloading the ZIP is perfectly fine.

Option A: Clone with Git

Cloning creates a local copy of the repository that is linked to the original on GitHub. This makes it easy to pull down updates later with a single git pull command, and also lets you contribute back if you find improvements to share.

# Clone the repository to your current directory
git clone https://github.com/DJCastle/homeBrewScripts.git

# Move into the project folder
cd homeBrewScripts

If you do not have Git installed yet, do not worry. macOS will prompt you to install the Xcode Command Line Tools when you first run git, which includes Git along with other useful developer utilities.

Option B: Download ZIP

If you prefer not to use Git, you can download the entire project as a ZIP file. This is a quick option if you want to get started right away without setting up Git first.

# Download the latest version as a ZIP file
curl -L -o brewscripts.zip https://github.com/DJCastle/homeBrewScripts/archive/refs/heads/main.zip

# Unzip and move into the project folder
unzip brewscripts.zip && cd homeBrewScripts-main

Alternatively, you can visit the GitHub repository in your browser, click the green "Code" button, and select "Download ZIP." Once downloaded, double-click the file in Finder to unzip it, then open Terminal and navigate to the extracted folder.

Step 2 — Set Up Your Config

Before running any scripts, you should create and customize your configuration file. The config file controls which applications get installed, how notifications are delivered, and various other behaviors. An example configuration ships with the project so you can see all available options and their default values.

Start by copying the example configuration to create your own personal config file:

# Create your config from the example template
cp config/homebrew-scripts.example.conf config/homebrew-scripts.conf

Next, open the file in any text editor to review and customize the settings. You can use nano directly in the terminal, or open it in a graphical editor like TextEdit or Visual Studio Code:

# Open in nano (terminal-based editor)
nano config/homebrew-scripts.conf

# Or open in your default text editor
open config/homebrew-scripts.conf

Here are the key settings you will want to review and customize:

Setting	What It Does
WIFI_NETWORK	Only run auto-updates when connected to this specific Wi-Fi network. Leave empty to allow updates on any network. This is useful to prevent large downloads on metered or slow connections.
EMAIL_ADDRESS	Where to send update reports. After each automatic update, you will receive a summary of what was updated, what failed, and any action items.
PHONE_NUMBER	Your iMessage number for quick text alerts. Great for getting a quick heads-up that an update ran without needing to check email.
INSTALL_*	Toggle entire categories of applications on or off. Categories include development tools, productivity apps, creative software, communication apps, and utilities.
CUSTOM_APPS	Add or remove specific applications from the install list. This lets you fine-tune exactly which apps are installed beyond the category toggles.

The example config file includes detailed comments explaining every setting, so take a moment to read through it. You do not need to configure everything right away — the defaults are sensible and safe starting points.

Step 3 — Make Scripts Executable

By default, downloaded files on macOS are not marked as executable. Before you can run the shell scripts, you need to give them execute permission. This is a standard security measure that prevents scripts from running unintentionally.

# Make all shell scripts in the project executable
chmod +x *.sh

You only need to do this once. The chmod +x command adds the "execute" permission to each .sh file, telling macOS that these files are programs that can be run directly from the terminal. If you later download updated versions of the scripts, you may need to run this command again on the new files.

If you want to verify that the permissions were set correctly, you can list the files with their permissions:

# List files with permissions — look for 'x' in the output
ls -la *.sh

You should see -rwxr-xr-x (or similar) at the beginning of each line, where the x characters indicate that execute permission has been granted.

Step 4 — Run Your First Script

Now that everything is set up, it is time to run your first script. There are two main entry points depending on how much control you want over the process. Both support a --dry-run flag, which is strongly recommended for your first run so you can see exactly what will happen without making any actual changes to your system.

Option A: Quick Setup (fast, opinionated)

The quick setup script is designed for experienced users who want a rapid bootstrap with sensible defaults. It installs CLI tools via a Brewfile, configures Visual Studio Code extensions, and sets up Git — all in one pass. No config file is needed for this option.

# Preview what would happen (safe — no changes are made)
./quick-setup.sh --dry-run

# Run for real when you are satisfied with the preview
./quick-setup.sh

Option B: Full Interactive Setup (config-driven, educational)

The full interactive setup is the flagship script. It walks you through each step with clear explanations and interactive checkpoints. You can skip any step you are not comfortable with, and the script will respect your choices. This is the recommended option for first-time users or anyone who wants to learn while they set up.

# Preview what would happen (safe — no changes are made)
./brew_setup_tahoe.sh --dry-run

# Run for real when you are ready
./brew_setup_tahoe.sh

During the interactive setup, the script will ask for confirmation before each major operation. Simply answer y to continue or n to skip. If you are ever unsure, skipping is always the safe choice — you can come back and run the script again later for any steps you skipped.

What Each Script Does

The Brew Scripts project includes several specialized scripts, each designed for a specific purpose. Here is an overview of every script in the collection and what it does. You do not need to run all of them — pick the ones that match your needs.

Script	Purpose
quick-setup.sh	Quick bootstrap — installs CLI tools via Brewfile, sets up VSCode extensions, and configures Git. Ideal for developers who want to get a new machine ready fast.
brew_setup_tahoe.sh	Full interactive setup — installs Homebrew, configures your shell, and installs applications with guided, step-by-step checkpoints. The most comprehensive and educational script.
install-essential-apps.sh	Batch-installs applications from your config file. Useful if Homebrew is already installed and you just want to add your app collection.
auto-update-brew.sh	Runs Homebrew updates with text message notifications via iMessage. Designed to be run as a scheduled task.
auto-update-brew-hybrid.sh	Runs Homebrew updates with both email and text notifications. Provides more detailed reporting than the text-only version.
setup-auto-update.sh	Schedules automatic Homebrew updates using macOS launchd. Creates a background job that runs updates on your preferred schedule.
setup-hybrid-notifications.sh	Schedules automatic updates with both email and text notifications. The most fully-featured automated update option.
cleanup-homebrew.sh	Removes old package versions, clears the download cache, and frees disk space. Safe to run periodically to keep your system tidy.

Optional — Set Up Auto-Updates

Once you have Homebrew and your applications installed, you can set up automatic updates to keep everything current without manual intervention. The auto-update system uses macOS launchd to schedule periodic update checks. It is smart enough to verify network connectivity and power status before running, so it will not interrupt you or use battery power unexpectedly.

# Set up automatic updates with email and text notifications
./setup-hybrid-notifications.sh

This creates a scheduled task that runs updates in the background at the interval you specify in your config file. Each time an update runs, you will receive a notification summarizing what was updated and whether any issues were encountered. If the conditions are not right — for example, if your Mac is on battery power or not connected to your preferred Wi-Fi network — the update will be skipped and reattempted at the next scheduled interval.

You can verify that the scheduled task was created successfully by listing your launchd jobs:

# List your scheduled Homebrew update jobs
launchctl list | grep homebrew

Logs

All scripts produce detailed logs that record every action taken, along with timestamps and status indicators. Logs are your best friend when troubleshooting — they contain a complete record of what happened, what succeeded, and what failed. Every log entry includes a severity level (INFO, WARNING, ERROR, SUCCESS) so you can quickly scan for issues.

Log files are stored in the standard macOS logs directory:

# List all Brew Scripts log files
ls ~/Library/Logs/Homebrew*.log

# View the most recent log entries
tail -50 ~/Library/Logs/HomebrewSetup.log

# Search logs for errors
grep ERROR ~/Library/Logs/HomebrewSetup.log

If something goes wrong during a script run, the log file should be the first place you check. It will show you exactly which step failed and usually includes an error message from the underlying tool that explains why. You can also enable debug mode by passing the --debug flag to any script, which produces even more detailed output that can help diagnose tricky issues.

Tips for Success

Need More Info?

Now that you are set up, here are some resources to help you go further:

• Safety & Best Practices — Understand the safety features and learn best practices for working with system automation scripts.
• Shell Scripting Guide — Learn shell scripting concepts by studying the real-world patterns used in these scripts.
• FAQ — Answers to common questions about installation, configuration, and troubleshooting.
• Changelog — See what has changed in each version of the project.