mac_os-config

Shell scripts for customized macOS machine setup.

https://github.com/bkuhlmann/mac_os-config

Keywords

Repository

Shell scripts for customized macOS machine setup.

README.adoc

:toc: macro
:toclevels: 5
:figure-caption!:

= macOS Configuration

This project provides a highly opinionated default configuration built upon the
link:https://alchemists.io/projects/mac_os[macOS] project. Should the configuration provided by
this project not be to your liking, feel free to fork and customize for your specific needs.

toc::[]

== Features

Due to the amount of tooling used, the following features are broken down into subsections for
easier navigation.

=== Homebrew Formulas

Installs the following link:https://brew.sh[formulas]:

* link:https://asciinema.org[asciinema]
* link:https://www.gnu.org/software/bash[Bash]
* link:http://bash-completion.alioth.debian.org[Bash Completion]
* link:https://github.com/sharkdp/bat[Bat]
* link:https://github.com/toy/blueutil[blueutil]
* link:https://github.com/cloudflare/cloudflared[cloudflared]
* link:https://github.com/schollz/croc[croc]
* link:https://crystal-lang.org[Crystal]
* link:http://ctags.sourceforge.net[CTags]
* link:https://difftastic.wilfred.me.uk[Difftastic]
* link:https://direnv.net[direnv]
* link:https://github.com/wagoodman/dive[Dive]
* link:https://github.com/muesli/duf[duf]
* link:https://github.com/bootandy/dust[Dust]
* link:http://duti.org[duti]
* link:https://eradman.com/entrproject[Entr]
* link:https://exiftool.org/index.html[ExifTool]
* link:https://github.com/sharkdp/fd[fd]
* link:https://github.com/tako8ki/frum[Frum]
* link:https://github.com/Schniz/fnm[Fast Node Manager]
* link:https://fx.wtf[fx]
* link:https://github.com/junegunn/fzf[FZF]
* link:https://git-scm.com[Git]
* link:https://github.com/dandavison/delta[Git Delta]
* link:https://github.com/newren/git-filter-repo[Git Filter Repo]
* link:https://github.com/github/git-sizer[Git Sizer]
* link:https://www.gnupg.org[GPG]
* link:https://github.com/orf/gping[gping]
* link:http://www.graphicsmagick.org[Graphics Magick]
* link:https://www.graphviz.org[Graphviz]
* link:https://github.com/sharkdp/hexyl[hexyl]
* link:http://www.andre-simon.de/doku/highlight/en/highlight.php[Highlight]
* link:https://github.com/mgdm/htmlq[htmlq]
* link:https://hisham.hm/htop[htop]
* link:https://github.com/reorx/httpstat[HTTP Stat]
* link:https://github.com/sharkdp/hyperfine[Hyperfine]
* link:https://imagemagick.org[ImageMagick]
* link:https://stedolan.github.io/jq[jq]
* link:https://lnav.org[lnav]
* link:https://github.com/CISOfy/lynis[Lynis]
* link:https://github.com/mas-cli/mas[Mac App Store]
* link:https://jedisct1.github.io/minisign[Minisign]
* link:https://github.com/variadico/noti[Noti]
* link:https://github.com/hatoo/oha[Oha]
* link:https://ollama.com[Ollama]
* link:https://www.openssh.com[OpenSSH]
* link:https://openssl.org[OpenSSL]
* link:https://osv.dev[Open Source Vulnerability Scanner]
* link:https://github.com/DarthSim/overmind[Overmind]
* link:https://pandoc.org[Pandoc]
* link:https://savannah.gnu.org/projects/parallel[Parallel]
* link:https://github.com/sharkdp/pastel[Pastel]
* link:https://www.pgcli.com[pgcli]
* link:https://www.zlib.net/pigz[Pigz]
* link:https://github.com/GPGTools/pinentry[Pinentry]
* link:https://github.com/dalance/procs[Procs]
* link:https://protobuf.dev[Protobuf]
* link:https://tiswww.case.edu/php/chet/readline/rltop.html[Readline]
* link:http://redis.io[Redis]
* link:https://github.com/BurntSushi/ripgrep[ripgrep]
* link:https://github.com/koalaman/shellcheck[ShellCheck]
* link:https://www.joedog.org/siege-home[Siege]
* link:https://www.tarsnap.com[Tarsnap]
* link:https://www.terraform.io[Terraform]
* link:https://github.com/ggreer/the_silver_searcher[The Silver Surfer]
* link:https://github.com/tmux/tmux/wiki[tmux]
* link:https://github.com/XAMPPRocky/tokei[Tokie]
* link:https://vale.sh[Vale]
* link:https://github.com/sachaos/viddy[Viddy]
* link:https://www.vim.org[Vim]
* link:https://github.com/libvips/libvips[Vips]
* link:https://github.com/vi/websocat[Websocat]
* link:https://developers.yubico.com/yubikey-manager[YubiKey Manager CLI]
* link:https://github.com/ajeetdsouza/zoxide[Zoxide]

