Scripts

Upload or paste PowerShell (Windows) or Zsh/Bash (macOS) scripts and run them across your managed devices, once or on a schedule. Use them for maintenance, data collection, configuration changes or any custom automation.

WindowsmacOSOwners, Admins and MSP Technicians manage them; Read Only and MSP Read Only can view

In short

  • The shell decides the platform: PowerShell scripts run on Windows devices, Zsh and Bash scripts run on Macs.
  • Run a script once with Run now, or Schedule it to repeat on device groups. Both walk you through the steps and show a summary before anything runs.
  • A Days and time schedule runs on each device's own clock, and a device that is offline at that time is skipped, not caught up.
  • Collector scripts report custom field values on every Windows device instead of being scheduled.
  • Each run's status, exit code and output are in the script's Execution History, and you can export every run to CSV for an audit.

The Scripts page

Use the Windows and macOS tabs at the top of the page to switch between each platform's scripts. The Custom Fields tab is where you define the fields that collector scripts report.

Create a script

  1. Go to Scripts in the sidebar.

  2. Click New Script.

  3. Fill in the details below.

  4. Click Create Script.

Name
A descriptive name, for example “Cleanup temp files” or “Collect disk usage”.
Description
Optional notes about what the script does.
ShellPowerShell, Zsh or Bash
PowerShell runs on Windows; Zsh and Bash run on macOS. The shell determines which devices can run the script.
Script
Either Upload file (a .ps1 file for PowerShell, a .zsh or .sh file for Zsh, or a .bash or .sh file for Bash) or switch to Paste and paste the script body straight into the editor.
Install ContextSystem or User
Run as System (recommended for most tasks) or as the logged-in User.
Collect custom fields
Turn this on to make the script a collector (see Collector scripts).

Scripts only run on devices matching the shell's platform: PowerShell scripts run on Windows devices, Zsh and Bash scripts run on Macs. Schedule targeting filters device groups accordingly.

Edit a script

You don't need to delete and recreate a script to change it.

  1. Open the script and click Edit, in the page header or on the Script card.

    You can change the Name, Description and Install Context, and the script body, either by editing it in place or with Replace from file to load a new file into the editor.
  2. Click Save Changes.

    Schedules, collector settings and run history are kept, and devices run the new version on their next scheduled run (or next collector run). Jobs already claimed by a device finish with the version they started with.

The Script card also shows the current body with a Copy button, so you can pull the script into your own editor.

The shell is fixed

The shell cannot be changed after creation, because it fixes which platform's devices the script targets. To move a script to the other platform, create a new one.

Collector scripts

A collector is a script that reports values for custom fields instead of being scheduled against groups.

  1. Turn on Collect custom fields when creating a script.

    Or open an existing script and enable it in the Custom Field Collector card.
  2. Choose how often it runs, from hourly to weekly.

  • Collectors run on every Windows device, starting at the next check-in and then on the chosen cadence. They only run while the device is otherwise idle, so they never compete with an app install.
  • They report values with Set-PckgrField -Name <key> -Value <value>. Each key must match a field defined on the Custom Fields tab of the Scripts page.
  • Collectors are available for PowerShell (Windows) scripts only for now; the toggle is not shown for Zsh/Bash scripts.
  • A collector's page shows a Collector Runs card instead of the schedule and execution history. It lists every device's last run, status, exit code, how many fields were set, and any problem such as an unknown key or a value of the wrong type.

See Custom Fields for a full walkthrough and example scripts.

Run or schedule a script

Open a script from the list and use the Run and schedule card on its page. Collector scripts have no such card; they run on every device automatically. A script that isn't running anywhere yet offers two buttons:

Run now
Runs the script once on the groups you choose. Each device runs it at its next check-in.
Schedule
Sets the script to repeat on the groups you choose.

Both open a short set of steps. Click Next to move on and Back to change an earlier step; nothing is saved until the last step.

Run a script once

  1. Devices: tick the groups that should run the script.

    Use the search bar to find groups, or click Select all to target everything. Optionally choose groups under Exclude groups; their devices are skipped even though they are in a target group.
  2. Review: check the summary, then click Run now.

    The summary lists the groups and roughly how many devices they hold.

PowerShell scripts run only on the Windows devices in the groups, and Zsh and Bash scripts only on the Macs; the others are skipped.

