Device Action: Run Script

The Run Script action allows admins to execute shell scripts on macOS devices remotely. Scripts are managed in a script library within SimpleMDM and run on devices through the SimpleMDM Agent. Script output is captured and reported back to SimpleMDM, and can optionally be saved to a custom attribute on the device.

Supported platforms

The Run Script action is available for enrolled macOS devices. Supervision is not required. This action is not available for iOS, iPadOS, or tvOS devices.

How to run a script from a device

1. In SimpleMDM, navigate to the device's Device Details page.
2. Click the "Actions" menu.
3. Select "Run Script".
4. This opens the script job creation page. Select a script from the dropdown, choose target devices, and submit the job.

Script library

Scripts are created and managed in the Scripts section of SimpleMDM before they can be run on devices. Each script has a name and content, and must begin with a shebang line (e.g., #!/bin/bash). Scripts can also be uploaded as files.

Scripts support variable substitution — when enabled, placeholders like {{variable}} in the script content are replaced with device-specific values before execution.

Script jobs

When you run a script, SimpleMDM creates a script job that tracks execution across all targeted devices. Jobs can target individual devices or assignment groups.

Job options

• Script: The script to run, selected from the script library.
• Target devices: Individual devices or assignment groups to run the script on.
• Custom attribute: Optionally map the script's output to a custom attribute on each device. A regex pattern can be used to extract a specific value from the output.
• Expiration: Optionally set a time after which the script job expires. Devices that haven't fetched the script by the expiration time will be marked as expired.

Job status tracking

Each device in a script job has its own status:

• Pending: Waiting for the device to fetch the script.
• Fetched: The device has retrieved the script but hasn't reported results yet.
• Completed: The script executed successfully (exit code 0).
• Error: The script execution failed (non-zero exit code).
• Expired: The device didn't fetch the script before the job's expiration time.
• Cancelled: The admin cancelled the pending command.

Script output is captured (up to 5,000 characters) and viewable in the script job details.

Scheduling scripts

Script jobs can be scheduled to run once at a specific time or on a recurring schedule, allowing admins to automate routine maintenance tasks or data collection.

Notes