PowerShell module reference

CloudSmithPS is the PowerShell module for managing CloudSmith from the command line. Install it from the PowerShell Gallery:

Install-Module -Name CloudSmithPS -Scope CurrentUser
Import-Module CloudSmithPS

All cmdlets require an active session established with Connect-CloudSmith.

Connect-CloudSmith

Authenticate to a CloudSmith instance and store the session for use by subsequent cmdlets.

Syntax

Connect-CloudSmith
    -Url <string>
    -Username <string>
    [-Password <SecureString>]
    [-Credential <PSCredential>]

Parameters

Examples

# Interactive prompt
Connect-CloudSmith -Url 'https://cloudsmith.contoso.com' -Username 'admin'

# Non-interactive with SecureString password
$pw = ConvertTo-SecureString 'your-password' -AsPlainText -Force
Connect-CloudSmith -Url 'https://cloudsmith.contoso.com' -Username 'admin' -Password $pw

# Using PSCredential
$cred = Get-Credential
Connect-CloudSmith -Url 'https://cloudsmith.contoso.com' -Credential $cred

Notes

The session (access token and refresh token) is stored in the current PowerShell session only. It is not persisted to disk. Run Connect-CloudSmith at the start of each script or interactive session.

Disconnect-CloudSmith

Revoke the current session and clear the stored tokens.

Syntax

Disconnect-CloudSmith

Parameters

None.

Example

Disconnect-CloudSmith

Notes

Disconnect-CloudSmith calls POST /api/v1/auth/logout to revoke the refresh token server-side and then clears the local session state. After disconnecting, any attempt to use another cmdlet returns an error until you call Connect-CloudSmith again.

Get-CloudSmithContext

Return information about the active CloudSmith session.

Syntax

Get-CloudSmithContext

Parameters

None.

Examples

Get-CloudSmithContext

Server                          Org    UserPrincipalName         TokenExpiry
------                          ---    -----------------         -----------
https://cloudsmith.contoso.com  acme   admin@contoso.com         2026-05-31T04:00:00+00:00

# Check whether the token is still valid
(Get-CloudSmithContext).IsTokenValid

Output

Returns a CloudSmith.ContextView object with properties: Server, Org, UserPrincipalName, TokenExpiry, IsTokenValid. The access token is never included.

Notes

If no session is active, the cmdlet writes a non-terminating error and returns nothing. Check IsTokenValid before running long-running scripts.

Test-CloudSmithConnection

Validate API reachability and token validity for the active session.

Syntax

Test-CloudSmithConnection
    [-Quiet]

Parameters

Examples

Test-CloudSmithConnection

Connected  Server                          ApiVersion  TokenValid
---------  ------                          ----------  ----------
True       https://cloudsmith.contoso.com  1.0         True

# Use in a script guard
if (-not (Test-CloudSmithConnection -Quiet)) {
    Connect-CloudSmith -Url 'https://cloudsmith.contoso.com' -Username 'admin'
}

Output

Returns a CloudSmith.ConnectionTest object with properties: Connected, Server, ApiVersion, TokenValid. When -Quiet is specified, returns [bool].

Get-CSCluster

List registered clusters or retrieve a specific cluster by ID or name.

Syntax

Get-CSCluster
    [[-Id] <string>]
    [-Name <string>]
    [-Status <string>]
    [-Type <string>]

Parameters

Examples

# List all clusters
Get-CSCluster

# Get a specific cluster by ID
Get-CSCluster -Id 'clus_01hv7...'

# Get all degraded clusters
Get-CSCluster -Status Degraded

# Get all Hyper-V clusters
Get-CSCluster -Type HyperV

# Wildcard name match
Get-CSCluster -Name 'prod-*'

Output

Returns one or more cluster objects with properties: Id, Name, Type, Status, NodeCount, RegisteredAt, LastSeenAt.

Get-CSNode

List the nodes in a registered cluster.

Syntax

Get-CSNode
    -Cluster <string>

Parameters

Examples

Get-CSNode -Cluster 'prod-cluster-01'

Hostname    IpAddress    Status   Cluster
--------    ---------    ------   -------
node01      10.0.0.11    Online   prod-cluster-01
node02      10.0.0.12    Online   prod-cluster-01
node03      10.0.0.13    Online   prod-cluster-01

Output

Returns CloudSmith.Node objects with properties: NodeId, Hostname, IpAddress, Status, Cluster, JoinedAt.

Add-CSNode

Add a node to a registered cluster. Supports -WhatIf and -Confirm.

Syntax

Add-CSNode
    -Cluster <string>
    -Hostname <string>
    -IpAddress <string>
    [-WhatIf]
    [-Confirm]

Parameters

Examples

Add-CSNode -Cluster 'prod-cluster-01' -Hostname 'node04' -IpAddress '10.0.0.14'

# Preview without making changes
Add-CSNode -Cluster 'prod-cluster-01' -Hostname 'node04' -IpAddress '10.0.0.14' -WhatIf

Output

