Home

Nudge is a lightweight, open-source application that encourages users to update the operating system on their company-issued Mac (in accordance with their organization's IT policies). This encouragement comes in the form of reminders that are displayed front-and-center on the user’s screen, and which reappear more frequently until the Mac is in compliance.

Nudge has already been successfully deployed at hundreds of organizations across public and private sectors, with fleet sizes ranging from less than 100 Macs in a small office to over 10,000 Macs at multiple offices across the globe.

Nudge offers support for multiple languages, custom user deferral settings, and a range of optional features designed to strongly encourage users to update macOS.

Written in Swift 5.10, Nudge is compatible with macOS Monterey 12 and higher (please use Nudge 1.x releases for macOS 11). It is a replacement for the original Nudge-Python project. If you need to enforce macOS updates for earlier versions of macOS, it is recommend to use nudge-python instead.

The SwiftUI version of Nudge offers several distinct advantages:

An enhanced UI, redesigned with new functionality
A new UI called simpleMode
Support for localization
Support for Mac computers with Apple silicon
Customizable buttons and button actions
Customizable text elements (except for left sidebar)

OS support

The following operating system versions have been tested:

macOS 12.0 ~ 12.7
macOS 13.0 ~ 13.6.2
macOS 14.0 ~ 14.5

Troubleshooting

Before submitting any issues to Nudge, please ensure you using the latest version. You can find the version you are using by running Nudge and clicking on the ? button at the top left.

Alternatively you can run the -version argument through the command line

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge -version
1.1.13.81503

Nudge compatibility with MDM workflows

To deploy Nudge, your device management infrastructure must include some way to deploy macOS package (.pkg) files. While the Nudge configuration can be deployed to the Mac with a package, it is recommended to build a managed configuration profile (.mobileconfig) and deploy it via MDM.

Nudge Functionality Overview

Nudge consists of the following three components:

Nudge.app installed to /Applications/Utilities/Nudge.app
A LaunchAgent installed to /Library/LaunchAgents
A Preference file, either in JSON or mobileconfig format

Rather than trying to install updates via the macOS built-in softwareupdate binary, Nudge prompts users to install updates via Apple approved/tested methods: System Preferences > Software Update and major application upgrades via the standalone macOS installer (Ex: Install macOS Monterey.app). Note: in macOS 12.3 and higher, the 'standalone installer' is no longer used, and all updates are driven through the Software Update preference pane.

With the optionally provided LaunchAgent package, Nudge will open every 30 minutes, at the top and bottom of each hour. If you find this behavior too aggressive, you will need to create your own LaunchAgent.

Deploying Nudge

If you install the Nudge package without a configuration, you can attempt to open Nudge through Finder - but nothing will appear. Nudge will simply write a log entry to the macOS unified log indicating that a required configuration was not found.

Please read on to learn how to engage with Nudge through the command line.

Command Line Arguments

For a full listing of the available command line arguments, please see the wiki.

To open Nudge through the command-line application, open Terminal and run the following command:

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge

If you have just installed Nudge for the first time, you will likely see the following message returned:

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge
Device fully up-to-date.

Demo Mode

In order to trigger Nudge in demo mode, simply pass the -demo-mode argument

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-demo-mode

This will open Nudge in the English localization and allow you to test the buttons, as well as Light/Dark mode.

If you'd like to trigger simpleMode in Demo mode, chain the both -demo-mode and -simple-mode arguments

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-demo-mode \
-simple-mode

If you'd like to force the icon in Demo mode, chain the both -demo-mode and -force-screenshot-icon arguments

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-demo-mode \
-force-screenshot-icon

Simple Mode

If you'd like to force simple mode (and don't want to use the built in preferences configuration), simply pass the -simple-mode argument

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-simple-mode

JSON Support

Nudge has support for both remote JSON and local JSON.

By default, Nudge will look for local JSON located at /Library/Preferences/com.github.macadmins.Nudge.json.

Using the `-json-url` argument

Remote JSON