=== Homebrew Casks

Installs the following link:https://brew.sh[casks]:

* link:https://www.alfredapp.com[Alfred]
* link:https://freemacsoft.net/appcleaner[App Cleaner]
* link:https://www.rogueamoeba.com/audiohijack[Audio Hijack]
* link:https://www.balena.io/etcher[Balena Etcher]
* link:https://brave.com[Brave]
* link:https://bombich.com[Carbon Copy Cloner]
* link:https://getcleanshot.com[CleanShot]
* link:https://discord.com[Discord]
* link:https://software.charliemonroe.net/downie[Downie]
* link:https://www.getdoxie.com[Doxie]
* link:https://www.dropbox.com[Dropbox]
* link:https://www.mozilla.com/en-US/firefox[Firefox]
* link:https://www.rogueamoeba.com/fission[Fission]
* link:https://www.google.com/chrome[Google Chrome]
* link:https://www.noodlesoft.com[Hazel]
* link:https://iina.io[IINA]
* link:http://imageoptim.pornel.net[ImageOptim]
* link:https://bjango.com/mac/istatmenus[iStat Menus]
* link:https://www.iterm2.com[iTerm2]
* link:https://mitmproxy.org[mitmproxy]
* link:https://mockuuups.studio[Mockuuups Studio]
* link:https://netnewswire.com[NewNewsWire]
* link:https://ngrok.com[Ngrok]
* link:https://numi.app[Numi]
* link:https://obsidian.md[Obsidian]
* link:https://www.openoffice.org[OpenOffice]
* link:https://orbstack.dev[OrbStack]
* link:https://kagi.com/orion[Orion]
* link:https://www.owasp.org/index.php/OWASP_Zed_Attack_Proxy_Project[OWASP Zed Attack Proxy (ZAP)]
* link:https://cocoatech.com[Path Finder]
* link:https://www.pgadmin.org[pgAdmin]
* link:https://superhighfives.com/pika[Pika]
* link:https://getpixelsnap.com[PixelSnap]
* link:https://protonvpn.com[ProtonVPN]
* link:https://paw.cloud[Rapid API]
* link:https://manytricks.com/resolutionator[Resolutionator]
* link:https://flyingmeat.com/retrobatch[Retrobatch]
* link:https://signal.org[Signal]
* link:https://skim-app.sourceforge.io[Skim]
* link:https://www.sublimetext.com[Sublime Text]
* link:https://panic.com/transmit[Transmit]
* link:https://twist.com[Twist]
* link:https://www.sparklabs.com/viscosity[Viscosity]
* link:https://code.visualstudio.com[Visual Studio Code]
* link:https://vivaldi.com[Vivaldi]
* link:https://zed.dev[Zed]

=== App Store

Installs link:https://www.apple.com/app-store[App Store] applications as managed by the link:https://github.com/mas-cli/mas[Mac App Store] CLI which assumes you've _purchased_ the applications listed below:

