caffeinate - macOS

Overview

The caffeinate command in macOS is used to prevent the system from sleeping. This utility is particularly useful when you need to ensure your computer remains awake during long-running tasks that do not involve user interaction, such as large file transfers, backups, or long computations. It is also handy during presentations to avoid the screen saver or sleep mode activation.

Syntax

The basic syntax of the caffeinate command is as follows:

caffeinate [options] [utility arguments...]

When used without options, caffeinate will prevent the system from sleeping indefinitely until it is manually terminated with Ctrl-C or another stop signal.

Options/Flags

  • -d: Prevent the display from sleeping.
  • -i: Prevent the system from idle sleeping.
  • -m: Prevent the disk from sleeping.
  • -s: Keep the system awake only when the system is plugged into AC power.
  • -u: Declare that user activity is occurring. This is useful for cases where the system needs to appear as being used actively.
  • -t timeout: Specifies the duration in seconds for which the command should keep the system awake. After this period, normal sleep behavior resumes.
  • -w pid: Wait for the process with the specified process ID pid to exit and then allow the system to sleep normally.

Options can be combined to cover multiple requirements. Without any arguments, caffeinate affects the system sleep behavior only temporarily and must be stopped manually.

Examples

  1. Prevent sleep while using a specific application:

    caffeinate -i -t 3600

    This command prevents the system from idle sleeping for one hour.

  2. Combine options to prevent both display and system sleep while running a script:

    caffeinate -di ./long_running_script.sh

    This keeps the display and system awake while long_running_script.sh is running.

  3. Prevent sleep indefinitely until explicitly stopped:

    caffeinate

    Execute caffeinate with no arguments to keep the system awake until you cancel it with Ctrl-C.

Common Issues

  • Mistaking sleep prevention types: Users sometimes use -d when they mean -i, leading to unexpected sleeps. Ensure you choose the correct flag for your scenario.
  • Forgetting to terminate caffeinate: When run without a timeout or specific process, caffeinate will keep the system awake indefinitely, which might lead to unnecessary power consumption.

Integration

caffeinate can be integrated into scripts or used in combination with other commands. For example, to ensure your computer stays awake during a system backup using rsync, you could use:

caffeinate -s rsync -avz /source /destination

This command will prevent the system from sleeping as long as it is connected to AC power during the synchronization process.

  • pmset: Used to manipulate power management settings, which can achieve similar effects in a more permanent manner compared to caffeinate.

For further information, consult the caffeinate man page in macOS or visit the official Apple developer documentation.

This comprehensive overview of the caffeinate command should help you effectively manage sleep behavior on macOS devices for a wide range of practical applications, ensuring that your device remains awake and functional when you need it most.