To use a remote JSON file, simply pass the -json-url argument.

Note: Spaces must be converted to %20, just as a standard URL. (This is required both for remote and local assets.)

The following example uses remote JSON included in the Nudge GitHub repository. (You can safely ignore any warnings indicating "There is no application set to open the URL munki://updates.")

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-json-url \
"https://raw.githubusercontent.com/macadmins/nudge/main/Example%20Assets/com.github.macadmins.Nudge.json"

Note: If the Mac on which you are testing Nudge has a later version of macOS than what is specified in requiredMinimumOSVersion, you will not observe the Nudge UI, but the Nudge logs will detail the actions taken. For example:

Nudge[9563]: [com.github.macadmins.Nudge:softwareupdate-download] enforceMinorUpdates: true
Nudge[9563]: [com.github.macadmins.Nudge:utilities] Current operating system (11.6) is greater than or equal to required operating system (11.5.2)
Nudge[9563]: [com.github.macadmins.Nudge:user-interface] Device is fully updated
Nudge[9563]: [com.github.macadmins.Nudge:user-interface] Nudge is terminating due to condition met

Local JSON

While the -json-url argument is mainly designed for web-hosted URLs, you can actually pass it a file:// path if you want to deploy JSON to a location other than /Library/Preferences or simply want to test your workflow:

Install the latest Nudge-1.1.9.x.pkg on a local test Mac
Save the sample JSON to your Downloads folder as com.github.macadmins.Nudge.json

curl -o ~/Downloads/com.github.macadmins.Nudge.json https://raw.githubusercontent.com/macadmins/nudge/main/Example%20Assets/com.github.macadmins.Nudge.json

Modify and save with your preferred editor
- Change requiredInstallationDate to a date in the future (or in the past)
- Change requiredMinimumOSVersion to a value greater than (or less than) the output of sw_vers -productVersion
- Review actionButtonPath
  - Munki: See Munki Links
  - Jamf Pro: See Jamf Self Service for macOS URL Schemes <-- replace "&" in such a string with &
  - Nudge v1.0.0 behavior: To open System Preferences > Software Update, delete the entire actionButtonPath line.
Execute the following command in Terminal:

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge \
-json-url \
"file:///Users/`id -n -u`/Downloads/com.github.macadmins.Nudge.json"

Press Control + C to break
Repeat Steps 2 through 4, modifying the values of requiredInstallationDate, requiredMinimumOSVersion, and actionButtonPath as desired

Setting the json-url in mobileconfig profile

Using PayloadType com.github.macadmins.Nudge in a mobileconfig, use the json-url

<key>PayloadContent</key>
<dict>
        <key>json-url</key>
        <string>https://example.org/nudge.json</string>
</dict>
<key>PayloadType</key>
<string>com.github.macadmins.Nudge</string>

Scheduling Nudge to run

Every release of Nudge comes with an optional LaunchAgent package.

This LaunchAgent will open Nudge every 30 minutes, at the top and bottom of each hour. If you find this behavior too aggressive, you will need to create your own LaunchAgent.

Example LaunchAgent

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>AssociatedBundleIdentifiers</key>
  <array>
   <string>com.github.macadmins.Nudge</string>
  </array>
  <key>Label</key>
  <string>com.github.macadmins.Nudge</string>
  <key>LimitLoadToSessionType</key>
  <array>
    <string>Aqua</string>
  </array>
  <key>ProgramArguments</key>
  <array>
    <string>/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge</string>
    <!-- <string>-json-url</string> -->
    <!-- <string>https://raw.githubusercontent.com/macadmins/nudge/main/Nudge/example.json</string> -->
    <!-- <string>-demo-mode</string> -->
    <!-- <string>-force-screenshot-icon</string> -->
    <!-- <string>-simple-mode</string> -->
    <!-- <string>-version</string> -->
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>StartCalendarInterval</key>
  <array>
    <dict>
      <key>Minute</key>
      <integer>0</integer>
    </dict>
    <dict>
      <key>Minute</key>
      <integer>30</integer>
    </dict>
  </array>