* link:https://secure.flyingmeat.com/acorn[Acorn]
* link:https://bitwarden.com[Bitwarden]
* link:https://ccmenu.org[CCMenu]
* link:https://sindresorhus.com/system-color-picker[Color Picker]
* link:https://daisydiskapp.com[DaisyDisk]
* link:https://dropoverapp.com[Dropover]
* link:https://www.apple.com/mac/garageband[GarageBand]
* link:https://handmirror.app[Hand Mirror]
* link:https://www.apple.com/imovie[iMovie]
* link:https://firecore.com/infuse[Infuse]
* link:https://manytricks.com/keycodes[Key Codes]
* link:https://manytricks.com/keymou[Keymou]
* link:https://www.apple.com/keynote[Keynote]
* link:https://apps.apple.com/us/app/amazon-kindle/id302584613[Kindle]
* link:http://limechat.net/mac[LimeChat]
* link:https://marked2app.com[Marked 2]
* link:http://getmedis.com[Medis]
* link:https://trymeeter.com[Meeter]
* link:https://www.markvapps.com/metadatics[Metadatics]
* link:https://mindnode.com[MindNode]
* link:https://manytricks.com/namemangler[Name Mangler]
* link:https://www.apple.com/numbers[Numbers]
* link:https://www.omnigroup.com/omnifocus[OmniFocus]
* link:https://www.apple.com/pages[Pages]
* link:https://krillapps.com/patterns[Patterns]
* link:https://software.charliemonroe.net/permute[Permute]
* link:https://apps.apple.com/app/apple-store/id1494948845[Paletter]
* link:https://apps.apple.com/gb/app/sequence-diagram/id1195426709[Sequence Diagram]
* link:https://shapesapp.com[Shapes]
* link:https://slack.com[Slack]
* link:https://www.adriangranados.com[WiFi Explorer]

=== Applications

Installs the following, basic, macOS applications which are not located in the App Store:

* link:https://appmap.io[AppMap]
* link:https://www.docker.com[Docker]
* link:https://icemenubar.app[Ice]
* link:https://moneywell.app[MoneyWell]
* link:https://manytricks.com/moom[Moom]
* link:https://github.com/theory/pgenv[pgenv]
* link:https://www.sonos.com[Sonos]
* link:https://tana.inc[Tana]
* link:https://tuple.app[Tuple]

=== Application Extensions

Installs the following extensions to existing applications:

* link:https://github.com/tpope/vim-bundler[Vim Bundler]
* link:https://github.com/tpope/vim-commentary[Vim Commentary]
* link:https://github.com/tpope/vim-fugitive[Vim Fugitive]
* link:https://github.com/airblade/vim-gitgutter[Vim Git Gutter]
* link:https://github.com/tpope/vim-pathogen[Vim Pathogen]
* link:https://github.com/tpope/vim-projectionist[Vim Projectionist]
* link:https://github.com/tpope/vim-rails[Vim Rails]
* link:https://github.com/vim-ruby/vim-ruby[Vim Ruby]
* link:https://github.com/AndrewRadev/splitjoin.vim[Vim Splitjoin]
* link:https://github.com/kana/vim-textobj-user[Vim Text Object User]
* link:https://github.com/tpope/vim-unimpaired[Vim Unimpaired]

=== Node Packages

Installs the following link:https://nodejs.org[Node] link:https://www.npmjs.com[packages]:

_None are used at the moment._

=== Ruby Gems

Installs the following link:https://www.ruby-lang.org[Ruby] link:https://rubygems.org[gems]:

* link:https://github.com/amazing-print/amazing_print[Amazing Print]
* link:https://asciidoctor.org[ASCII Doctor]
* link:https://github.com/evanphx/benchmark-ips[Benchmark IPS]
* link:https://github.com/jmmastey/bundler-stats[Bundler Stats]
* link:https://github.com/mattbrictson/bundleup[BundleUp]
* link:https://alchemists.io/projects/caliber[Caliber]
* link:https://alchemists.io/projects/gemsmith[Gemsmith]
* link:https://alchemists.io/projects/git-lint[Git Lint]
* link:https://hanamirb.org[Hanami]
* link:https://alchemists.io/projects/hanamismith[Hanamismith]
* link:https://alchemists.io/projects/irb-kit[IRB Kit]
* link:https://github.com/jaredbeck/libyear-bundler[Libyear (Bundler)]
* link:https://alchemists.io/projects/pennyworth[Pennyworth]
* link:https://github.com/joonty/pessimize[Pessimize]
* link:https://alchemists.io/projects/pragmater[Pragmater]
* link:https://rubyonrails.org[Ruby on Rails]
* link:https://github.com/troessner/reek[Reek]
* link:https://github.com/AlexB52/retest[Retest]
* link:https://rspec.info[RSpec]
* link:https://alchemists.io/projects/rubysmith[Rubysmith]
* link:https://solargraph.org/guides[Solargraph]
* link:https://alchemists.io/projects/sublime_text_kit[Sublime Text Kit]
* link:https://github.com/ruby-syntax-tree/syntax_tree[Syntax Tree]
* link:https://github.com/red-data-tools/YouPlot[YouPlot]

