Running and scheduling scripts

Run a script#

You can start a run from the library (Run a script), from a script's page (Run, or press R), from the Runs tab, or from a device (Run a script... in its Toolbox, Run script in its ... menu or its Scripts section).

1. Choose the Script. Its description, language, who it runs as, time limit and version appear beneath it.
2. Fill in any parameters it asks for.
3. Choose where it runs:
   • Devices: pick one or more devices.
   • Device group: every device in a group.
   • Customer: every device at a customer.
   • Everywhere: every device.
4. Choose when: Now, or At a time and pick the time (your local time).
5. Click Run.

Devices without the agent, or on an operating system the script does not support, are listed as skipped, with the reason. Opened from a device on the Lite agent, the dialog lists every script but only those marked Works on the Lite agent can be chosen. For a run at a time, devices that are offline then run it when they are next online, within a day. A device that is asleep runs it once it fully wakes; see Sleeping devices and volumes.

If someone left a warning on a device the run reaches, the dialog shows it, and a Stop warning must be ticked as read before the run goes ahead.

Run a command#

For a one-off, you do not need a library script. Choose Run a command from a device's ... menu (or Cmd+K):

1. Pick the Language, Run as (System or The signed-in user) and Stops after.
2. Type the Command, and optionally say Why (the approver sees it when commands need approval).
3. Click Run.

The command is not saved to the library, but the run keeps it with its output, so it has the same run page, cancel, Run again and history as any script. Save to library on the run copies it into a new script's draft. Running commands needs the Run commands permission, which administrators have by default.

Second person approval#

Some runs should never happen on one person's say-so. A run waits for a second person when the script is marked Runs need approval, or when a rule under Second person approval in Settings > Device management matches it:

• Running as system on a server needs approval.
• Running on more devices than this needs approval (0 switches it off).
• Scripts in these categories need approval, for example Destructive or Security.
• Commands typed on a device need approval.
• Every run needs approval, which you can set for one sensitive customer in the customer's settings.

The run is made straight away with its devices Waiting for approval, and nothing is sent to any device. Someone with the Scripts approve permission, never whoever started it, is asked through Approvals, seeing the script, its version and fingerprint, the values (secrets and credentials by name only), the devices and when it runs. Approved, the run starts; turned down, withdrawn or expired, it is cancelled with the reason. Automation runs and fixes the AI proposes go through the same check.

A schedule the rules catch is approved once when it is saved, and again whenever what it runs changes: a new published version, its devices or its values. Until then its occurrences are skipped and say why.

Follow a run#

Devices > Scripts, the Runs tab, lists every run, newest first, with its status, the script and version, where it ran, how many devices succeeded and failed, and who or which schedule or automation started it. Filter by Status, Script, From or When.

Click a run to open it.

• The counters show Devices, Succeeded, Failed, Running, Waiting and Cancelled or skipped.
• The Devices list shows each device with its customer, how long it took and its result. Press J and K to move between devices.
• The right-hand pane shows the chosen device's output, its exit code, how long it took, the size of the output and when it started. Use the copy button to copy the output.
• What ran records the script, version, language, time limit, where the run came from and the SHA-256 of the exact code.
• Values shows the parameters it was given (secrets are never shown).

Output streams in live while a script runs. A running script can be cancelled, which stops it and everything it started on the device.

Run again repeats the run with the same script and values.

Comparing and exporting results#

On a run with many devices, the output is grouped: devices that said exactly the same are counted together ("31 devices said X, 2 said Y"), so the odd one out stands out. Compare output puts two devices of the run side by side, or one device against Its previous run of the same script, with lines only in the first in red and lines only in the second in green. Download every device as CSV exports the device, customer, status, exit code, duration and the end of each device's output.

Note: Each device runs at most four scripts at once; a fifth waits its turn. If the agent restarts while a script is running, that run is reported as failed with the reason.

Schedule a script#

Schedules run a script on their own, once or every day, week or month, at a local time.

1. Go to Devices > Scripts, open the Schedules tab and click New schedule, or choose Schedule it on a script.
2. Choose the Script and, optionally, a Name (leave it empty to use the script's name).
3. Choose where it runs: Devices, Device group, Customer or Everywhere.
4. Choose Once, Daily, Weekly (tick the days) or Monthly, then the Time and Time zone. Leave the time zone on Where the devices are to use each site's time zone when the devices share one, else the customer's, else the one in Settings > Regional.
5. Optionally, under When a run fails, choose people, roles or teams to tell when any device fails, and Raise an alert when more than a number of devices fail.
6. Click Schedule it.

A schedule runs on the devices as they are at each occurrence, so new devices that join a group or a customer are included automatically.

Manage schedules#

The Schedules tab lists each schedule with the script, where it runs, when, the next run and how the last run went.

• Use the switch in the On column to pause a schedule or resume it.
• Click a schedule to change it.
• Each run a schedule starts appears on the Runs tab with the schedule's name in the From column.

A schedule's failure alert clears by itself when a later run is back within the number. Automation can also act when a run finishes, with the trigger A script run finished. See Building a rule. Automation rules are in Settings > Automation rules.