IBM Sovereign Core platform Command Line Interface (CLI)

Edit online

The IBM® Sovereign Core platform CLI is a command-line tool designed for developers, system administrators, and platform operators who need programmatic access to platform features. The CLI eliminates the need for manual UI interactions by providing direct terminal access to platform management functions, making it ideal for automation, scripting, and DevOps workflows.

Note: The binaries are automatically downloaded on landing server during deployment process.

Available Command Groups

The CLI organizes commands into functional groups for easier navigation and use. The following table describes each command group and its purpose:

Table 1. Available command groups
Command Group Commands Description
Authentication login, logout, status Manage authentication sessions and view connection status
System owner account management msp-account Manage Managed Service Provider accounts
System owner IAM msp-account-users, msp-account-groups, msp-account-apikeys Manage users, groups, and API keys for System owner accounts
Tenant Account Management tenant-accounts Create and manage tenant accounts
Tenant IAM tenant-account-users, tenant-account-groups, tenant-account-apikeys Manage users, groups, and API keys for tenant accounts
Tenant Settings tenant-settings Configure tenant-specific settings and preferences
Service Instances instances-management Provision and manage service instances
Instance IAM instances-users, instances-groups, instances-apikeys Manage users, groups, and API keys for service instances
Workspaces workspaces-management Manage workspace lifecycle and configuration
Workspace IAM workspaces-users, workspaces-groups Manage users and groups for workspaces
Service Catalog services Browse and configure available platform services
AI Inference Services services-aiiaas Manage AI Inference as a Service operations
Product Registration products Register and manage product offerings
System Operations system Configure platform-wide settings and view metrics
Host Resources hosts-resources Manage infrastructure inventory and cluster resources

Authentication

Before using the CLI, you must authenticate with the platform. The authentication method depends on the type of operations you need to perform.

Login methods

The platform CLI supports two distinct login methods based on your role and the commands you need to execute:

System owner Login

Use System owner login to execute Managed Service Provider commands and run system-wide management tasks.

To obtain your System owner token:

  1. Navigate to the system owner ui interface
  2. Click your profile menu
  3. Select Login Command
  4. Copy and execute the provided login command

Login syntax:

sov-core-platform login --hostname <hostname> --token <system-owner-bearer-token>
Tenant Login

Use tenant login to execute tenant-specific commands and manage workspace resources.

To obtain your tenant token:

  1. Navigate to <accountui-url>/tenant/<tenant-id>
  2. Click your profile menu
  3. Select Login Command
  4. Copy and execute the provided login command

Login syntax:

sov-core-platform login --hostname <hostname> --token <tenant-bearer-token>
Login Parameters

The login command accepts the following parameters:

Table 2. Login parameters
Parameter Required Default Description
hostname Yes None Hostname of the server (for example, localhost:3002 or api.example.com)
token Yes None Bearer token for authentication (System owner or tenant token)
scheme No https Connection scheme (http or https)
Login Examples 
# system owner login with HTTPS (default)
sov-core-platform login --hostname xpm.example.com --token "your-system-owner-token-here"

# Tenant login with HTTPS
sov-core-platform login --hostname xpm.example.com --token "your-tenant-token-here"

# Login with HTTP (for development environments)
sov-core-platform login --hostname localhost:3002 --scheme http --token "your-token-here"
Note: The token type (System owner or tenant) determines which commands you can execute. Refer to the Token Types and Authentication Requirements section for details.
Verify Authentication Status

To verify your current authentication status and connection details:

sov-core-platform status

Example output:

Authentication Status:
  Hostname: xpm.example.com
  Scheme: https
  Authenticated: Yes
Logout

To end your session and remove stored credentials:

sov-core-platform logout

Token Types and Authentication Requirements

The platform uses role-based authentication tokens to control access to different command groups. Understanding token types helps you determine which login method to use.

Table 3. Token Types and Authentication Requirements
Token Type Source Use Cases
System owner Token Generated from System owner UI System owner account operations, system-wide management, platform configuration, and infrastructure management
Tenant/Workspace Token Generated from AccountUI at <accountui-url>/tenant/<tenant-id> Tenant-specific operations, workspace management, service instance provisioning, and tenant resource administration
Important: Attempting to execute commands with an incorrect token type results in authorization errors. Ensure you use the appropriate token for your intended operations.

Configuration File

The CLI stores authentication credentials and connection settings in a local configuration file. This file is automatically created when you log in and updated with each subsequent login.

File Location:

Default: ~/.sov-core/sov-core-platform/config.yaml

File Format: 