=== Rust Crates

Installs the following link:https://www.rust-lang.org[Rust] link:https://crates.io[crates]:

* link:https://atuin.sh[Atuin]
* link:https://github.com/nabijaczleweli/cargo-update[Cargo Update]
* link:https://dotenv-linter.github.io[Dotenv Linter]
* link:https://eza.rocks[Eza]
* link:https://jj-vcs.github.io[Jujutsu]
* link:https://jless.io[jless]
* link:https://github.com/chmln/sd[sd]

== Requirements

. Apple Silicon hardware.
. link:https://alchemists.io/projects/mac_os[macOS]
. link:https://developer.apple.com/xcode[Xcode]

== Setup

To install, run:

[source,bash]
----
git clone https://github.com/bkuhlmann/mac_os-config.git
cd mac_os-config
git checkout 29.5.0
----

== Usage

The following will walk you through the steps of installing/re-installing your machine.

=== Pre-Install

Ensure you have the following in place for your Silicon machine:

. Ensure a backup of your Apple, NAS, backup image, and Dropbox credentials are available.
. Ensure a recent backup of your machine exists and works properly.
. Ensure link:https://support.apple.com/en-us/HT208198[Startup Security Utility] is disabled.
.. Turn off your machine.
.. Start your machine by pressing and holding the `POWER` button until you see startup options being
   loaded.
.. Select Utilities → Startup Security Utility from the main menu.
.. Select _Reduced Security_.
.. Quit the utility and restart the machine.

=== Install

. Create a link:https://alchemists.io/projects/mac_os/#_boot_disk[macOS Boot Disk] and follow
  instructions.
. Ensure latest software updates are applied per
  link:https://alchemists.io/projects/mac_os/#_requirements[macOS Requirements].
. Ensure Xcode is installed per link:https://alchemists.io/projects/mac_os/#_requirements[macOS
  Requirements].
. Run link:https://alchemists.io/projects/mac_os#_usage[macOS Install] and follow all prompts.

=== Post-Install

The following are additional steps, not easily automated, that are worth completing after the
install scripts have completed:

