Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,9 +118,9 @@ The `release` artifact is kept for 30 days; re-runs need it.
writes `FunctionsToExport` from the `Public/` file names (the source manifest says `'*'`). The source `.psm1` is only
for development: it dot-sources the same files and is **not** used by the build, so module-level code belongs in
`source/prefix.ps1`. That file holds the TLS setup and the shared constants: `$script:CWCSessionType`,
`$script:CWCSessionEventType` (live-verified numbers), `$script:CWCDefaultSessionGroup`, `$script:CWCProcessType`,
`$script:CWCAllSessionPermissions`, `$script:InternalUserSource` and the Remote Workforce and RESTful API Manager
extension IDs.
`$script:CWCSessionEventType` and `$script:CWCToolboxOperation` (live-verified numbers),
`$script:CWCDefaultSessionGroup`, `$script:CWCProcessType`, `$script:CWCAllSessionPermissions`,
`$script:InternalUserSource` and the Remote Workforce and RESTful API Manager extension IDs.
- **Requests**: every public function calls `Private/Invoke-CWCServiceMethod.ps1`. It builds the endpoint
(`-Service` → `Services/<Service>.ashx/<Method>`, `-RestApi` / `-ExtensionID` →
`App_Extensions/<id>/Service.ashx/<Method>`) and sends the arguments as a **positional JSON array** matching the
Expand All @@ -130,8 +130,8 @@ The `release` artifact is kept for 30 days; re-runs need it.
commands/notes/deletes never repeat. Session events go through `Private/Add-CWCSessionEvent.ps1`. Transport
errors carry an ErrorId (`CWC.NotConnected`, `CWC.AuthModeMismatch`, `CWC.Http<status>`, `CWC.NoResponse`); an MFA
login adds `CWC.MfaRequired`, `CWC.MfaCodeRejected`, `CWC.LoginFailed` and `CWC.LoginThrottled`. A failed sign-in
without MFA or with `-ApiSecret` has no `CWC.*` ErrorId. `-Sensitive` redacts the body from verbose and debug
output.
without MFA or with `-ApiSecret` has no `CWC.*` ErrorId. `-Sensitive` keeps the body (a secret, or bulk content
such as an uploaded file) out of verbose and debug output.
- **Transport**: `Private/Invoke-CWCWebRequest.ps1` checks that a connection exists, **blocks calls that don't match
the auth mode** (API-secret connections may only reach the RESTful API Manager), adds auth headers, handles PS 5
vs 6+ error shapes, and returns parsed JSON.
Expand All @@ -140,7 +140,8 @@ The `release` artifact is kept for 30 days; re-runs need it.
and `IdentityHash`. ApiSecret mode keeps the secret as a SecureString (`ApiSecret`) and sends `CTRLAuthHeader`.
Connect-CWC validates the login with a test call. If that call fails, the previous connection is restored only
when this was a `-Force` refresh of the same server, method and identity; a failed switch to anything else leaves
the module disconnected.
the module disconnected. While a login is being made or validated the connection carries `LoggingIn`, which
stops the transport from adding its "the login may be stale, reconnect" hints to permission errors.

## Adding New Functions

Expand Down
23 changes: 20 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [0.5.0] - 2026-11-10

Version numbers now have three parts (`0.5.0`). The previous release was 0.4.0.0, which had 21 commands; this
release has 32.
release has 35.

### Breaking changes

