mac_os is a shell framework for scripting a whole Mac from scratch

A framework, not a configuration

The project description is precise about the distinction, and it is the thing to understand before you clone anything. This project is a framework for automating the setup of a macOS machine. The companion project, macOS Config, is the layer on top of this mac_os project which defines a custom machine implementation, and it is an opinionated configuration that meets the needs of the author's own development environment while also serving as an example and a guide for building your own.

The two are meant to be used together in a specific way. macOS is the foundational framework for building custom macOS machine setups. macOS Configuration is the layer on top, and the project is meant to be forked for as many custom machine setups as needed. So the intended shape is: take the framework, fork the configuration, edit the configuration to match your own taste, and run the result on every machine you own or manage.

That framing is more useful than it first looks. A list of applications to install with a tool like Ansible or a shell script of your own gets you the same packages, but not the same machine. This project covers the parts of a Mac that people actually get wrong during setup: the system defaults, the shell, the dotfiles, the extensions, the configuration of the software after it is installed, and the ability to restore from a backup. The homepage is alchemists.io/projects/mac_os, the primary language is Shell, and the repository is not archived with the last push on 2026-09-17.

The licence is stated as a custom one that GitHub cannot classify, with the terms in a LICENSE.adoc file, so if you intend to redistribute it inside an organisation that expects a standard open source licence, read that file first rather than assuming a permissive grant.

The command line interface, and what each option does

The features list starts with the interface itself: a command line interface, written in Bash, with no additional dependencies for installation and management of a macOS machine. That last clause is the design goal, and it is the reason this approach is different from a configuration management tool that needs Python, Ruby or a daemon installed before it can configure anything.

Running bin/run gives a menu. The options are grouped by phase, and the grouping tells you the intended order of operations. Boot offers B for creating a boot disk. Install offers b for basic settings, t for development tools, hf for Homebrew Formulas, hc for Homebrew Casks, m for Mac App Store software, a for application software, x for application software extensions, df for dotfiles, np for Node packages, rg for Ruby gems, rc for Rust crates, d for default settings, cs for configuring installed software, and i which installs everything by executing all install options in the order listed. Restore offers R for restoring settings from backup. Manage offers c for checking the status of managed software, C for caffeinating the machine, ua and ux for uninstalling applications and extensions, ra and rx for reinstalling them, w for cleaning the work directory, and q to quit.

Two design decisions in that menu are worth calling out. The i option executes all install options in order listed, which means the full install is not a separate implementation but the same code paths run in sequence. And the documentation stresses that each option is designed to be re-run if necessary, which is described as handy for performing upgrades, re-running a missing or failed install, and similar recoveries. Idempotent-by-re-runnable step scripts are what make a machine setup script survive contact with a second machine.

The prompt can be skipped by passing the option directly to bin/run, so bin/run i runs the full install. The documentation also says the machine should be rebooted after all install tasks have completed so that all settings are loaded, and that the mac_os project directory should not be deleted and kept on the local machine, both in order to manage installed software and to benefit from future upgrades.

The script list, which is really the feature list

The customization section enumerates the executable scripts in the bin folder and marks each one required or optional, which is more useful information than a marketing list of features.

Only two are required. bin/install_dev_tools is required, and it installs the macOS development tools required by Homebrew, which is the Xcode Command Line Tools step. bin/run is required, and it is the main script and interface for macOS setup.

Everything else is optional and, more usefully, customisable. There is bin/create_boot_disk for creating a macOS boot disk. There is bin/install_basics for applying basic settings for setting up a machine. There is bin/install_defaults, which applies the system defaults, and the project links this to a companion site, macos-defaults.com, There are the package installers: bin/install_homebrew_formulas, bin/install_homebrew_casks, bin/install_node_packages, bin/install_ruby_gems, bin/install_rust_crates, and bin/install_app_store and bin/install_applications for the two kinds of Mac software. There is bin/install_extensions for application extensions to any application that supports add-ons or plugins. There is bin/install_shell, which lets you install and customise your preferred shell and is called out as especially useful if you do not want the macOS default Z shell. And there is bin/restore_backup, which restores system and application settings from a backup.

