docs » hs.caffeinate

Control system power states (sleeping, preventing sleep, screen locking, etc)

NOTE: Any sleep preventions will be removed when hs.reload() is called. A future version of the module will save/restore state across reloads.

API Overview

API Documentation

Functions

declareUserActivity
Signature hs.caffeinate.declareUserActivity([id])
Type Function
Description

Informs the OS that the user performed some activity

Parameters:

  • id - An option number containing the assertion ID returned by a previous call of this function

Returns:

  • A number containing the ID of the assertion generated by this function

Notes:

  • This is intended to simulate user activity, for example to prevent displays from sleeping, or to wake them up
  • It is not mandatory to re-use assertion IDs if you are calling this function mulitple times, but it is recommended that you do so if the calls are related
get
Signature hs.caffeinate.get(sleepType) -> bool or nil
Type Function
Description

Queries whether a particular sleep type is being prevented

Parameters:

  • sleepType - A string containing the type of sleep to inspect (see hs.caffeinate.set() for information about the possible values)

Returns:

  • True if the specified type of sleep is being prevented, false if not. nil if sleepType was an invalid value
lockScreen
Signature hs.caffeinate.lockScreen()
Type Function
Description

Request the system lock the displays

Parameters:

  • None

Returns:

  • None
logOut
Signature hs.caffeinate.logOut()
Type Function
Description

Request the system log out the current user

Parameters:

  • None

Returns:

  • None
restartSystem
Signature hs.caffeinate.restartSystem()
Type Function
Description

Request the system reboot

Parameters:

  • None

Returns:

  • None
sessionProperties
Signature hs.caffeinate.sessionProperties()
Type Function
Description

Fetches information from the display server about the current session

Parameters:

  • None

Returns:

  • A table containing information about the current session, or nil if an error occurred

Notes:

  • The keys in this dictionary will vary based on the current state of the system (e.g. local vs VNC login, screen locked vs unlocked).
set
Signature hs.caffeinate.set(sleepType, aValue, acAndBattery)
Type Function
Description

Configures the sleep prevention settings

Parameters:

  • sleepType - A string containing the type of sleep to be configured. The value should be one of:
    • displayIdle - Controls whether the screen will be allowed to sleep (and also the system) if the user is idle.
    • systemIdle - Controls whether the system will be allowed to sleep if the user is idle (display may still sleep).
    • system - Controls whether the system will be allowed to sleep for any reason.
  • aValue - A boolean, true if the specified type of sleep should be prevented, false if it should be allowed
  • acAndBattery - A boolean, true if the sleep prevention should apply to both AC power and battery power, false if it should only apply to AC power

Returns:

  • None

Notes:

  • These calls are not guaranteed to prevent the system sleep behaviours described above. The OS may override them if it feels it must (e.g. if your CPU temperature becomes dangerously high).
  • The acAndBattery argument only applies to the system sleep type.
  • You can toggle the acAndBattery state by calling hs.caffeinate.set() again and altering the acAndBattery value.
shutdownSystem
Signature hs.caffeinate.shutdownSystem()
Type Function
Description

Request the system log out and power down

Parameters:

  • None

Returns:

  • None
startScreensaver
Signature hs.caffeinate.startScreensaver()
Type Function
Description

Request the system start the screensaver (which may lock the screen if the OS is configured to do so)

Parameters:

  • None

Returns:

  • None
systemSleep
Signature hs.caffeinate.systemSleep()
Type Function
Description

Requests the system to sleep immediately

Parameters:

  • None

Returns:

  • None
toggle
Signature hs.caffeinate.toggle(sleepType) -> bool or nil
Type Function
Description

Toggles the current state of the specified type of sleep

Parameters:

  • sleepType - A string containing the type of sleep to toggle (see hs.caffeinate.set() for information about the possible values)

Returns:

  • True if the specified type of sleep is being prevented, false if not. nil if sleepType was an invalid value

Notes:

  • If systemIdle is toggled to on, it will apply to AC only