List of Functions • Examples • Install • Contribute • Submit a Bug • Request a Feature
This module makes it easy to leverage PowerShell to automate tasks in ScreenConnect.
ConnectWise renamed Control back to ScreenConnect. The module keeps its name and its CWC command names, so
scripts don't need renaming. Version 0.5.0 does change some behaviour: see Upgrading from 0.4.
The module can be easily installed from the PowerShellGallery
Install-Module 'ConnectWiseControlAPI'If you are having issues accessing the PowerShell Gallery check out my repair script
0.5.0 changes some behaviour. Check your scripts before you update:
Remove-CWCSession,Remove-CWCSessionNote,Remove-CWCHostFromSessionandRemove-CWCToolboxItemask for confirmation by default, and so doesSend-CWCToolboxItemwith-Elevatedor-Silent. Unattended scripts must add-Confirm:$false. Without it, a session started with-NonInteractivefails at the prompt and does nothing; other unattended hosts may wait at the prompt or take its default answer (Yes).Connect-CWCwithout-Forcenow switches to a different server, sign-in method or user. Before, it kept the old connection.Get-CWCLastContactreturns an error when it finds no connection event. Before, it returned the current time.Get-CWCAuditLogcovers the last 24 hours unless you pass-StartDateand-EndDate.Get-CWCSession -Type Supportand-Type Meetingwithout-Groupread theAll SessionsandAll Meetingsgroups. Before, they readAll Machines, which holds Access sessions.- A read or "set to value" update that gets HTTP 500 is retried 3 times (after 2, 4 and 8 seconds) before it fails. 0.4 failed at once. Commands, wakes, deletes and user creation are never retried.
The full list is in the changelog.
-
Requires your ScreenConnect server to use https.
-
One of three authentication methods:
-
Credentials (
Connect-CWC -Credentials): an account without MFA. Use a complex username and password. All functions exceptFind-CWCSessionare available, limited by the account's permissions. -
Credentials with MFA (
Connect-CWC -Credentialsplus-Mfa,-OneTimeCodeor-TotpSecret): an account that requires MFA, signed in the way the web page does. Same functions as credentials.-Mfaasks for the code at the console (authenticator app, email or SMS).-TotpSecretcomputes the authenticator-app code for unattended scripts from the account's TOTP secret (ms:...or Base32); keep that secret in a secret store, and note that storing it next to the password makes MFA a single factor. The login expires on the server; runConnect-CWCagain before each batch of work (a still-valid login is reused with one check call).Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) -Mfa # Unattended, with Microsoft.PowerShell.SecretManagement Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Secret 'CWC-Login') -TotpSecret (Get-Secret 'CWC-TOTP')
-
API secret (
Connect-CWC -ApiSecret): install the RESTful API Manager extension and set itsRESTfulAuthenticationSecretsetting to a long random value. Works when every account requires MFA. Available functions:Find-CWCSession,New-CWCSession,Get-CWCSessionDetail,Update-CWCSessionName,Invoke-CWCCommand(queues the command but does not return its output),Add-CWCSessionNote,Send-CWCSessionMessage,Send-CWCToolboxItem. The secret bypasses ScreenConnect's role permissions and acts on every session, so protect it like an administrator password. If the extension'sRESTfulAllowedOriginsetting is set, pass a matching-Origin.$Secret = Read-Host -AsSecureString -Prompt 'RESTful API secret' Connect-CWC -Server 'screenconnect.example.com' -ApiSecret $Secret Find-CWCSession -Filter "Name LIKE 'DESKTOP-*'"
-
In-depth tutorials on christaylor.codes:
- Introducing ConnectWiseControlAPI - Module overview and key features
- Getting Started with ConnectWiseControlAPI - Authentication, setup, and first commands
- Cleaning Duplicate Control Sessions - Practical session management automation
- Building PowerShell API Wrappers - Design patterns behind the module
If you use this project please give it a star and follow so you can get updated when new features are released. This also lets me know what projects are getting used and what ones I should dedicate more time to. If you want to get more involved please see the contributing page. Projects need all kinds of help even if you don't know how to code.
If you cant take time to contribute maybe you would like to help another way.
It takes time to maintain this project. Does the time spent on this module help you do cool things? Is that time worth a beer or two?
Donations allow me to spend more time on this project and implement your feature requests.