Returns a CloudSmith.Node object representing the newly added node.

Remove-CSNode

Remove a node from a registered cluster. Supports -WhatIf and -Confirm.

Syntax

Remove-CSNode
    -Cluster <string>
    -Node <string>
    [-WhatIf]
    [-Confirm]

Parameters

Examples

Remove-CSNode -Cluster 'prod-cluster-01' -Node 'node04'

# Preview without making changes
Remove-CSNode -Cluster 'prod-cluster-01' -Node 'node04' -WhatIf

New-CSDeploymentPlan

Create a deployment plan for a cluster. The plan describes all actions CloudSmith would take without executing them.

Syntax

New-CSDeploymentPlan
    -Cluster <string>

Parameters

Examples

$plan = New-CSDeploymentPlan -Cluster 'prod-cluster-01'
$plan.Actions | Format-Table

Output

Returns a CloudSmith.DeploymentPlan object with properties: PlanId, Cluster, Status, Actions, CreatedAt.

Invoke-CSDeployment

Execute a deployment plan against a cluster. Supports -WhatIf and -Confirm.

Syntax

Invoke-CSDeployment
    -Cluster <string>
    [-WhatIf]
    [-Confirm]

Parameters

Examples

$job = Invoke-CSDeployment -Cluster 'prod-cluster-01'
$job | Watch-CSJob

# Preview without applying
Invoke-CSDeployment -Cluster 'prod-cluster-01' -WhatIf

Output

Returns a CloudSmith.DeploymentJob object with properties: JobId, Cluster, Status, StartedAt, CompletedAt, Message.

Get-CSDeploymentStatus

Retrieve the current status of a deployment job.

Syntax

Get-CSDeploymentStatus
    -JobId <string>

Parameters

Examples

Get-CSDeploymentStatus -JobId 'deploy-job-abc123'

JobId               Cluster          Status     StartedAt
-----               -------          ------     ---------
deploy-job-abc123   prod-cluster-01  Completed  2026-05-31T10:00:00Z

Output

Returns a CloudSmith.DeploymentJob object.

Get-CSModuleCatalog

List modules from the CloudSmith module catalog.

Syntax

Get-CSModuleCatalog
    [-Id <string>]
    [-Installed]
    [-Verified]

Parameters

Examples

# List all modules
Get-CSModuleCatalog

# List only installed modules
Get-CSModuleCatalog -Installed

# List only verified modules
Get-CSModuleCatalog -Verified

# Get a specific module
Get-CSModuleCatalog -Id monitoring

# List verified, uninstalled modules (available to install)
Get-CSModuleCatalog -Verified | Where-Object { -not $_.Installed }

Output

Returns module objects with properties: Id, Name, Version, Verified, Installed, UpdateAvailable, Description, CatalogSource.

Get-CSModule

List modules currently installed on the platform.

Syntax

Get-CSModule

Parameters

None.

Examples

Get-CSModule

Name                  Version  Status     Enabled
----                  -------  ------     -------
CloudSmith Monitoring 1.2.0    Healthy    True
CloudSmith Firmware   0.9.1    Healthy    True

Output

Returns CloudSmith.Module objects with properties: ModuleId, Name, Version, Status, Enabled, InstalledAt.

Notes

Get-CSModule lists installed modules and their runtime state. To browse available modules in the catalog, use Get-CSModuleCatalog.

Install-CSModule

Install a module from the CloudSmith catalog.

Syntax

Install-CSModule
    -ModuleId <string>
    [-FromCatalog]
    [-Version <string>]

Parameters

Examples

# Install the latest verified version from the catalog
Install-CSModule -ModuleId monitoring -FromCatalog

# Install a specific version
Install-CSModule -ModuleId monitoring -FromCatalog -Version 1.1.0

# Wait for installation to complete
$job = Install-CSModule -ModuleId monitoring -FromCatalog
$job | Watch-CSJob

Notes

Install-CSModule submits an asynchronous install job and returns immediately with a job object. Use Watch-CSJob or Get-CSDeploymentStatus to poll for completion. The cmdlet requires platform:admin permission on the authenticated account.

Enable-CSModule

Activate an installed module. Supports -WhatIf and -Confirm.

Syntax

Enable-CSModule
    -ModuleId <string>
    [-WhatIf]
    [-Confirm]

Parameters

Examples

Enable-CSModule -ModuleId monitoring

# Preview without making changes
Enable-CSModule -ModuleId monitoring -WhatIf

Output

Returns the updated CloudSmith.Module object with Enabled set to $true.

Disable-CSModule

Deactivate an installed module without uninstalling it. Supports -WhatIf and -Confirm.

Syntax

Disable-CSModule
    -ModuleId <string>
    [-WhatIf]
    [-Confirm]

Parameters

Examples

Disable-CSModule -ModuleId monitoring

# Preview without making changes
Disable-CSModule -ModuleId monitoring -WhatIf

Output

Returns the updated CloudSmith.Module object with Enabled set to $false.

Remove-CSModule