</dict>
</plist>

Localization

By default, Nudge supports the following locales:

Chinese
Danish
Dutch
English
French
German
Hindi
Korean
Japanese
Norwegian
Portuguese
Russian
Spanish
Swedish

If you need additional localizations, you will need the following:

Localization.strings for locale of the left side of Nudge and the Additional Machine Details view
Preferences file

The following example would add support for the French (fr) locale.

Note: There is already a French localization string to fill the rest of the UI

JSON

{
  "userInterface": {
    "updateElements": [
      {
        "_language": "es",
        "actionButtonText": "Actualizar dispositivo",
        "informationButtonText": "Más información",
        "mainContentHeader": "Su dispositivo se reiniciará durante esta actualización",
        "mainContentNote": "Notas importantes",
        "mainContentSubHeader": "Las actualizaciones pueden tardar unos 30 minutos en completarse",
        "mainContentText": "Se requiere un dispositivo completamente actualizado para garantizar que IT pueda proteger su dispositivo con precisión.\n\nSi no actualiza su dispositivo, es posible que pierda el acceso a algunos elementos necesarios para sus tareas diarias.\n\nPara comenzar la actualización, simplemente haga clic en el botón Actualizar dispositivo y siga los pasos proporcionados.",
        "mainHeader": "Tu dispositivo requiere una actualización de seguridad",
        "primaryQuitButtonText": "Más tarde",
        "secondaryQuitButtonText": "Entiendo",
        "subHeader": "Un recordatorio amistoso de su equipo de IT local"
      },
      {
        "_language": "fr",
        "actionButtonText": "Mettre à jour l'appareil",
        "informationButtonText": "Plus d'informations",
        "mainContentHeader": "Votre appareil redémarrera pendant cette mise à jour",
        "mainContentNote": "Notes Importantes",
        "mainContentSubHeader": "Les mises à jour peuvent prendre environ 30 minutes.",
        "mainContentText": "Un appareil entièrement à jour est nécessaire pour garantir que le service informatique puisse le protéger efficacement.\n\n Si vous ne mettez pas à jour votre appareil, vous risquez de perdre l'accès à certains systèmes nécessaires à vos tâches quotidiennes.\n\nPour commencer la mise à jour, cliquez simplement sur le bouton Mettre à Jour le Périphérique et suivez les étapes fournies.",
        "mainHeader": "Votre appareil nécessite une mise à jour de sécurité",
        "primaryQuitButtonText": "Plus tard",
        "secondaryQuitButtonText": "Je comprends",
        "subHeader": "Un rappel amical de votre équipe informatique locale"
      }
    ]
  }
}

Mobile Config

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>userInterface</key>
      <dict>
        <key>updateElements</key>
        <array>
          <dict>
            <key>_language</key>
            <string>es</string>
            <key>actionButtonText</key>
            <string>Actualizar dispositivo</string>
            <key>informationButtonText</key>
            <string>Más información</string>
            <key>mainContentHeader</key>
            <string>Su dispositivo se reiniciará durante esta actualización</string>
            <key>mainContentNote</key>
            <string>Notas importantes</string>
            <key>mainContentSubHeader</key>
            <string>Las actualizaciones pueden tardar unos 30 minutos en completarse</string>
            <key>mainContentText</key>
            <string>Se requiere un dispositivo completamente actualizado para garantizar que IT pueda proteger su dispositivo con precisión.

Si no actualiza su dispositivo, es posible que pierda el acceso a algunos elementos necesarios para sus tareas diarias.

