launchd
For services running in the background (or foreground), macOS uses launchd (think cron jobs on Linux or scheduled tasks on Windows).
Legacy Subcommands
If you’ve been managing Macs for a while, you may be familiar with a particular syntax for loading launchd.
For launch agents (usually run as user), you may typically have launched them with
launchctl load /Library/LaunchAgents/com.domainname.app.plist
For launch daemons (usually run as root), you may typically have launched them with
sudo launchctl load /Library/LaunchDaemons/com.domainname.app.plist
If you read the manual for launchctl (man launchctl), you’ll see load and unload listed as legacy subcommands:
Legacy subcommands should still work. I don’t believe they’re fully deprecated (at least as of this writing).
“New” subcommands
But there are now subcommands that aren’t legacy:
For a super-comprehensive breakdown on what all these “new” subcommands are, you may want to check out Babo D’s Launchctl 2.0 Syntax post (from 2016!), but I thought I’d just do a quick breakdown here of the basics.
launchctl subcommand basics
Don’t come for me. As I mentioned above, there are far more comprehensive breakdowns of launchctl subcommands. This is just the basics. Not much nuance. Just how do you do it if you’ve been doing it the “legacy” way this whole time.
Listing with launchctl
With legacy subcommands, to get launch agents, you’d run
launchctl list
and that would give you a list of launch agents that are running.
With the “new” subcommands, you would do something like
launchctl print gui/501
Well, that’s assuming your uid is 501, which it may not be. If you want to find your uid, you can use id -u. If you want to find the uid of a specific other user account, you can use id -u username. You could also find the uids of a bunch of users by running dscl . -list /Users UniqueID | grep -v _
With legacy subcommands, to get launch daemons, you’d run
sudo launchctl list
or run launchctl list as root (e.g., via Munki or Jamf).
With the “new” subcommands, you would do
launchctl print system
The nice thing about doing that is you’re specifying system, so it doesn’t matter if you run it as root or as user—you’ll just get the system (root-level) launchd.
With either type of listing type, you won’t just get a list of process IDs and labels (you will still get those under services), but you’ll also get a list of what are called disabled services, which is a bit confusing, because that list will include both disabled and enabled services.
So, for example, for Nudge, you might see something like
0 0 com.github.macadmins.Nudge
under services but then something like
"com.github.macadmins.Nudge" => enabled
under disabled services.
You’ll probably find ways to parse the output, but just be aware there is this note in man launchctl:
IMPORTANT: This output is NOT API in any sense at all. Do NOT
rely on the structure or information emitted for ANY reason. It
may change from release to release without warning.
Launching launch agents
Instead of running
launchctl load /Library/LaunchAgents/com.github.macadmins.Nudge.plist
you’d run something like
launchctl bootstrap gui/501 /Library/LaunchAgents/com.github.macadmins.Nudge.plist
Launching launch daemons
Instead of running
sudo launchctl load /Library/LaunchDaemons/com.github.macadmins.Nudge.logger.plist
you’d run something like
sudo launchctl bootstrap system /Library/LaunchDaemons/com.github.macadmins.Nudge.logger.plist
Obviously, if you’re running this in a script from a root-run management tool (e.g., Munki or Jamf), you wouldn’t preface commands with sudo.
Unloading launch agents
Instead of running
launchctl unload /Library/LaunchAgents/com.github.macadmins.Nudge.plist
you’d run something like
launchctl bootout gui/501/com.github.macadmins.Nudge
Unloading launch daemons
Instead of running
sudo launchctl unload /Library/LaunchDaemons/com.github.macadmins.Nudge.logger.plist
you’d run something like
sudo launchctl bootout system/com.github.macadmins.Nudge.Logger
Reminder: don’t preface with sudo in root-run scripts.
Disabling a launch daemon or agent
Instead of bootout, you would use disable to disable a launch daemon or agent. Example:
sudo launchctl disable system/com.github.macadmins.Nudge.Logger
Just be careful with this. If you disable it, you can’t then just bootstrap it right afterwards:
sudo launchctl bootstrap system /Library/LaunchDaemons/com.github.macadmins.Nudge.logger.plist
Bootstrap failed: 5: Input/output error
First, you want to re-enable it:
sudo launchctl enable system/com.github.macadmins.Nudge.Logger
Then you can bootstrap it:
sudo launchctl bootstrap system /Library/LaunchDaemons/com.github.macadmins.Nudge.logger.plist
That’s all I’ve got for now. As I mentioned earlier, you can read a more comprehensive breakdown at Launchctl 2.0 Syntax.