cs CLI reference

cs is the CloudSmith command-line interface. Install it on any machine with network access to your CloudSmith portal.

Install

# Windows — PowerShell 7
winget install cloudsmith.cs

# Or download directly from the release page
Invoke-WebRequest -Uri 'https://github.com/cloudsmith-cloud/cloudsmith-cli/releases/latest/download/cs-windows-x64.exe' `
    -OutFile 'C:\Program Files\CloudSmith\cs.exe'

Authenticate

cs auth login --url https://cloudsmith.contoso.com --username admin

Authentication stores a session token in ~/.cloudsmith/session.json. Run cs auth logout to clear it.

cs config

Read and write CLI configuration. Settings are stored in ~/.cloudsmith/config.json.

cs config get

Read a single configuration value.

Synopsis:

cs config get <key> [flags]

Arguments:

Argument Description
key Configuration key to read: server, org, or output

Example:

cs config get server

Key      Value
server   https://cloudsmith.contoso.com

cs config set

Write a configuration value.

Synopsis:

cs config set <key> <value> [flags]

Arguments:

Argument Description
key Configuration key to write: server, org, or output
value Value to set. For output, accepted values are table or json

Example:

cs config set server https://cloudsmith.contoso.com
cs config set output json

Set server = https://cloudsmith.contoso.com

cs config list

Print all current configuration values.

Synopsis:

cs config list [flags]

Example:

cs config list

Key      Value
server   https://cloudsmith.contoso.com
org      contoso
output   table

cs cluster

Manage registered clusters.

cs cluster list

List all clusters registered with the platform.

Synopsis:

cs cluster list [flags]

Flags:

Flag Description
--status <value> Filter by status: Healthy, Degraded, Pending, Offline
--type <value> Filter by type: HyperV, AzureLocal
--format <value> Output format: table (default) or json

Example:

cs cluster list

ID              NAME            TYPE     STATUS    NODES
clus_01hv7...   prod-hci-01     HyperV   Healthy   3
clus_02...      dev-hci-01      HyperV   Pending   2

cs cluster list --status Healthy --format json

[
  {
    "id": "clus_01hv7...",
    "name": "prod-hci-01",
    "type": "HyperV",
    "status": "Healthy",
    "nodeCount": 3
  }
]

cs cluster get

Get details for a specific cluster.

Synopsis:

cs cluster get <cluster-id-or-name> [flags]

Flags:

Flag Description
--format <value> Output format: table (default) or json

Example:

cs cluster get prod-hci-01

ID:           clus_01hv7...
Name:         prod-hci-01
Type:         HyperV
Status:       Healthy
Nodes:        3
Relay:        relay-prod-hci-01 (Connected, last seen 30s ago)
Registered:   2026-05-01 10:00:00 UTC

cs cluster register

Register a new cluster and print the Relay enrollment command.

Synopsis:

cs cluster register --name <name> --type <type> [flags]

Flags:

Flag Description
--name <value> Display name for the cluster (required)
--type <value> Cluster type: HyperV (default) or AzureLocal (required)
--site <value> Site ID to associate the cluster with
--format <value> Output format: table (default) or json

Example:

cs cluster register --name prod-hci-02 --type HyperV

Cluster registered.

ID:               clus_03...
Name:             prod-hci-02
Status:           Pending
Enrollment token: enroll_01hz...  (expires in 24 hours)

Run the following command on a Linux host inside the cluster network to deploy the Relay:

  docker run -d --name cloudsmith-relay --restart=always \
    -e RELAY_PAAS_URL=https://cloudsmith.contoso.com \
    -e RELAY_ENROLLMENT_TOKEN=enroll_01hz... \
    -e RELAY_DISPLAY_NAME=relay-prod-hci-02 \
    -v cloudsmith-relay-identity:/var/lib/cloudsmith-relay/identity \
    ghcr.io/cloudsmith-cloud/cloudsmith-relay:latest

cs deploy

Create and execute cluster deployment plans.

cs deploy plan

Create a deployment plan for a cluster. The plan shows all actions CloudSmith would take without making any changes.

Synopsis:

cs deploy plan --cluster <name> [flags]

Flags:

Flag Description
--cluster <value> Target cluster name or ID (required)
--server <url> Override the configured server URL
--output table\|json Output format (default: table)

Example:

cs deploy plan --cluster prod-hci-01

Action    Resource          Detail
------    --------          ------
Create    VirtualSwitch     external-switch-01
Update    ClusterNetwork    10.0.0.0/24
Create    LiveMigration     SMB transport enabled

Plan ID: plan_01hz...

cs deploy apply

Execute a deployment plan against a cluster. Prompts for confirmation unless --yes is passed.

Synopsis:

cs deploy apply --cluster <name> [--yes] [flags]

Flags:

Flag Description
--cluster <value> Target cluster name or ID (required)
--yes Skip the confirmation prompt
--server <url> Override the configured server URL
--output table\|json Output format (default: table)

Example:

cs deploy apply --cluster prod-hci-01 --yes

Field    Value
JobId    job_01hz...
Status   Running
Cluster  prod-hci-01

Use cs watch --job job_01hz... or cs deploy status --job job_01hz... to follow progress.

cs deploy status

Poll the status of a deployment job.

Synopsis:

cs deploy status --job <id> [flags]

Flags:

Flag Description
--job <value> Deployment job ID (required)
--server <url> Override the configured server URL
--output table\|json Output format (default: table)

Example:

cs deploy status --job job_01hz...

Field      Value
JobId      job_01hz...
Status     Completed
Cluster    prod-hci-01
StartedAt  2026-05-31T10:00:00Z
UpdatedAt  2026-05-31T10:04:33Z

cs agent

Manage CloudSmith agents. Agents run on hosts inside your cluster network and relay management traffic to the portal.

cs agent list

List all registered agents.

Synopsis:

cs agent list [flags]

Flags:

Flag Description
--server <url> Override the configured server URL
--output table\|json Output format (default: table)

Example:

cs agent list

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

cs agent register

Register a new agent by hostname and enrollment token.

Synopsis:

cs agent register --host <hostname> --token <token> [flags]

Flags:

Flag Description
--host <value> Hostname of the agent to register (required)
--token <value> Registration token issued during cluster enrollment (required)
--server <url> Override the configured server URL
--output table\|json Output format (default: table)

Example:

cs agent register --host agent-host-03 --token reg-token-xyz

Field     Value
Id        agent_03hz...
Hostname  agent-host-03
Status    Registered

cs agent remove

Deregister an agent. Prompts for confirmation unless --force is passed.

Synopsis:

cs agent remove <id> [--force] [flags]

Arguments:

Argument Description
id Agent ID to deregister

Flags:

Flag Description
--force Skip the confirmation prompt
--server <url> Override the configured server URL
--output table\|json Output format (default: table)

Example:

cs agent remove agent_01hz... --force

Agent 'agent_01hz...' removed.

cs module catalog

Browse and manage the module catalog.

cs module catalog list

List modules in the catalog.

Synopsis:

cs module catalog list [flags]

Flags:

Flag Description
--verified Show only cosign-verified modules
--installed Show only installed modules
--format <value> Output format: table (default) or json

Example:

cs module catalog list

ID             NAME                     VERSION  VERIFIED  INSTALLED  UPDATE
monitoring     CloudSmith Monitoring    1.2.0    Yes       No         -
firmware       CloudSmith Firmware      0.9.1    Yes       Yes        -

cs module catalog list --verified --format json

[
  {
    "id": "monitoring",
    "name": "CloudSmith Monitoring",
    "version": "1.2.0",
    "verified": true,
    "installed": false,
    "updateAvailable": false
  }
]

cs module catalog get

Get details for a specific module.

Synopsis:

cs module catalog get <module-id>

Example:

cs module catalog get monitoring

ID:           monitoring
Name:         CloudSmith Monitoring
Version:      1.2.0
Verified:     Yes
Installed:    No
Description:  Prometheus-based workload monitoring for Hyper-V clusters.
Source:       ghcr.io/cloudsmith-cloud/module-monitoring:1.2.0

cs module install

Install a module from the catalog.

Synopsis:

cs module install --from-catalog <module-id> [flags]

Flags:

Flag Description
--from-catalog Install from the GHCR catalog (required for catalog installs)
--version <value> Specific version to install (default: latest verified release)
--wait Wait for the install job to complete before returning

Example:

cs module install --from-catalog monitoring

Installing module: monitoring v1.2.0
Job ID: job_01hz...
Status: Installing

Use 'cs job get job_01hz...' to check progress.

cs module install --from-catalog monitoring --wait

Installing module: monitoring v1.2.0
Job ID: job_01hz...
... installing (15s)
Status: Completed

Module 'monitoring' installed successfully.

cs watch

Stream real-time job progress via Server-Sent Events (SSE). Use this after cs deploy apply or any other command that returns a job ID.

Synopsis:

cs watch --job <id> [flags]

Flags:

Flag Description
--job <value> Job ID to stream (required)
--server <url> Override the configured server URL

Behavior:

  • Connects to /api/v1/jobs/{id}/stream and prints [HH:mm:ss] message lines as events arrive.
  • Exits with code 0 when the job reaches Completed.
  • Exits with code 1 when the job reaches Failed or Cancelled, or if the connection fails.

Example:

cs deploy apply --cluster prod-hci-01 --yes
# Output: JobId  job_01hz...

cs watch --job job_01hz...

[10:00:01] Starting deployment for cluster prod-hci-01
[10:00:05] Creating virtual switch external-switch-01
[10:00:18] Updating cluster network
[10:04:33] Deployment completed successfully

cs platform update

Check for and apply platform updates.

cs platform update –check

Check whether a newer version of CloudSmith is available.

Synopsis:

cs platform update --check

Example:

cs platform update --check

Current version:  0.5.3
Latest version:   0.6.0
Update available: Yes
Release notes:    https://github.com/cloudsmith-cloud/cloudsmith-installer/releases/tag/v0.6.0

cs platform update –apply

Apply the latest available update (or a specific version).

Synopsis:

cs platform update --apply [--version <value>] [--wait]

Flags:

Flag Description
--version <value> Specific version to update to (default: latest)
--wait Wait for the update job to complete before returning

Example:

cs platform update --apply --wait

Applying update: 0.5.3 → 0.6.0
Job ID: job_02hz...
... updating (42s)
Status: Completed

CloudSmith updated to v0.6.0 successfully.

cs platform update –rollback

Roll back to the previously installed version.

Synopsis:

cs platform update --rollback [--wait]

Example:

cs platform update --rollback

Rolling back: 0.6.0 → 0.5.3
Job ID: job_03hz...

Use 'cs job get job_03hz...' to check progress.

Global flags

These flags apply to all cs commands:

Flag Description
--server <url> Override the configured server URL for this invocation
--output table\|json Output format: table (default) or json. Short form: -o
--verbose Enable verbose output. Short form: -v
--version Print the cs CLI version and exit
--help Print help for the command