Para comenzar la actualización, simplemente haga clic en el botón Actualizar dispositivo y siga los pasos proporcionados.</string>
            <key>mainHeader</key>
            <string>Tu dispositivo requiere una actualización de seguridad</string>
            <key>primaryQuitButtonText</key>
            <string>Más tarde</string>
            <key>secondaryQuitButtonText</key>
            <string>Entiendo</string>
            <key>subHeader</key>
            <string>Un recordatorio amistoso de su equipo de IT local</string>
          </dict>
          <dict>
            <key>_language</key>
            <string>fr</string>
            <key>actionButtonText</key>
            <string>Mettre à jour l'appareil</string>
            <key>informationButtonText</key>
            <string>Plus d'informations</string>
            <key>mainContentHeader</key>
            <string>Votre appareil redémarrera pendant cette mise à jour</string>
            <key>mainContentNote</key>
            <string>Notes Importantes</string>
            <key>mainContentSubHeader</key>
            <string>Les mises à jour peuvent prendre environ 30 minutes.</string>
            <key>mainContentText</key>
            <string>Un appareil entièrement à jour est nécessaire pour garantir que le service informatique puisse protéger votre appareil efficacement.

Si vous ne mettez pas à jour votre appareil, vous risquez de perdre l'accès à certains outils nécessaires à vos tâches quotidiennes.

Pour commencer la mise à jour, cliquez simplement sur le bouton Mettre à jour le périphérique et suivez les étapes fournies.</string>
            <key>mainHeader</key>
            <string>Votre appareil nécessite une mise à jour de sécurité</string>
            <key>primaryQuitButtonText</key>
            <string>Plus tard</string>
            <key>secondaryQuitButtonText</key>
            <string>Je comprends</string>
            <key>subHeader</key>
            <string>Un rappel amical de votre équipe informatique locale</string>
          </dict>
        </array>
      </dict>
    </dict>
  </array>
</dict>
</plist>

Configuration

Nudge offers significant customization, which might be overwhelming. But don't worry, you don't have to customize everything. 😄

For a full listing of the available preferences, please see the wiki. See also Over-configuring Nudge.

Small Example

In this example, Nudge will do the following:

Open up in simpleMode
Prompt users running any version of macOS Big Sur to upgrade to version 11.6 by 30-Sep-2021
The More Info button will open up to Apple's macOS Big Sur English release notes

JSON

{
  "userInterface": {
    "simpleMode": true
  },
  "osVersionRequirements": [
    {
      "aboutUpdateURL": "https://support.apple.com/en-us/HT211896",
      "requiredInstallationDate": "2021-09-30T00:00:00Z",
      "requiredMinimumOSVersion": "11.6",
      "targetedOSVersionsRule": "11"
    }
  ]
}

Mobile Config

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>osVersionRequirements</key>
      <array>
        <dict>
          <key>aboutUpdateURL</key>
          <string>https://support.apple.com/en-us/HT211896</string>
          <key>requiredInstallationDate</key>
          <date>2021-09-30T00:00:00Z</date>
          <key>requiredMinimumOSVersion</key>
          <string>11.6</string>
          <key>targetedOSVersionsRule</key>
          <string>11</string>
        </dict>
      </array>
      <key>userInterface</key>
      <dict>
        <key>simpleMode</key>
        <true/>
      </dict>
    </dict>
  </array>
</dict>
</plist>

Full Example

For full examples please see the Example Assets folder in this repo.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Home

OS support

Troubleshooting

Nudge compatibility with MDM workflows

Nudge Functionality Overview

Deploying Nudge

Command Line Arguments

Demo Mode

Simple Mode

JSON Support

Using the `-json-url` argument

Remote JSON

Local JSON

Setting the json-url in mobileconfig profile

Scheduling Nudge to run

Example LaunchAgent

Localization

JSON

Mobile Config

Configuration

Small Example

JSON

Mobile Config

Full Example

Further reading

Clone this wiki locally

Home

OS support

Troubleshooting

Nudge compatibility with MDM workflows

Nudge Functionality Overview

Deploying Nudge

Command Line Arguments

Demo Mode

Simple Mode

JSON Support

Using the -json-url argument

Remote JSON

Local JSON

Setting the json-url in mobileconfig profile

Scheduling Nudge to run

Example LaunchAgent

Localization

JSON

Mobile Config

Configuration

Small Example

JSON

Mobile Config

Full Example

Further reading

Clone this wiki locally

Using the `-json-url` argument