Making a good Recovery: So many tools

Recovery Mode aims to provide the user and technician with all the tools they need to recover a Mac stricken by problems. Major tools, such as Disk Utility and the macOS Installer, are easy to access, being placed on the Recovery ‘Springboard’, its substitute for the Finder which is used to launch GUI apps. This article briefly reviews those before passing on to those that aren’t so obvious, and mostly accessed through Terminal. It applies mainly to M1 Macs, but some tools are common to Intel Macs running Big Sur.


The chart above summarises how to access all the main tools, and here is a tear-out PDF version: M1MacBootModes

In addition to those, the Window menu gives access to the Recovery log, which can be saved to any mounted disk. Although you might think that this is the only log available, in fact Recovery keeps standard Unified logs, which can be accessed using the log command in Terminal, as explained below.

If you use Recovery to install macOS, the version installed is that matching the firmware installed (on the internal SSD). Thus if that Mac has been upgraded to macOS 11.4, installing macOS will also deliver 11.4. When you install a Monterey beta-release on an M1 Mac, that ensures that same beta will be installed in Recovery. Although there are ways which can be used to install older versions, they don’t appear reliable. The Install macOS Big supplied isn’t complete, and normally requires to download much of its payload in the form of the SharedSupport.dmg required for a full installation.

A plethora of additional recovery tools are accessible in Terminal, which runs the more traditional bash shell, rather than zsh, and the user is here given root privileges, so there’s no sudo needed or provided.

Here I provide some of the highlights of the command tools accessible in Big Sur 11.4 recoveryOS on an M1 Mac. If you want to get the most out of Recovery, I recommend that you spend a little time cruising its directories.

Tools found in sbin include a full suite of fsck support for APFS, HFS+, exFAT, MSDOS, UDF and CS file systems, and all the main APFS tools including apfs_hfs_convert for converting HFS+ to APFS. Two more unusual tools are also included:

  • fibreconfig to configure hardware ports in the M1 Fibre. Note that this isn’t the old Fibre Channel tool of the same name. As with many of these tools, this has no man page, but the option -h returns usage information.
  • mpioutil to manage multiple paths to a SCSI Logical Unit, which seems strange, and it has a man page.

In /usr/bin, there are important tools such as bputil, codesign, curl, defaults, hdiutil, and tccutil. Worth studying are:

  • csrutil which here has several options only available in recoveryOS, including one which allows booting from non-sealed snapshots.
  • hpmdiagnose to collect diagnostic information to help with the investigation of USB-C issues.
  • kmutil, which is one of several kernel management utilities provided.
  • recoverydiagnose which is the equivalent of sysdiagnose for recoveryOS, and is only available in recoveryOS.
  • trustcachectl, which works with trustcaches, as the name implies. This has no man page, only usage information.

Most significantly, recoveryOS runs a normal Unified log, with the command tool log available to give access to it. If you don’t fancy working live with that, it’s straightforward to use the log collect command to save the current log files into a logarchive on an accessible volume, then to browse that using Ulbow, Consolation 3, or even Console if you really can’t do any better. In recoveryOS, the system is very lean and entries are minimal compared to those of a full working macOS, often with less than 1,000 entries per minute, making browsing the whole log more feasible.

In /usr/sbin are diskutil, filevaultRecovery, pkgutil, repairHomePermissions, resetFileVaultPassword, resetpassword, scutil, spctl and sysctl. Less well-known are:

  • vsdbutil to manipulate the volume status database. This apparently works with the on-disk permissions database for HFS+ file systems, and has long been deprecated.
  • xartutil is an xART recovery utility. It has no man page, and even getting usage info requires it to be run as root.

You should also be able to run your own software from within recoveryOS, perhaps loaded from an external disk or a mounted disk image. GUI apps are likely to need special builds to ensure they don’t have any dependencies on frameworks and other features which aren’t supported by this reduced macOS. There also doesn’t appear to be any way to add them to the Recovery Dashboard, or launch them except in Terminal. Command tools should be a safer bet, though. One important limitation to bear in mind is the fact that every executable has to run native on ARM, as recoveryOS has no Rosetta 2 support.