Uninstall an installed module. Supports -WhatIf and -Confirm.

Syntax

Remove-CSModule
    -ModuleId <string>
    [-Force]

Parameters

Examples

# Uninstall with confirmation prompt
Remove-CSModule -ModuleId monitoring

# Uninstall without confirmation
Remove-CSModule -ModuleId monitoring -Force

Notes

Requires platform:admin permission. The module must be installed; uninstalling a module that is not installed returns an error. Removal is asynchronous — the cmdlet returns a job object.

Get-CSAgent

List registered CloudSmith agents.

Syntax

Get-CSAgent

Parameters

None.

Examples

Get-CSAgent

Hostname          Status     AgentId         LastSeenAt
--------          ------     -------         ----------
agent-host-01     Connected  agent_01hz...   2026-05-31T10:05:00Z
agent-host-02     Connected  agent_02hz...   2026-05-31T10:05:02Z

Output

Returns CloudSmith.Agent objects with properties: AgentId, Hostname, Status, RegisteredAt, LastSeenAt.

Register-CSAgent

Register a new CloudSmith agent by hostname and token. Supports -WhatIf and -Confirm.

Syntax

Register-CSAgent
    -Hostname <string>
    -Token <string>
    [-WhatIf]
    [-Confirm]

Parameters

Examples

Register-CSAgent -Hostname 'agent-host-03' -Token 'reg-token-xyz'

# Preview without registering
Register-CSAgent -Hostname 'agent-host-03' -Token 'reg-token-xyz' -WhatIf

Output

Returns a CloudSmith.Agent object representing the newly registered agent.

Remove-CSAgent

Deregister a CloudSmith agent. Supports -WhatIf and -Confirm.

Syntax

Remove-CSAgent
    -AgentId <string>
    [-WhatIf]
    [-Confirm]

Parameters

Examples

Remove-CSAgent -AgentId 'agent_01hz...'

# Preview without deregistering
Remove-CSAgent -AgentId 'agent_01hz...' -WhatIf

Get-CloudSmithPlatformUpdate

Check whether a CloudSmith platform update is available.

Syntax

Get-CloudSmithPlatformUpdate

Parameters

None.

Examples

Get-CloudSmithPlatformUpdate

CurrentVersion  LatestVersion  UpdateAvailable  ReleaseNotesUrl
--------------  -------------  ---------------  ---------------
1.2.3           1.2.4          True             https://github.com/...

# Conditionally apply an update
$info = Get-CloudSmithPlatformUpdate
if ($info.UpdateAvailable) {
    Update-CloudSmith -Apply
}

Output

Returns a CloudSmith.PlatformUpdateInfo object with properties: CurrentVersion, LatestVersion, UpdateAvailable, ReleaseNotesUrl.

Notes

This cmdlet only checks for updates; it does not apply them. Use Update-CloudSmith -Apply to apply an available update.

Update-CloudSmith

Check for, apply, or roll back platform updates.

Syntax

Update-CloudSmith
    [-Check]
    [-Apply]
    [-Rollback]
    [-TargetVersion <string>]
    [-WhatIf]

Parameters

Examples

# Check for updates
Update-CloudSmith -Check

# Apply the latest update
Update-CloudSmith -Apply

# Apply a specific version
Update-CloudSmith -Apply -TargetVersion 0.6.0

# Roll back to the previous version
Update-CloudSmith -Rollback

# Preview what -Apply would do
Update-CloudSmith -Apply -WhatIf

Output (-Check):

CurrentVersion : 0.5.3
LatestVersion  : 0.6.0
UpdateAvailable: True
ReleaseNotesUrl: https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/tag/v0.6.0

Notes

-Apply and -Rollback require platform:admin permission. Both operations are asynchronous and return a job object. The update pulls new container images and performs a rolling restart of the Docker Compose stack. No VM reboot is required for standard updates.

Air-gapped environments cannot use Update-CloudSmith -Apply unless the images are accessible from the CloudSmith VM. See Bundled install — updating for the offline update process.

Watch-CSJob

Stream job progress and wait for completion. Uses the CloudSmith SignalR hub when available, and falls back to polling automatically.

Syntax

Watch-CSJob
    -JobId <string>
    [-TimeoutSeconds <int>]

Parameters

Examples

# Watch a deployment job until completion
$job = Invoke-CSDeployment -Cluster 'prod-cluster-01'
Watch-CSJob -JobId $job.JobId

# Pipe a job object directly
Invoke-CSDeployment -Cluster 'prod-cluster-01' | Watch-CSJob

# Use a shorter timeout
Watch-CSJob -JobId 'job-abc123' -TimeoutSeconds 600

Output

Returns a CloudSmith.JobResult object with properties: JobId, Status, ExitCode, Message, StartedAt, CompletedAt.

Notes

Progress is displayed using Write-Progress. Log messages from the server are available via -Verbose. The cmdlet throws a terminating error if the job fails or the timeout expires, making it safe to use in pipelines and scripts that check $? or use -ErrorAction Stop.