hostname: xpm.example.com
scheme: https
Authorization: Bearer your-token-here
Tip: You can manually edit this file if needed, but it is recommended to use the login command to ensure proper formatting.

Practical Workflows

This section provides practical, real-world examples of using the sov-core-platform CLI. The workflows are organized by the token type required (System owner or Tenant).

Use Case 1: Create a Tenant Account

Token Required: System owner Token

Description: Create a new tenant account under the System owner account. This is the first step in onboarding a new customer or team to the platform.

Prerequisites:

  • Logged in with System owner token
  • Owner or Editor role on the System owner account

Command:

sov-core-platform tenant-accounts createTenant \
  --createTenantAccountRequest.leadAccountId system \
  --createTenantAccountRequest.ownerEmail user@example.com \
  --createTenantAccountRequest.name cli-tenant-4 \
  --createTenantAccountRequest.storageClass '[]' \
  --createTenantAccountRequest.imageRegistryApiKey null \
  --insecure

Parameters:

Table 4. Create Tenant Parameters
Parameter Required Description
leadAccountId Yes Parent System owner account ID (typically system)
ownerEmail Yes Email address of the tenant owner
name Yes Unique name for the tenant account
storageClass No JSON object for storage class configuration (use '[]' for default)
imageRegistryApiKey No Image registry API key (use null if not needed)
description No Optional tenant account description
ownerDisplayName No Display name of the tenant owner

Expected Output:

{
  "owner": {
    "identityType": "USER",
    "identityUid": "d04c7e15-241c-46fc-95c8-0d940ed71683"
  },
  "scopeId": "0679e979-2074-455d-a918-9ac6d4269756"
}
Important: Save the scopeId value as your Tenant Account ID - you'll need it for creating workspaces.
Use Case 2: Publish a Service to the Catalog

Token Required: System owner Token

Description: Configure and publish a service (for example, Cluster as a Service) to make it available in the catalog for tenants to deploy.

Step 1: Get Infrastructure Inventory

sov-core-platform hosts-resources getInventory --insecure

Expected Output:

{
  "agents": [
    {
      "agentClassification": "basic-memory-16",
      "coreCount": 8,
      "memBytes": 17179869184,
      "gpuCount": 0,
      "node": "test-vm-001"
    }
  ]
}

Save these values: agentClassification → $AGENT_CLASS

coreCount → $CORE_COUNT

memBytes → $MEM_BYTES

gpuCount → $GPU_COUNT

Step 2: Configure Service Categories

Use the inventory data to publish service categories:

sov-core-platform services saveServiceCategories \
  --serviceId cluster-as-a-service \
  --body '{
    "categories": [{
      "agentClass": "basic-memory-16",
      "coreCount": 8,
      "displayName": "memory-16",
      "gpuCount": 0,
      "id": "memory-16",
      "memBytes": 17179869184,
      "planes": ["control", "worker"]
    }],
    "cidr": "192.168.1.0/24",
    "excludedIPs": ["192.168.1.1/32"],
    "visibility": ["global"]
  }' \
  --insecure

Field Descriptions:

Table 5. Service Category Fields
Field Description
agentClass Hardware classification from inventory
displayName Human-readable category name
id Unique identifier (typically same as displayName)
planes Where category can be used: ["control"], ["worker"], or ["control", "worker"]
cidr Network CIDR range for cluster (for example, 192.168.1.0/24)
excludedIPs IPs to exclude from allocation with /32 prefix
visibility ["global"] = published and visible to all, [] = hidden from catalog

Step 3: Verify Catalog Configuration

sov-core-platform services getServiceCategories \
  --serviceId cluster-as-a-service \
  --insecure

Expected Output:

{
  "categories": [
    {
      "agentClass": "basic-memory-16",
      "coreCount": 8,
      "displayName": "memory-16",
      "gpuCount": 0,
      "hostCount": 3,
      "id": "memory-16",
      "inUse": 0,
      "memBytes": 17179869184,
      "planes": ["control", "worker"]
    }
  ],
  "cidr": "192.168.1.0/24",
  "excludedIPs": ["192.168.1.1/32"],
  "visibility": ["global"]
}
Use Case 3: Create a Workspace

Token Required: Tenant Token

Description: Create a workspace within a tenant account. Workspaces provide isolated environments for deploying service instances.

Command:

sov-core-platform workspaces-management createWorkspace \
  --createWorkspaceRequest.leadAccountId <tenant-account-id> \
  --createWorkspaceRequest.email user@example.com \
  --createWorkspaceRequest.name my-workspace \
  --createWorkspaceRequest.displayName "John Doe" \
  --insecure

Parameters:

