Schedule Auto-Updates

Create a macOS launchd agent to run Homebrew updates on a recurring schedule.

📄 setup-auto-update.sh 🛡 Scheduling 💻 macOS 11+ (15+ recommended)
Download Script View on GitHub

What This Script Does

The setup-auto-update.sh script automates the process of creating a macOS LaunchAgent that runs the basic auto-update script on a schedule you define. Instead of remembering to run Homebrew updates manually, this script sets up the system so updates happen automatically in the background at a time that works for you. It is the recommended way to ensure your Homebrew packages stay current without any ongoing effort on your part.

macOS uses a system called launchd for managing background tasks, scheduled jobs, and system services. Launchd is similar to cron on Linux, but it is more tightly integrated with macOS and supports features like running missed jobs when the system wakes from sleep. The setup script generates a properly formatted launchd plist (property list) file and installs it as a user-level LaunchAgent, which means it runs under your user account and does not require root privileges.

When you run this script, it first asks for the phone number that should receive iMessage summaries, sends a test message to it, and writes the number into PHONE_NUMBER at the top of auto-update-brew.sh. It then offers three schedules: daily at 2:00 AM, weekly on Sunday at 2:00 AM, or manual only (no agent is created). The time is fixed; to change it, edit the generated plist.

The script generates a plist XML file that contains your schedule preferences, the path to the auto-update script, and metadata that launchd uses to manage the job. It writes this file to the standard LaunchAgents directory at ~/Library/LaunchAgents/, named com.homebrew.autoupdate.plist. After writing the file, the script registers it with launchctl bootstrap gui/$(id -u), which activates the schedule immediately.

One of the advantages of launchd over simple cron jobs is its handling of missed executions. If your Mac is asleep when a scheduled update is due, launchd runs the job when it wakes. If the Mac is shut down at that time, the run is skipped until the next scheduled slot.

If you have previously set up a scheduled update and want to change the schedule, simply run this script again. It removes the existing agent from launchd with launchctl bootout, writes a new plist with your updated choice, and bootstraps it again. This makes it easy to adjust your update frequency as your needs change over time, without needing to manually edit XML files or run launchctl commands yourself.

Before finishing, the script runs auto-update-brew.sh once as a test. That run is real: if your Mac is on the configured Wi-Fi network and on AC power, it upgrades your packages. Use ./setup-auto-update.sh --dry-run to preview everything without changing anything. The commands below verify, trigger and stop the agent.

Usage

Run this script once to set up the scheduled task. You do not need to run it again unless you want to change the schedule.

# Set up the scheduled auto-update agent
./setup-auto-update.sh

After the agent is installed, you can verify it is running and manage it with these commands:

# Verify the agent is loaded
launchctl list | grep com.homebrew.autoupdate

# Manually trigger an update right now (for testing)
launchctl kickstart gui/$(id -u)/com.homebrew.autoupdate

# Stop scheduled updates
launchctl bootout gui/$(id -u)/com.homebrew.autoupdate

# Resume scheduled updates
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.homebrew.autoupdate.plist

What Gets Changed

  • LaunchAgent plist — A new file is created at ~/Library/LaunchAgents/com.homebrew.autoupdate.plist (unless you choose manual only). This XML file contains the schedule and the path to the auto-update script that launchd will execute. Its output goes to ~/Library/Logs/AutoUpdateBrew.log.
  • launchd registration — The plist is registered with launchctl bootstrap gui/$(id -u), which activates the schedule immediately. The agent persists across restarts and logins.
  • auto-update-brew.sh — Made executable, and the phone number you enter is written into its PHONE_NUMBER line.
  • Setup log — Written to ~/Library/Logs/AutoUpdateSetup.log.

The script does not touch system files. Apart from the one test run described above, the update work is done by auto-update-brew.sh when launchd triggers it. WIFI_NETWORK is not set by this script: edit it at the top of auto-update-brew.sh; left as the placeholder, every run skips.

Related Scripts

  • Schedule Hybrid Updates — The equivalent scheduling script for the hybrid (email + text) auto-update script. Choose this if you want both email reports and text message alerts.
  • Auto-Update (Basic) — The auto-update script that this scheduling agent triggers. Read its documentation to understand exactly what happens during each scheduled update run.