- `Remove-CWCSession`, `Remove-CWCSessionNote` and `Remove-CWCHostFromSession` ask for confirmation by default.
- `Remove-CWCSession`, `Remove-CWCSessionNote`, `Remove-CWCHostFromSession` and the new `Remove-CWCToolboxItem`
ask for confirmation by default, and so does `Send-CWCToolboxItem` with the new `-Elevated` or `-Silent`.
Unattended scripts must add `-Confirm:$false`. Without it, a session started with `-NonInteractive` fails at
the prompt and removes nothing; other unattended hosts may wait at the prompt or take its default answer (Yes)
the prompt and does nothing; other unattended hosts may wait at the prompt or take its default answer (Yes)
- `Connect-CWC` without `-Force` switches to a different server, sign-in method or user instead of keeping the
old connection
- `Get-CWCLastContact` returns an error when no connection event is found, instead of the current time
Expand Down Expand Up @@ -75,6 +76,20 @@ Details are in the sections below.
(`InitiatedJoin`). `-UrlOnly` returns the URL instead (for macOS/Linux or custom launchers), using a
5-minute delegated token when the role allows it. The token is never written to any output stream.
Credentials connections only; launching is Windows only
- `Get-CWCToolbox` lists the Toolbox contents (`PageService.GetToolbox`) as one object per folder and file
with its path; `-Raw` returns the server's tree. Credentials connections only
- `Add-CWCToolboxItem` uploads a file to the shared Toolbox in chunks, or creates a Toolbox folder
(`ToolboxService.WriteToolboxFileContent`; needs the ManageSharedToolbox permission; credentials
connections only). Accepts files from the pipeline. It replaces an item of the same name. If the upload
fails or is stopped part way, the incomplete item is deleted so it cannot be run
- `Remove-CWCToolboxItem` deletes a Toolbox file or folder (`ToolboxService.ProcessToolboxOperation`, Delete);
asks for confirmation by default. Credentials connections only. It checks the Toolbox afterwards and
returns `CWC.ToolboxItemNotRemoved` when the item is still there: the server answers success even when it
could not delete a file it has open
- `Send-CWCToolboxItem -Elevated` runs the item with administrative privileges (QueuedElevatedTool 101) and
`-Silent` runs it elevated and silently (QueuedSilentElevatedTool 117). Both ask for confirmation unless
`-Confirm:$false` is passed; credentials connections only. Use `-Silent` for unattended runs: an
`-Elevated` item did not start on a machine with no host connected

### Deprecated