* System Preferences
** Apple ID
*** Login (if not already).
*** Update avatar.
*** Configure iCloud.
*** Enable Find My Mac.
** Bluetooth
*** Reconnect keyboard, mouse, and earbuds.
** Sound
*** Disable _Play sound on startup_.
*** Disable _Play user interface sound effects_.
** Screen Time
*** Disable entire feature.
** General
*** AirDrop & Handoff
**** Disable _AirPlay Receiver_ so you can run link:https://github.com/rack/rack[Rack] applications on Port 5000.
*** AutoFill & Passwords
**** Disable _AutoFill Passwords and Passkeys_.
*** Login Items
**** Ensure only _Alfred_ is listed.
*** Language and Region
**** Set _First day of week_ to _Monday_.
**** Set _Date format_ to _YYYY-MM-DD_.
** Accessibility
*** Hearing
**** Enable _Turn off background sounds when your Mac is not in use._
** Appearance
*** Use _Light_ theme.
** Apple Intelligence & Siri
*** Disable _Listen for_.
*** Disable _Keyboard shortcut_ (use Alfred instead).
**  Privacy & Security
*** Enable _FileVault_.
** Wallpaper
*** Select custom image from _Documents_.
** Spotlight
*** Disable _Help Apple Improve Search_. link:https://obdev.at/blog/what-happens-on-your-device-stays-on-your-device-until-it-doesnt[Details].
** Screen Saver
*** Use _Message_ with custom text.
** Battery
*** Click _Options_ and enable _Prevent automatic sleeping on power adapter when the
display is off_.
** Lock Screen
*** Set _Start Screen Saver when inactive_ for 5 minutes.
*** Set _Turn display off on battery when inactive_ for 2 minutes.
*** Set _Turn display off on power adapter when inactive_ for 10 minutes.
*** Set _Require password after screen saver begins or display is turned off_ for 5 minutes.
*** Set _Show message when locked_. Example: ` |  | `.
** Touch ID & Password
*** Rename fingerprint.
*** Enable use of Touch ID for all settings.
*** Enable use of Apple Watch.
** Users & Groups
*** Update avatar image.
*** Remove unused login items.
*** Disable guest account.
** Internet Accounts
*** Add all accounts.
** Wallet & Apple Pay
*** Reenable all accounts and assign default card.
** Keyboard
*** Set _Key repeat rate_ to max level.
*** Set _Delay until repeat_ to short (max) level.
*** Keyboard Shortcuts
**** Select _Launchpad and Dock_ and uncheck _Turn Dock Hiding On/Off_.
**** Select _Mission Control_ and assign `CONTROL + OPTION + COMMAND + N` to _Show Notification
     Center_.
**** Within _Mission Control_, assign `CONTROL + OPTION + COMMAND + W` to _Mission Control_.
**** Select _Screenshots_ and uncheck all boxes.
**** Select _Spotlight_ and uncheck all boxes.
** Mouse
*** Ensure tracking speed is on the 5th setting (i.e. 5th from right of _Slow_).
** Trackpad
*** Ensure tracking speed is on the 5th setting (i.e. 5th from right of _Slow_).
** Printers & Scanners
*** Add printer/scanner.
* iStat Menus
** Double click, within the Applications folder, to install as a system preference.
* Carbon Copy Cloner
** Rename old backup, create new backup, and schedule frequency.
* Notifications
** Set _Show previews when unlocked_.
** Disable _Allow notifications when the display is sleeping_.
** Disable _Allow notifications when the screen is locked_.
** Disable _Allow notifications when mirroring or sharing the display_.
** Disable _Show notifications on lock screen_ and _Play sound for notification_ for all applications.
** Enable _Allow notifications from iPhone_ but disable _Play sounds for notifications from iPhone_ within this option.

=== Keyboard Shortcuts

Several applications provide global hotkey support. These are the associations I use (which are also
captured in the `+restore.bom+` as well):

* *COMMAND (x2)*: Siri (open)
* *COMMAND + SPACE*: Alfred/Spotlight (open)
* link:https://alchemists.io/articles/clean_shot/#_shortcuts[CleanShot]
* *CONTROL + OPTION + COMMAND + c*: Pika (copy color)
* *CONTROL + OPTION + COMMAND + d*: Alfred Define (use OPTION to open Dictionary)
* *CONTROL + OPTION + COMMAND + h*: Alfred Highlight Syntax
* *CONTROL + OPTION + COMMAND + k*: Keymou (cursor highlight show/hide)
* *CONTROL + OPTION + COMMAND + m*: Moom (toggle)
* *CONTROL + OPTION + SHIFT + m*: Moom (open custom actions)
* *CONTROL + OPTION + COMMAND + n*: Notification Center (show/hide)
* *CONTROL + OPTION + COMMAND + o*: Alfred Open URL in default browser
* link:https://alchemists.io/articles/pixel_snap/#_shortcuts[PixelSnap]
* *CONTROL + OPTION + COMMAND + r*: Resolutionator (selector)
* *CONTROL + OPTION + COMMAND + t*: Alfred Large Type
* *CONTROL + OPTION + COMMAND + w*: Mission Control
* *CONTROL + OPTION + COMMAND + ←*: Keymou (move cursor left)
* *CONTROL + OPTION + COMMAND + ↑*: Keymou (move cursor up)
* *CONTROL + OPTION + COMMAND + →*: Keymou (move cursor right)
* *CONTROL + OPTION + COMMAND + ↓*: Keymou (move cursor down)
* *CONTROL + OPTION + COMMAND + ENTER*: Keymou (move cursor by division)
* *CONTROL + OPTION + SPACE*: OmniFocus (quick entry)
* *OPTION + SPACE*: Alfred (open)