Set up a recurring schedule

  1. When: choose how it repeats.

    Repeat every
    Every N days (up to 365) or every N weeks (up to 52), for example every 2 days. The first run starts as soon as you save.
    Days and timePowerShell scripts only
    Every week on the days you tick, at a time on each device’s own clock, for example every Thursday at 18:00.
  2. Devices: tick the target groups and any groups to exclude, as for a one-off run.

  3. Review: check the summary, then click Create schedule.

    The summary spells the schedule out in plain words, for example "Every week on Mon, Wed, Fri at 18:00 device time", with the groups it reaches.

Manage a schedule or a run

The card shows what the script is set to do, its state and, for a schedule, the Next run and Last run.

  • Edit schedule opens the same steps with the current settings filled in. Save changes stays off until you change something.
  • Pause and Resume stop and restart a schedule without losing its settings.
  • Delete schedule removes it. The run history is kept.
  • After a one-off run, Run again runs it once more on the same groups, or on others you pick, and Schedule instead turns it into a repeating schedule.

A script holds one schedule at a time, and a one-off run counts as one. Running a script that has a recurring schedule therefore replaces that schedule; the review step warns you before it does, so you can set the schedule up again afterwards.

Days and time schedules (device local time)

A Days and time schedule runs at the chosen time in each device's own time zone, so "Thursday at 18:00" means 6 pm in Sydney for a Sydney laptop and 6 pm in London for a London one. Daylight saving is taken into account.

The review step and the card spell the schedule out in plain words, for example "Every week on Mon, Wed, Fri at 18:00 device time".

  • A device that has not yet reported its time zone is skipped, with that reason shown in the run history.
  • Devices that have not checked in for more than 30 days are left out quietly and get no run history row for the slot.
  • Days and time is available for PowerShell (Windows) scripts only; Zsh and Bash scripts offer Repeat every and one-off runs.

Offline devices miss the run

A device must be online at that time. One that is offline is skipped for that day and does not catch up later; it appears as Skipped in the run history with the reason. A device that comes online but doesn't pick up the run within 30 minutes is also marked Skipped, so a script never runs hours after its slot.

View script runs

Results appear in the Execution History card on the script's page. At the top it shows counts of total, succeeded, failed and in-progress runs, with the overall success rate.

  • Click Refresh to load the latest results.
  • Click a row, or its arrow, to expand it and see the script's output for that run.
  • Use the status filter and the device search to find specific results.
  • Results are paginated; use Previous and Next to browse pages.
Device
Target device hostname.
Status
Pending, In Progress, Succeeded, Failed, Cancelled, Skipped, Deferred, or Abandoned.
Exit Code
Exit code from the script.
Started and Completed
When execution began and finished.
Duration
How long the run took.
Logs
Download the log bundle the agent uploaded for that run (script output and the run’s result record).

Export run history to CSV

The export gives you every run in a period, not only each device's latest, with the device, its user, the status and the script's output. Use it as evidence for a client audit.

  1. Choose what to export

    For one script, click Export CSV on its Execution History card; the card's status filter and device search apply to the file too. For every script in the tenant, click Export run history at the top of the Scripts page.
  2. Pick the period

    Choose a Date range, from the last 7 days to all time, or a Custom range. Then click Export CSV.
Created, Started, Completed (UTC)
When the run was queued, began and finished, in UTC.
Script, Device, Platform
Which script ran where.
Last signed-in user (now)
The device’s last signed-in user today. Pckgr does not record who was signed in at the time of each run.
Runs as
System, or the signed-in user, from the script’s Install Context.
Status, Exit code, Attempt
The run’s outcome and which attempt it was.
Error, Output (STDOUT), Error output (STDERR)
What the script printed. A value too long for one spreadsheet cell is cut and marked as truncated; the full output stays on the script’s page.
Run ID, Device ID
Identifiers to match a row to the portal.

Note

An export holds at most 50,000 runs. For more, choose a shorter range or a filter. Each export is recorded in the Audit Log.

Delete scripts

Click the trash icon next to a script in the list (or on the script's page) and confirm. This deletes the script along with all its schedules and job history.

To delete several at once, select them with the checkboxes, then click Delete in the action bar.

Tips

  • Test scripts on a small pilot group before scheduling them across your entire fleet.
  • Use System context for scripts that need administrator privileges.
  • Use User context for scripts that need to access the logged-in user's profile or settings.
  • Check the Execution History card after scheduling to verify scripts are executing successfully.
  • For recurring scripts, keep an eye on the success rate and failed count to catch issues early.