Expand Down Expand Up @@ -114,6 +129,8 @@ Details are in the sections below.
- `Invoke-CWCCommand` waits 1, 2, 3 … up to 5 seconds between polls of the rate-limited session details
- `Enter-CWCSession` takes `-Name` from the pipeline (e.g. from `Get-CWCSession`) and then skips its
session lookup
- A 401 "Needs permission" on a credentials or MFA connection suggests `Connect-CWC -Force` (#31): the server
stops honouring an older login's management permissions while ordinary calls keep working

### Fixed

Expand Down
9 changes: 9 additions & 0 deletions ConnectWiseControlAPI_Functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ Creates the security role required by the Remote Workforce extension.
### [Add-CWCSessionNote](Docs/Add-CWCSessionNote.md)
Adds a note to a session.

### [Add-CWCToolboxItem](Docs/Add-CWCToolboxItem.md)
Uploads a file to the shared ScreenConnect Toolbox, or creates a Toolbox folder.

### [Connect-CWC](Docs/Connect-CWC.md)
Connects to a ConnectWise ScreenConnect server.

Expand Down Expand Up @@ -57,6 +60,9 @@ Returns the details of a session: session info, events, connections and guest sc
### [Get-CWCSessionGroup](Docs/Get-CWCSessionGroup.md)
Returns all session groups.

### [Get-CWCToolbox](Docs/Get-CWCToolbox.md)
Lists the contents of the ScreenConnect Toolbox.

### [Initialize-CWCRemoteWorkforceSessionGroup](Docs/Initialize-CWCRemoteWorkforceSessionGroup.md)
Creates or repairs the session group used by the Remote Workforce extension.

Expand Down Expand Up @@ -90,6 +96,9 @@ Deletes sessions, optionally uninstalling the Access client first.
### [Remove-CWCSessionNote](Docs/Remove-CWCSessionNote.md)
Removes notes from a session.

### [Remove-CWCToolboxItem](Docs/Remove-CWCToolboxItem.md)
Deletes a file or folder from the shared ScreenConnect Toolbox.

### [Remove-CWCUser](Docs/Remove-CWCUser.md)
Deletes an internal user.

Expand Down
200 changes: 200 additions & 0 deletions Docs/Add-CWCToolboxItem.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
---
external help file: ConnectWiseControlAPI-help.xml
Module Name: ConnectWiseControlAPI
online version: https://github.com/christaylorcodes/ConnectWiseControlAPI
schema: 2.0.0
---

# Add-CWCToolboxItem

## SYNOPSIS
Uploads a file to the shared ScreenConnect Toolbox, or creates a Toolbox folder.

## SYNTAX

### File (Default)
```
Add-CWCToolboxItem -Path <String> [-Name <String>] [-ChunkSize <Int32>]
[-WhatIf] [-Confirm] [<CommonParameters>]
```

### Directory
```
Add-CWCToolboxItem -Name <String> [-Directory] [-WhatIf] [-Confirm]
[<CommonParameters>]
```

## DESCRIPTION
Calls ToolboxService.WriteToolboxFileContent.
The file is sent in chunks: the first chunk creates
the item, replacing an item of the same name, and the rest are appended.
The user needs the
ManageSharedToolbox permission.

When -Name contains a folder, that folder is created first.

The first chunk replaces an existing item at once.
If a later chunk fails, or the upload is
stopped with Ctrl+C, the incomplete item is deleted so it cannot be run; an item it was replacing
is gone.
Run the command again to upload it.

Several files can be piped in; each keeps its own file name.

Run the uploaded item on a session with Send-CWCToolboxItem.

## EXAMPLES

### EXAMPLE 1
```
Add-CWCToolboxItem -Path .\Cleanup.cmd
```

Uploads Cleanup.cmd to the top level of the Toolbox.

### EXAMPLE 2
```
Add-CWCToolboxItem -Path .\Cleanup.cmd -Name 'Scripts/Cleanup.cmd'
```

Creates the Scripts folder if needed and uploads the file into it.

### EXAMPLE 3
```
Get-ChildItem .\Tools\*.exe | Add-CWCToolboxItem
```

### EXAMPLE 4
```
Add-CWCToolboxItem -Directory -Name 'Scripts'
```

## PARAMETERS

### -Path
Local file to upload.
Accepts paths and Get-Item / Get-ChildItem output from the pipeline.

```yaml
Type: String
Parameter Sets: File
Aliases: FullName

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
```

### -Name
Path of the item inside the Toolbox, e.g.
'Cleanup.cmd' or 'Scripts/Cleanup.cmd'.
Defaults to the
file name of -Path.
It names one item, so it cannot be used when several files are piped in.

```yaml
Type: String
Parameter Sets: File
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
```

```yaml
Type: String
Parameter Sets: Directory
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
```

### -Directory
Create the Toolbox folder -Name instead of uploading a file.

```yaml
Type: SwitchParameter
Parameter Sets: Directory
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```

### -ChunkSize
Bytes of the file sent per request, up to 4194304 (4 MB).
Defaults to 524288 (512 KB).
Lower it
if the server rejects the request as too large.

```yaml
Type: Int32
Parameter Sets: File
Aliases:

Required: False
Position: Named
Default value: 524288
Accept pipeline input: False
Accept wildcard characters: False
```

### -WhatIf
Shows what would happen if the cmdlet runs.
The cmdlet is not run.

```yaml
Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
```

### -Confirm
Prompts you for confirmation before running the cmdlet.

```yaml
Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
```


### CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS

## OUTPUTS

## NOTES
Requires Connect-CWC -Credentials (the RESTful API Manager extension cannot write to the Toolbox).
Author: Chris Taylor

## RELATED LINKS

[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI)

77 changes: 77 additions & 0 deletions Docs/Get-CWCToolbox.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
external help file: ConnectWiseControlAPI-help.xml
Module Name: ConnectWiseControlAPI
online version: https://github.com/christaylorcodes/ConnectWiseControlAPI
schema: 2.0.0
---

# Get-CWCToolbox

## SYNOPSIS
Lists the contents of the ScreenConnect Toolbox.

## SYNTAX

```
Get-CWCToolbox [-Raw] [<CommonParameters>]
```

## DESCRIPTION
Calls PageService.GetToolbox, the same call the host client makes to list Toolbox items.
Any
signed-in user can call it.

The server returns a tree: a root folder whose Items hold folders and files, each with a Name,
Attributes (1 for a folder, 0 for a file), a base64 icon (Image) and its own Items.
By default the tree is
flattened to one object per folder and file, with its Path inside the Toolbox and without the icon.

Use it to find an item for Send-CWCToolboxItem, or to check an upload made with Add-CWCToolboxItem.

## EXAMPLES

### EXAMPLE 1
```
Get-CWCToolbox
```

Lists every folder and file in the Toolbox.

### EXAMPLE 2
```
Get-CWCToolbox | Where-Object { -not $_.IsFolder -and $_.Path -like 'Scripts/*' }
```

## PARAMETERS

### -Raw
Return the tree as the server sends it, including the icons.

```yaml
Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
```


### CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS

## OUTPUTS

## NOTES
Requires Connect-CWC -Credentials (the RESTful API Manager extension cannot list the Toolbox).
Author: Chris Taylor

## RELATED LINKS

[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI)

Loading
Loading