Table 6. Create Workspace Parameters
Parameter Required Description
leadAccountId Yes Tenant account ID from Use Case 1
email Yes Email address of the workspace owner
name Yes Unique name for the workspace
displayName Yes Display name for the workspace owner

Expected Output:

{
  "owner": {
    "identityType": "USER",
    "identityUid": "42074dda-32fc-40e8-a6dd-4b66ef7b4423"
  },
  "scopeId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
Important: Save the scopeId value as your Workspace ID - you'll need it for deploying service instances.
Use Case 4: Deploy a Cluster as a Service Instance

Token Required: Tenant Token

Description: Deploy a cluster instance within a workspace. This is a multi-step process.

Step 4.1: Get Data Center Name

sov-core-platform system getDataCenterName --insecure

Expected Output:

{
  "name": "us-east-2"
}

Save: name → $DATA_CENTER_NAME

Step 4.2: Get Service Metadata

sov-core-platform services getServiceById \
  --serviceId cluster-as-a-service \

Expected Output:

{
  "productName": "Cluster as a Service",
  "productDescription": "Out-of-the-box OpenShift cluster with custom sizing configuration.",
  "serviceID": "cluster-as-a-service",
  "defaultPlanID": "cluster-as-a-service_plan",
  "consoleParameters": {
    "category": "clusters",
    "tags": ["Compute"]
  },
  "plans": [...]
}

Save these values:

productName → $PRODUCT_NAME

productDescription → $PRODUCT_DESC

serviceID → $SERVICE_ID

defaultPlanID → $PLAN_ID

plans → $PLANS

consoleParameters.category → $CATEGORY

consoleParameters.tags → $TAGS

Step 4.3: Get Service Categories

sov-core-platform services getServiceCategories \
  --serviceId cluster-as-a-service \ 
  --insecure

Expected Output:

{
  "categories": [
    {
      "agentClass": "basic-memory-16",
      "coreCount": 8,
      "displayName": "memory-16",
      "gpuCount": 0,
      "hostCount": 3,
      "id": "memory-16",
      "inUse": 0,
      "memBytes": 17179869184,
      "planes": ["control", "worker"]
    }
  ],
  "cidr": "192.168.1.0/24",
  "excludedIPs": ["192.168.1.1/32"],
  "visibility": ["global"]
}

Save these values:

categories → $HOST_CATEGORIES (complete categories array)

categories[0].id → $HOST_CATEGORY_ID (e.g., memory-16)

Step 4.4: Construct the CRN

CRN Format:

crn:v1:cName:cType:cluster-as-a-service:location:sub/workspace-id:::

Example : 

 CRN="crn:v1:ibm-sc:private:cluster-as-a-service:us-east-2:sub/a1b2c3d4-5678-90ab-cdef-12345678>90ab:::"

Components:

cName: Typically ibm-sc for IBM Sovereign Cloud

cType: private for private cloud deployments

location: Data center name from Step 4.1 ($DATA_CENTER_NAME)

workspace-id: Workspace ID from Use Case 3 ($WORKSPACE_ID)

Step 4.5: Build Request Body

Construct the complete request body using values from previous steps:

{
  "parameters": {
    "ClusterRequest": {
      "productName": "$PRODUCT_NAME",
      "productDescription": "$PRODUCT_DESC",
      "serviceID": "$SERVICE_ID",
      "plans": $PLANS,
      "category": "$CATEGORY",
      "consumption": {
        "cpu": 0,
        "memory": "",
        "disk": "",
        "nodes": 0,
        "gpu": 0
      },
      "tags": $TAGS,
      "disabled": false,
      "spec": {
        "clusterName": "$CLUSTER_NAME",
        "description": "$CLUSTER_DESC",
        "nodeConfigs": {
          "master": {
            "hostCategoryId": "$HOST_CATEGORY_ID",
            "count": "$MASTER_COUNT"
          },
          "workers": $WORKERS
        },
        "compactCluster": "$COMPACT_CLUSTER",
        "enableObservability": "$ENABLE_OBSERVABILITY",
        "clusterLabel": "$CLUSTER_LABEL"
      }
    },
    "accountParameters": {
      "storage-class-data": null
    },
    "hostCategoryConfig": $HOST_CATEGORIES
  }
}

User Input Values:

Table 7. User Input Variables
Variable Example Description
$CLUSTER_NAME my-test-cluster Cluster name (DNS-compliant)
$CLUSTER_DESC Test cluster for development Cluster description
$MASTER_COUNT 3 Control plane nodes (1, 3, 4, or 5)
$WORKERS [{"hostCategoryId":"memory-16","count":"3"}] Worker pool configuration
$COMPACT_CLUSTER false Compact mode (true/false)
$ENABLE_OBSERVABILITY true Enable observability (true/false)
$CLUSTER_LABEL env=dev,team=platform Cluster labels (comma-separated) 
crn:v1:<cName>:<cType>:cluster-as-a-service:<location>:sub/<workspace-id>:::

Step 4.6: Create the Instance

sov-core-platform instances-management createInstance \
  --provisionRequest.service_id cluster-as-a-service \
  --provisionRequest.plan_id cluster-as-a-service_plan \
  --provisionRequest.context.account_id <tenant-id> \
  --provisionRequest.context.sub_account_id <workspace-id> \
  --provisionRequest.context.name my-cluster \
  --provisionRequest.context.platform gori \
  --provisionRequest.context.crn "<crn>" \
  --body '<request-body-json>' \
  --insecure

Parameters:

Table 8. Create Instance Parameters
Parameter Description
service_id Service ID from Step 2
plan_id Plan ID from Step 2
account_id Tenant ID from Use Case 1
sub_account_id Workspace ID from Use Case 3
name Cluster name (user input)
platform Platform identifier (typically gori)
crn CRN from Step 4
body Request body with cluster configuration
Important: Save the instance_id from the response for tracking and managing your cluster instance.
Complete End-to-End Workflow

Phase 1: System owner Operations (System owner Token Required)

# 1. Login with systen owner token
sov-core-platform login --hostname xpm.example.com --token <system-owner-token> --insecure

# 2. Verify authentication
sov-core-platform status

# 3. Get infrastructure inventory
sov-core-platform hosts-resources getInventory --insecure
# Save: agentClassification, coreCount, memBytes, gpuCount

# 4. Publish service catalog
sov-core-platform services saveServiceCategories \
  --serviceId cluster-as-a-service \
  --body '<categories-json>' \
  --insecure

# 5. Verify catalog (optional)
sov-core-platform services getServiceCategories \
  --serviceId cluster-as-a-service \
  --insecure

# 6. Create tenant account
sov-core-platform tenant-accounts createTenant \
  --createTenantAccountRequest.leadAccountId system \
  --createTenantAccountRequest.ownerEmail user@example.com \
  --createTenantAccountRequest.name my-tenant \
  --insecure

# Save scopeId as $TENANT_ID

Phase 2: Tenant Operations (Tenant Token Required)

# 7. Login with tenant token
sov-core-platform login --hostname xpm.example.com --token <tenant-token> --insecure

# 8. Create workspace
sov-core-platform workspaces-management createWorkspace \
  --createWorkspaceRequest.leadAccountId <tenant-id> \
  --createWorkspaceRequest.email user@example.com \
  --createWorkspaceRequest.name my-workspace \
  --createWorkspaceRequest.displayName "User Name" \
  --insecure
# Save scopeId as $WORKSPACE_ID

# 9. Get data center name
sov-core-platform system getDataCenterName --insecure
# Save name as $DATA_CENTER_NAME

# 10. Get service metadata
sov-core-platform services getServiceById \
  --serviceId cluster-as-a-service \
  --insecure
# Save serviceID, defaultPlanID, productName, productDescription, plans, category, tags

# 11. Get service categories (with tenant token)
sov-core-platform services getServiceCategories \
  --serviceId cluster-as-a-service \
  --insecure
# Save categories array and category IDs

# 12. Construct CRN
CRN="crn:v1:ibm-sc:private:cluster-as-a-service:$DATA_CENTER_NAME:sub/$WORKSPACE_ID:::"

# 13. Build request body (see Step 4.5 for complete JSON structure)

# 14. Create cluster instance
sov-core-platform instances-management createInstance \
  --provisionRequest.service_id cluster-as-a-service \
  --provisionRequest.plan_id cluster-as-a-service_plan \
  --provisionRequest.context.account_id <tenant-id> \
  --provisionRequest.context.sub_account_id <workspace-id> \
  --provisionRequest.context.name my-cluster \
  --provisionRequest.context.platform gori \
  --provisionRequest.context.crn "$CRN" \
  --body '<request-body-json>' \
  --insecure
Tips and Best Practices

All commands support these global flags:

  • --insecure - Skip TLS certificate verification
  • --debug - Output debug logs for troubleshooting
  • --dry-run - Preview the request without executing it
  • --config - Specify custom config file path

Getting help:

# General help
sov-core-platform --help

# Command group help
sov-core-platform tenant-accounts --help

# Specific command help
sov-core-platform tenant-accounts createTenant --help