Invoke-CUAgentUpdate: Update an Agent

The Invoke-CUAgentUpdate cmdlet enables you to update ControlUp Agents on local machines to a specific version or the latest available GA version. This PowerShell cmdlet is part of our ControlUp Automation module and provides a streamlined method for keeping agents current without requiring manual intervention or complex deployment processes

Important Note

Only version 9.0 and higher can be used to download and install via this cmdlet.

Prerequisites

System Requirements

.NET Framework: Version 4.8 must be installed
Existing Agent: A ControlUp Agent must already be installed on the target machine (this cmdlet updates existing agents, it doesn't perform fresh installations)

Permissions

Administrative Rights: You must run PowerShell as Administrator to update the agent service
Registry Access: You need read/write access to:
- HKLM\SOFTWARE\Smart-X\ControlUp
- HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall
Service Control: You need permissions to stop and start Windows services

Network Requirements (for Online Updates)

Internet Access: You need HTTPS access to download agent packages from:
- https://downloads.controlup.com (primary CDN)
Proxy Configuration: If you use a proxy server, you must provide proxy settings through the -ProxySettings parameter

Module Requirements

ControlUp.Automation Module: You must have the ControlUp Automation PowerShell module installed
Module Import: You need to import the module before using the cmdlet:

Import-Module ControlUp.Automation

Syntax

 Invoke-CUAgentUpdate
      [[-ZipFilePath] <String>]
      [[-Version] <String>]
      [[-ProxySettings] <ProxySettings>]
      [<CommonParameters>]

Parameters

Parameter	Type	Required	Description
ZipFilePath	String	No	The absolute path to a local ControlUp Agent ZIP file. If you don't specify this parameter, the cmdlet downloads the agent from ControlUp's CDN. Use this parameter for offline updates or when you have pre-downloaded the agent package.
Version	String	No	The specific version number you want to update to (e.g., "9."). If you don't specify this parameter and no ZipFilePath is provided, the cmdlet downloads and installs the latest available version. This parameter is ignored when ZipFilePath is specified.
ProxySettings	ProxySettings	No	The proxy configuration object for environments that require proxy access to reach ControlUp's download servers. You need to create a ProxySettings object with server address, port, and optional credentials. This parameter only applies to online updates.

Parameter Notes

ZipFilePath and Version work independently:
- If you provide ZipFilePath, the Version parameter is ignored
- If you provide only Version, the cmdlet downloads that specific version
- If you provide neither, the cmdlet downloads the latest version
ProxySettings example:

$proxy = New-Object ControlUp.Automation.ProxySettings
$proxy.Server = "proxy.company.com"
$proxy.Port = 8080

Workflow and Examples

Basic Update Workflow

Open PowerShell as Administrator
Import the ControlUp Automation Module

Import-Module ControlUp.Automation

Run the Update Command

 Invoke-CUAgentUpdate

Verify the Update

# Check the result object
$result = Invoke-CUAgentUpdate
    if ($result.Success) {
      Write-Host "Agent updated successfully"
  } else {
      Write-Host "Update failed: $($result.Error)"
  }