/scripts

name: "ConnectWise Automate Scripts"
description: >
  ConnectWise Automate script management: script types (PowerShell, batch,
  VBScript, Shell), script folders, script execution on computers, parameter
  handling and validation, execution status polling, and result/history
  retrieval.
when_to_use: >-
  When listing, executing, passing parameters, and retrieving results. Use when: automate script,
  automate powershell, automate execute, run script, script execution, script parameters, script
  results, script history, labtech script, or automate automation.

ConnectWise Automate Script Management

Overview

Scripts in ConnectWise Automate are automation routines that run on managed endpoints. They can be PowerShell, batch files, VBScript, or Automate's native scripting language. This skill covers script listing, execution, parameters, and result retrieval.

Anti-triggers

• **Shell commands in this session** — "run the script" here means

dispatching a stored Automate script to a customer's managed endpoint, never executing anything on the local machine.

• **What fires a script automatically** — the threshold or condition that

triggers it is a monitor definition; use `connectwise-automate-monitors`.

• **Which machines to target** — resolving hostnames, checking online

status and building the target list is `connectwise-automate-computers`.

• **Another RMM's job runner** — Datto RMM quickjobs and NinjaOne script

runs share this vocabulary; use `datto-rmm-jobs`.

MCP Tools

| Tool | Tier | Purpose | |------|------|---------| | `cwautomate_scripts_list` | read | Script catalog | | `cwautomate_scripts_get` | read | One script's metadata and parameters | | `cwautomate_scripts_running` | read | Scripts currently running on a computer (`computer_id`) | | `cwautomate_scripts_history` | read | Completed runs on a computer with pass/fail state and Automate's diagnostic message (`computer_id`) | | `cwautomate_computers_run_script` | admin | Run one script on one computer; waits up to 20 seconds | | `cwautomate_scripts_execute` | admin | Run one script on several computers and poll its history for each outcome |

Automate has no synchronous script run. A run that outlasts the wait returns `completed: false` and **keeps running**: read `cwautomate_scripts_history` (and `cwautomate_scripts_running`) for the result instead of launching it again. Check `cwautomate_scripts_running` before a launch so a script already in progress is not queued twice.

Key Concepts

Script Types

| Type | Extension | Use Case | |------|-----------|----------| | **Automate Script** | Internal | Built-in functions, agent commands | | **PowerShell** | .ps1 | Windows automation, complex logic | | **Batch** | .bat/.cmd | Simple Windows tasks | | **VBScript** | .vbs | Legacy Windows automation | | **Shell** | .sh | Linux/macOS automation |

Script Execution Modes

| Mode | Description | Use Case | |------|-------------|----------| | **Immediate** | Run now on target | Ad-hoc tasks | | **Scheduled** | Run at specific time | Maintenance | | **On Event** | Triggered by alert/monitor | Automated remediation | | **Login/Logout** | Run at user session events | User setup |

Script Status

| Status | Description | |--------|-------------| | `Running` | Currently executing | | `Completed` | Finished successfully | | `Failed` | Execution error | | `Pending` | Queued for execution | | `Timeout` | Exceeded time limit | | `Cancelled` | Manually stopped |

Field Reference

See [references/fields.md](references/fields.md) for the complete `Script`, `ScriptParameter`, and `ScriptExecution` field reference (TypeScript interfaces).

API Patterns

See [references/api.md](references/api.md) for the complete endpoint catalog: listing/searching scripts, executing on one or many computers, polling execution status, and retrieving execution history — with full request/response JSON examples.

Workflows

Find Script by Name

async function findScriptByName(client, name) {
  const scripts = await client.request(
    `/Scripts?condition=Name contains '${name}'&pageSize=50`
  );

  if (scripts.length === 0) {
    return { found: false, suggestions: [] };
  }

  if (scripts.length === 1) {
    return { found: true, script: scripts[0] };
  }

  return {
    found: false,
    ambiguous: true,
    suggestions: scripts.map(s => ({
      name: s.Name,
      id: s.ScriptID,
      folder: s.FolderPath,
      description: s.Description
    }))
  };
}

Execute Script and Wait for Completion

async function runScriptAndWait(client, computerId, scriptId, params = {}, options = {}) {
  const { timeoutMs = 300000, pollIntervalMs = 5000 } = options;

  // Start the script
  const execution = await client.request(
    `/Computers/${computerId}/Scripts/${scriptId}/Execute`,
    {
      method: 'POST',
      body: JSON.stringify({ Parameters: params })
    }
  );

  const startTime = Date.now();

  // Poll for completion
  while (true) {
    const status = await client.request(
      `/Scripts/Executions/${execution.ExecutionID}`
    );

    if (['Completed', 'Failed', 'Timeout', 'Cancelled'].includes(status.Status)) {
      return {
        success: status.Status === 'Completed' && status.ExitCode === 0,
        execution: status
      };
    }

    // Check timeout
    if (Date.now() - startTime > timeoutMs) {
      return {
        success: false,
        execution: status,
        error: 'Polling timeout exceeded'
      };
    }

    await sleep(pollIntervalMs);
  }
}

Validate Script Parameters

async function validateScriptParams(client, scriptId, providedParams) {
  const script = await client.request(`/Scripts/${scriptId}`);
  const errors = [];
  const warnings = [];

  for (const param of script.Parameters || []) {
    const value = providedParams[param.Name];

    // Check required parameters
    if (param.Required && !value && !param.DefaultV