One documentation quirk is worth flagging rather than reproducing, because it is exactly the kind of thing that wastes an afternoon. In the script list, the entry for bin/install_homebrew_casks is described as installing Homebrew Formulas, and the entry for bin/install_homebrew_formulas is described as installing Homebrew Casks. The two descriptions are swapped relative to what the names say. The feature list at the top of the project gets it right, listing both formulas and casks as installed, so trust the script names rather than those two description lines.

Boot disk creation, and what it does to the machine

The boot disk flow is the most destructive thing the framework does, and the documentation handles it with the detail it deserves. The presented instructions start with inserting a USB drive of 8GB or higher, formatting it with Disk Utility as Mac OS Extended (Journaled), setting the schema to GUID Partition Map if available, labelling it Untitled, and then running the script to install the OS and create a bootable USB drive.

The usage section then covers what to do with that drive. Insert it into the machine to be upgraded, reboot, press and hold the POWER key before the Apple logo appears, select the USB boot disk from the menu, and then use Disk Utility to delete and erase the hard drive including associated partitions, create a single APFS drive, and install the new operating system. A recovery section follows, covering holding the POWER key at restart, waiting for the installer to load from the recovery partition, and using the dialog options to launch Disk Utility or reinstall the system.

The final piece is a practical detail that saves a long download later. The documentation notes you can ensure the right installer is downloaded and available for boot disk creation by running these commands:

# Show which installers are available.
softwareupdate --list-full-installers

# Download desired version.
sudo softwareupdate --fetch-full-installer --full-installer-version 27.0

The stated requirements are macOS 27.0.0, which the project links to as Golden Gate, and Xcode. There is a .ruby-version file at the repository root and a Gemfile and Rakefile alongside it, plus a .config/ directory and a .circleci/ directory for continuous integration, and a CITATION.cff file for citing the project.

Where a shell framework is the wrong answer

The first limitation is the one the project design makes obvious. Every step here runs with the privileges needed to modify a machine system wide, and a machine setup script that installs software, applies system defaults, changes the shell and writes dotfiles is a script that can leave a machine in a state you do not want. There is no dry run, no diff, no plan. The i option does everything, in order, and the individual options exist precisely so you can run one at a time, which is the mitigation.

The second limitation is the scope of the result. This automates the installation and configuration of a machine, and it is deliberately a personal setup framework rather than an engineering environment builder. It does not pin language versions per project, it does not manage dotfiles across several repositories with different layouts, and it does not set up containers or virtualisation for isolation. If your problem is a consistent development environment across a team with conflicting project requirements, you want a tool built for that, and this is the wrong shape.

The third limitation is macOS only, and specifically a recent macOS, since the stated requirement is macOS 27.0.0. A script that applies system defaults by name and expects a particular installer layout will break when Apple changes them, and the whole thing has to be re-audited on each macOS release. The readme points at macos-defaults.com for the defaults, which suggests the defaults live in a companion project so they can move without this repository changing, and that is the pattern to follow if you adopt it.

The realistic alternative for a managed fleet is a configuration management tool, which is a different approach rather than a better version of the same thing. Ansible, or a platform provisioning system, gives you idempotence as a property of the tool rather than a hope about re-runnable scripts, gives you a report of what changed, and gives you a way to run the same definition against a machine that is already in an unknown state. What the shell framework buys you instead is zero dependencies and total control over the exact sequence, on a machine you own, with a configuration you have read line by line. For a single developer rebuilding their own machine after a wipe, that trade is often the right one. For twenty machines across a team, the other trade usually wins.

Editorial conclusion

Adopt mac_os if you provision many Macs or want your own machine to be reproducible from a fresh install, and you are willing to fork it and own the configuration layer. Do not adopt it as a one-off laptop setup, since the point is automation you run repeatedly, and do not assume the companion configuration project is yours to use unchanged. Before you start, read the script list in the project description to see which install steps are required and which are optional, and note the stated requirements of macOS 27.0.0 and Xcode, plus the instruction to keep the project directory on the machine.

Frequently asked questions

Official sources

1. bkuhlmann/mac_os on GitHub
2. Issues
3. Project website
4. README