How to use the command `launchctl` (with examples)

launchctl is a command-line utility that allows control over Apple’s launchd manager for launch daemons (system-wide services) and launch agents (per-user programs). It enables the loading and unloading of XML-based *.plist files that define the schedule of corresponding commands to be executed by launchd. Here are several use cases that demonstrate how to use the launchctl command.

Use case 1: Activate a user-specific agent to be loaded into launchd whenever the user logs in

Code:

launchctl load ~/Library/LaunchAgents/my_script.plist

Motivation: This command is used to activate a specific agent (my_script.plist) for a particular user. By loading the agent into launchd, it ensures that the agent is executed whenever the user logs in.

Explanation:

• launchctl is the command itself.
• load is the subcommand used to load an agent or daemon into launchd.
• ~/Library/LaunchAgents/my_script.plist specifies the path to the XML-based .plist file that defines the agent to be loaded. The ~ represents the home directory of the currently logged in user.

Example output:

No output is generated if the command is successful.

Use case 2: Activate an agent which requires root privileges to run and/or should be loaded whenever any user logs in

Code:

sudo launchctl load /Library/LaunchAgents/root_script.plist

Motivation: This command is used when an agent requires root privileges to run or should be loaded for all users. The sudo command grants the necessary permissions.

Explanation:

• sudo is a command used to execute commands with root or superuser privileges.
• launchctl load loads the specified agent or daemon into launchd.
• /Library/LaunchAgents/root_script.plist specifies the path to the .plist file that defines the agent to be loaded. Unlike the first use case, the absence of ~ indicates an absolute path, allowing it to be loaded for any user.

Example output:

No output is generated if the command is successful.

Use case 3: Activate a system-wide daemon to be loaded whenever the system boots up

Code:

sudo launchctl load /Library/LaunchDaemons/system_daemon.plist

Motivation: This command is used to activate a system-wide daemon that should be loaded during the system startup, regardless of whether any user logs in.

Explanation:

• sudo executes the command with elevated privileges.
• launchctl load loads the specified daemon into launchd.
• /Library/LaunchDaemons/system_daemon.plist is the path to the XML-based .plist file that defines the daemon to be loaded. Since it is located in the /Library/LaunchDaemons directory, it will be loaded for all users.

Example output:

No output is generated if the command is successful.

Use case 4: Show all loaded agents/daemons, with their process ID (PID) and exit code

Code:

launchctl list

Motivation: This command displays a list of all loaded agents and daemons along with their process ID (PID) and the exit code returned the last time they ran. It is useful for monitoring the status of currently loaded processes.

Explanation:

• launchctl list is the command to display the list of loaded agents and daemons.

Example output:

PID    Status  Label
123    -       com.example.agent1
456    0       com.example.agent2

• PID represents the Process ID of the agent or daemon.
• Status provides information about the current status of the agent or daemon.
• Label is the unique identifier for each agent or daemon.

Use case 5: Unload a currently loaded agent to make changes

Code:

launchctl unload ~/Library/LaunchAgents/my_script.plist

Motivation: This command allows the unloading of a currently loaded agent to make changes or modifications without requiring a system reboot or re-logging in.

Explanation:

• launchctl unload unloads the specified agent from launchd.
• ~/Library/LaunchAgents/my_script.plist is the path to the .plist file that defines the agent to be unloaded. The ~ represents the home directory of the currently logged in user.

Example output:

No output is generated if the command is successful.

Use case 6: Manually run a known (loaded) agent/daemon, even if it is not the right time

Code:

launchctl start script_file

Motivation: This command allows the manual start of a known agent or daemon, regardless of whether it is the appropriate time for it to run according to its schedule.

Explanation:

• launchctl start initiates the execution of the specified agent or daemon.
• script_file denotes the label or unique identifier of the agent or daemon, rather than the filename.

Example output:

No output is generated if the command is successful.

Use case 7: Manually kill the process associated with a known agent/daemon if it is running

Code:

launchctl stop script_file

Motivation: This command is employed to manually terminate the process associated with a known agent or daemon if it is currently running. It provides a way to stop the execution of unnecessary or problematic processes.

Explanation:

• launchctl stop halts the execution of the specified agent or daemon.
• script_file represents the label or identifier of the agent or daemon, not the filename.

Example output:

No output is generated if the command is successful.

Conclusion

The launchctl command is a powerful utility for controlling Apple’s launchd manager. It enables the activation, deactivation, management, and monitoring of launch agents and daemons. By understanding how to use the various command options, users gain greater control over the execution of processes within the system.