💡 See additional link:https://saurabhs.org/macos-tips[tips] for details.

=== Newsyslog

Native to macOS, link:https://www.freebsd.org/cgi/man.cgi?newsyslog.conf(5)[newsyslog] can be used
to configure system-wide log rotation across multiple projects. It’s a good recommendation to set
this up so that disk space is carefully maintained. Here’s how to configure it for your system,
start by creating a configuration for your projects in the `+/etc/newsyslog.d+` directory. In my
case, I use the following configurations:

* `+/etc/newsyslog.d/alchemists.conf+`
+
....
  # logfilename                                            [owner:group]    mode   count   size  when  flags
  /Users/bkuhlmann/Dropbox/Development/Work/**/log/*.log                    644    2       5120  *     GJN
....
* `+/etc/newsyslog.d/homebrew.conf+`
+
....
  # logfilename                   [owner:group]    mode   count   size    when  flags
  /usr/local/var/log/**/*.log                      644    2       5120    *     GJN
....

These configurations ensure that logs are rotated every 5MB (5120KB). In order to test that these
configurations are valid, run:

....
sudo newsyslog -nvv
....

If you don’t see any errors in the output, then your configuration settings are correct.

The last thing to do is to add a launch configuration to ensure the log rotations happen at
regularly scheduled intervals. To do this create the following file:
`+$HOME/Library/LaunchAgents/com.apple.newsyslog.plist+`. It should have the following content:

[source,xml]
----




  Label
  com.apple.newsyslog
  ProgramArguments
  
    /usr/sbin/newsyslog
  
  LowPriorityIO
  
  Nice
  1
  StartCalendarInterval
  
    Minute
    30
  


----

That’s it. System-wide log rotation is setup for your projects.

=== Customization

While this project’s configuration is opinionated and tailored for my setup, you can easily fork
this project and customize it for your environment. Start by editing the files found in the `+bin+`
and `+lib+` directories. Check out the
link:https://alchemists.io/projects/mac_os/#_customization[macOS Customization Documentation]
for further details.

_TIP_: The installer determines which applications/extensions to install as defined in the
`+settings.sh+` script. Applications defined with the "`APP_NAME`" suffix and extensions defined
with the "`EXTENSION_PATH`" suffix inform the installer what to care about. Removing/commenting out
these applications/extensions within the `+settings.sh+` file will cause the installer to skip these
applications/extensions.

== Development

To contribute, run:

[source,bash]
----
git clone https://github.com/bkuhlmann/mac_os-config.git
cd mac_os-config
----

== link:https://alchemists.io/policies/license[License]

== link:https://alchemists.io/policies/security[Security]

== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]

== link:https://alchemists.io/policies/contributions[Contributions]

== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]

== link:https://alchemists.io/projects/mac_os-config/versions[Versions]

== link:https://alchemists.io/community[Community]

== Credits

Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

Owner

Citation (CITATION.cff)

cff-version: 1.2.0
message: Please use the following metadata when citing this project in your work.
title: macOS Configuration
abstract: Shell scripts for customized macOS machine setup.
version: 29.5.0
license: Hippocratic-2.1
date-released: 2025-07-04
authors:
  - family-names: Kuhlmann
    given-names: Brooke
    affiliation: Alchemists
    orcid: https://orcid.org/0000-0002-5810-6268
keywords:
 - bash
 - shell
 - scripts
 - automation
 - setup
 - recovery
repository-code: https://github.com/bkuhlmann/mac_os-config
repository-artifact: https://alchemists.io/projects/mac_os-config
url: https://alchemists.io/projects/mac_os-config

GitHub Events

Committers

Last synced: 9 months ago

Issues and Pull Requests

Last synced: 11 months ago