cs CLI reference

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

Install

The CLI is not publicly available yet. Register interest in the upcoming Private Preview at preview@cloudgrange.com.

Authenticate

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

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

cs config

Read and write CLI configuration. Settings are stored in ~/.cloudgrange/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://cloudgrange.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://cloudgrange.contoso.com
cs config set output json

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

cs config list

Print all current configuration values.

Synopsis:

cs config list [flags]

Example:

cs config list

Key      Value
server   https://cloudgrange.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 cloudgrange-relay --restart=always \
    -e RELAY_PAAS_URL=https://cloudgrange.contoso.com \
    -e RELAY_ENROLLMENT_TOKEN=enroll_01hz... \
    -e RELAY_DISPLAY_NAME=relay-prod-hci-02 \
    -v cloudgrange-relay-identity:/var/lib/cloudgrange-relay/identity \
    ghcr.io/cloudgrange-cloud/cloudgrange-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 CloudGrange 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 CloudGrange 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     CloudGrange Monitoring    1.2.0    Yes       No         -
firmware       CloudGrange Firmware      0.9.1    Yes       Yes        -

cs module catalog list --verified --format json

[
  {
    "id": "monitoring",
    "name": "CloudGrange 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:         CloudGrange Monitoring
Version:      1.2.0
Verified:     Yes
Installed:    No
Description:  Prometheus-based workload monitoring for Hyper-V clusters.
Source:       ghcr.io/cloudgrange-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 CloudGrange 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/CloudGrange/cloudgrange-deployment-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

CloudGrange 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