Shell scripts for automated macOS machine setup.
This project is a framework for automating the setup of a macOS machine. In order to illustrate the potential of what this project can do, please see the companion macOS Config project for details. The macOS Config project is an opinionated configuration which meets the needs of my development environment but is also meant to serve as an example and guide for building your own personalized setup. Here is how the two projects are meant to be used:
macOS (this project) - The foundational framework for building custom macOS machine setups.
macOS Configuration - The layer on top of this macOS project which defines a custom machine implementation. The project is meant to be forked for as many custom machine setups as needed.
Provides a command line interface, written in Bash, with no additional dependencies for installation and management of a macOS machine.
Supports macOS boot disk creation for fresh install of operating system.
Installs Xcode Command Line Tools.
Installs Homebrew formulas and casks.
Installs App Store software.
Installs non-App Store software applications.
Installs software application extensions.
Applies basic default software settings.
Configures installed software.
Supports restoration of machine backups.
To install, run:
git clone https://github.com/bkuhlmann/mac_os.git cd mac_os git checkout 13.0.0
Run the following:
You will be presented with the following options (listed in order of use):
Boot: B: Create boot disk. Install: b: Apply basic settings. t: Install development tools. hf: Install Homebrew Formulas. hc: Install Homebrew Casks. m: Install Mac App Store software. a: Install application software. x: Install application software extensions. df: Install dotfiles. np: Install Node packages. rg: Install Ruby gems. rc: Install Rust crates. d: Apply default settings. cs: Configure installed software. i: Install everything (i.e. executes all install options in order listed). Restore: R: Restore settings from backup. Manage: c: Check status of managed software. C: Caffeinate machine. ua: Uninstall application software. ux: Uninstall application software extension. ra: Reinstall application software. rx: Reinstall application software extension. w: Clean work (temp) directory. q: Quit/Exit.
i to run a full install or select a specific option to run a single action. Each
option is designed to be re-run if necessary. This can also be handy for performing upgrades,
re-running a missing/failed install, etc.
The option prompt can be skipped by passing the desired option directly to the
bin/run script. For
bin/run i will execute the full install process.
The machine should be rebooted after all install tasks have completed to ensure all settings have been loaded.
It is recommended that the
mac_os project directory not be deleted and kept on the local machine
in order to manage installed software and benefit from future upgrades.
When attempting to create a boot disk via
bin/run B, you’ll be presented with the following
documentation (provided here for reference):
macOS Boot Disk Tips - Use a USB drive (8GB or higher). - Use Disk Utility to format the USB drive as "Mac OS Extended (Journaled)". - Use Disk Utility to label the USB drive as "Untitled". macOS Boot Disk Usage: 1. Insert the USB boot disk into the machine to be upgraded. 2. Reboot the machine. 3. Hold the POWER (Silicon) or OPTION (Intel) key before the Apple logo appears. 4. Select the USB boot disk from the menu. 5. Use Disk Utility to delete and/or erase the hard drive including associated partitions. 6. Use Disk Utility to create a single "APFS" drive as a "GUID Partition Table". 7. Install the new operating system. macOS Boot Disk Recovery: 1. Start/restart the machine. 2. Hold the POWER (Silicon) or COMMAND+R (Intel) keys before the Apple logo appears. 3. Wait for the macOS installer to load from the recovery partition. 4. Use the dialog options to launch Disk Utility, reinstall the system, etc.
All executable scripts can be found in the
bin/apply_basic_settings(optional, customizable): Applies basic and initial settings for setting up a machine.
bin/apply_default_settings(optional, customizable): Applies bare minimum system and application defaults.
bin/configure_software(optional, customizable): Configures installed software as part of the post install process.
bin/create_boot_disk(optional): Creates a macOS boot disk.
bin/install_app_store(optional, customizable): Installs macOS, GUI-based, App Store applications.
bin/install_applications(optional, customizable): Installs macOS, GUI-based, non-App Store applications.
bin/install_dev_tools(required): Installs macOS development tools required by Homebrew.
bin/install_dotfiles(optional, customizable): Installs personal dotfiles so the system is tailored to your workflow.
bin/install_extensions(optional, customizable): Installs macOS application extensions and add-ons.
bin/install_homebrew_casks(optional, customizable): Installs Homebrew Formulas.
bin/install_homebrew_formulas(optional, customizable): Installs Homebrew Casks.
bin/install_node_packages(optional, customizable): Installs Node packages.
bin/install_ruby_gems(optional, customizable): Installs Ruby gems.
bin/install_rust_crates(optional, customizable): Installs Rust crates.
bin/restore_backup(optional, customizable): Restores system/application settings from backup image.
bin/run(required): The main script and interface for macOS setup.
lib folder provides the base framework for installing, re-installing, and uninstalling
software. Everything provided via the macOS
Config project is built upon the functions found in the
lib folder. See the
macOS Config project for further details.
lib/settings.sh: Defines global settings for software applications, extensions, etc.
When using Pi-hole, you might need to temporarily disable prior to upgrading as you might experience various errors with Apple not being able to detect an internet connection which prevents the installer from working.
When using the boot disk and the installer fails in some catestrophic manner, reboot the machine into recovery mode —
COMMAND + R(Intel) buttons — to download and install the last operating system used. Alternatively, you can also use
COMMAND + OPTION + R(Intel) to attemp to download the latest operating system.
When using the boot disk, you might experience a situation where you see a black screen with a white circle and diagonal line running through it. This means macOS lost or can’t find the boot disk for some reason. To correct this, shut down and boot up the system again while holding down the
OPTION + COMMAND + R + P(Intel) keys simultaneously. You might want to wait for the system boot sound to happen a few times before releasing the keys. This will clear the system NVRAM/PRAM. At this point you can shut down and restart the system following the boot disk instructions (the boot disk will be recognized now).
To contribute, run:
git clone https://github.com/bkuhlmann/mac_os.git cd mac_os
Read Semantic Versioning for details. Briefly, it means:
Major (X.y.z) - Incremented for any backwards incompatible public API changes.
Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
Code of Conduct
Read Code of Conduct for details.
Read Contributions for details.
Read License for details.
Read Changes for details.
Engineered by Brooke Kuhlmann.