Common StormForge CLI workflows

Get started with common StormForge CLI workflows

8 minute read

The StormForge CLI lets you interact with Optimize Live to inspect workloads, view optimization data, and manage recommendations.

This guide covers common workflows:

Authenticate and configure the CLI
Explore clusters and workloads
View and generate recommendations
Query recommendation data
Apply recommendations to workloads

Typical workflow:

Identify workload → Inspect recommendation → Apply recommendation

Common workflow commands:

stormforge get workloads --cluster <cluster>
stormforge get recommendations --cluster <cluster> --namespace <namespace> --name <workload>
stormforge apply --cluster <cluster> --namespace <namespace> --resource <resource-type> --name <workload>

Common commands

Task	Command
Authenticate	`stormforge login`
List clusters	`stormforge get clusters`
List workloads	`stormforge get workloads`
View workloads	`stormforge view workloads`
List recommendations	`stormforge get recommendations`
Create recommendation	`stormforge create recommendation`
Apply recommendations	`stormforge apply`

Using command help in the CLI

Use the --help flag with any command for more information.

Get started with the CLI

Authenticate and configure the StormForge CLI.

Authenticate

Command:

stormforge login

Example output:

You are now logged in.

Opens a browser window and authenticates using your StormForge account.

Get the CLI version

Command:

stormforge version

Example output:

stormforge version 6.1.1

Displays the installed StormForge CLI version.

Set up autocompletion

Enabling CLI autocompletion

If you installed the StormForge CLI via brew, autocompletion is enabled by default.

Command:

stormforge completion [bash|zsh|fish|powershell] --help

Follow the instructions for your shell to enable command autocompletion.

Once configured, you can tab-complete StormForge CLI commands.

Explore clusters and workloads

Retrieve cluster and workload information.

List clusters

Command:

stormforge get clusters -o wide

Example output:

NAME        AGENT VERSION   APPLIER VERSION   KUBERNETES VERSION   STATE     AGE
<cluster>   2.27.2          2.12.0            1.34.0               Created   3 hours

The wide output option includes additional cluster metadata, such as the Optimize Live Agent and Kubernetes versions.

Available output formats

Multiple output formats are supported, including json and yaml. Different output formats return varying levels of detail.

View cluster details

Command:

stormforge get clusters <cluster> -o yaml

Example output:

_metadata: ...
name: <cluster>
stormforge:
  products:
  - name: optimize-live
  - name: stormforge-agent
    version: 2.27.2
  - name: stormforge-applier
    version: 2.12.0
kubernetes:
  version: 1.34.0
nodes: ...
status: ...

The yaml output includes node details, Kubernetes version, and StormForge cluster metadata.

List workloads in a cluster

Command:

stormforge get workloads --cluster <cluster> -o wide

Example output:

CLUSTER     NAMESPACE     TYPE              NAME           AUTO DEPLOY   HPA ENABLED   STATE     AGE
<cluster>   <namespace>   <resource-type>   <workload-1>   false         false         Created   3 hours
<cluster>   <namespace>   <resource-type>   <workload-2>   false         false         Created   3 hours

Cluster requirement for listing workloads

Running stormforge get workloads without specifying a cluster returns an error.

View detailed workload information

Command:

stormforge get workloads \
  --cluster <cluster> \
  --namespace <namespace> \
  --resource <resource-type> \
  --name <workload> \
  -o yaml

Example output:

cluster: <cluster>
resource: <resource-type>
namespace: <namespace>
name: <workload>
labels: ...
annotations: ...
learningPeriod: P1D
recommendationHandlers: ...
patchTarget: ...
pods: ...
status: ...

Specifying --cluster, --namespace, --resource, and --name ensures the expected workload is returned. Workloads with the same name can exist across multiple resource types, namespaces, or clusters.

View under- or over-provisioned workloads

Command:

stormforge view workloads --cluster <cluster> --over-provisioned

Example output:

WORKLOAD NAME   CLUSTER     NAMESPACE     TYPE              STATUS   OOM RATE   SCORE   NET IMPACT (CPU/MEMORY)
<workload>      <cluster>   <namespace>   <resource-type>   Ready    0          13      -$4.39/mo. (-0.180/-76MiB)

The stormforge view command returns recommendations ordered by impact. Filter using the --over-provisioned and --under-provisioned flags.

View and generate recommendations

Inspect recommendation status and generate recommendations on demand.

View recommendation status

Command:

stormforge get recommendations --cluster <cluster> --name <workload> -o wide

Example output:

CLUSTER      NAMESPACE    TYPE              NAME         TIMESTAMP    SCORE   NET IMPACT (CPU/MEMORY)    STATE       STATUS
<cluster>   <namespace>   <resource-type>   <workload>   1772819220   84      $1.80/mo. (0.087/-64MiB)   Generated   Learning

Returns recommendation data, including resource usage, requests and limits, and the net impact of applying a recommendation.

The net impact displays as a dollar amount determined by the configured cost per hour for CPU and RAM.

This generated recommendation is for a workload in the learning period. The optimization score of 84 indicates that the workload is close to optimal size.

View recommendation details

Command:

stormforge get recommendations --cluster <cluster> --name <workload> -o yaml

View the example output

name: "1772819220"
workload:
  cluster: <cluster>
  namespace: <namespace>
  name: <workload>
timestamp: "2026-03-06T17:47:00Z"
pods:
- observed:
    metrics:
      containerResources:
      - containerName: <container>
        usage:
          cpu: 0.11
          memory: 4012426
        requests:
          cpu: 0.5
          memory: 134217728
    values:
      containerResources:
      - containerName: <container>
        requests:
          cpu: 500m
          memory: 128Mi
        limits:
          cpu: 1
          memory: 128Mi
  recommended:
    values:
      containerResources:
      - containerName: <container>
        requests:
          cpu: 577m
          memory: 32Mi
        limits:
          cpu: 1154m
          memory: 128Mi

The yaml output provides additional information, including observed usage, current requests and limits, and recommended requests and limits.

Focus on the observed and recommended sections to compare existing and optimized resources.

Recommendations reflect point-in-time data

A recommendation contains data from the time it was generated. Running stormforge get recommendations doesn’t show the current workload usage.

Locate recommendations that failed to generate

Command:

stormforge get recommendations --cluster <cluster> --state FailedToGenerate

Example output:

CLUSTER     NAMESPACE     TYPE              NAME         TIMESTAMP    SCORE   NET IMPACT (CPU/MEMORY)   STATE
<cluster>   <namespace>   <resource-type>   <workload>   1772794020           -- (--/--)                FailedToGenerate

Optimize Live can fail to generate a recommendation if, for example, a workload lacks recent usage data or is scaled to zero more than 75% of the time. Use the --state flag to list recommendations in the FailedToGenerate state.

In this example, Optimize Live was unable to generate a recommendation due to insufficient recent usage data.

Generate a recommendation

Command:

stormforge create recommendation --cluster <cluster> --namespace <namespace> --resource <resource-type> --name <workload> --wait

Example output:

recommendation "<cluster>/<namespace>/<resource-type>/<workload>/<recommendation>" created.

You can generate a recommendation on demand using the CLI (or the UI), rather than waiting for the next scheduled run.

Using the --wait flag forces the CLI to wait until the recommendation has been generated before returning a result.

Query recommendation data

Use the jq tool with JSON-formatted output to extract and analyze specific recommendation fields.

Recommendations reflect point-in-time data

Any observed data reflects usage at the time the recommendation was generated.

Show observed usage for each container in a workload

Command:

stormforge get recommendations <cluster>/<namespace>/<resource-type>/<workload> -o json | jq '.results[].pods[].observed.metrics'

View the example output

{
  "containerResources": [
    {
      "containerName": "<container-1>",
      "usage": {
        "cpu": 0,
        "memory": 124995
      }
    },
    {
      "containerName": "<container-2>",
      "usage": {
        "cpu": 0.10,
        "memory": 4209629
      },
      "requests": {
        "cpu": 0.5,
        "memory": 134217728
      }
    }
  ]
}

Filtering CLI output with paths and flags

The StormForge CLI supports filtering by providing a path, such as <cluster>/<namespace>/<resource-type>/<workload> in this example, as well as flags such as --cluster <cluster> --namespace <namespace> --resource <resource-type> --name <workload>.

Show current request and limit values

Command:

stormforge get recommendations <cluster>/<namespace>/<resource-type>/<workload> -o json | jq '.results[].pods[].observed.values'

Example output:

{
  "containerResources": [
    {
      "containerName": "<container>",
      "requests": {
        "cpu": "500m",
        "memory": "128Mi"
      },
      "limits": {
        "cpu": "1",
        "memory": "128Mi"
      }
    }
  ]
}

Show recommended request and limit values

Command:

stormforge get recommendations <cluster>/<namespace>/<resource-type>/<workload> -o json | jq '.results[].pods[].recommended'

View the example output

{
  "values": {
    "containerResources": [
      {
        "containerName": "<container>",
        "requests": {
          "cpu": "577m",
          "memory": "32Mi"
        },
        "limits": {
          "cpu": "1154m",
          "memory": "128Mi"
        }
      }
    ],
    "scheduling": {
      "categories": [
        "compute-optimized"
      ]
    }
  }
}

Scheduling and node affinity

This example includes the compute-optimized scheduling category. See the Pod scheduling documentation for details on node affinity.

Show recommendations for all optimization goals

Command:

stormforge get recommendations <cluster>/<namespace>/<resource-type>/<workload> -o json | jq '.results[].pods[].effective'

View the example output

[
  {
    "goal": "savings",
    "values": {
      "containerResources": [
        {
          "containerName": "<container>",
          "requests": {
            "cpu": "577m",
            "memory": "32Mi"
          },
          "limits": {
            "cpu": "1154m",
            "memory": "128Mi"
          }
        }
      ]
    }
  },
  {
    "goal": "balanced",
    "values": {
      "containerResources": [
        {
          "containerName": "<container>",
          "requests": {
            "cpu": "577m",
            "memory": "32Mi"
          },
          "limits": {
            "cpu": "1154m",
            "memory": "128Mi"
          }
        }
      ]
    }
  },
  {
    "goal": "reliability",
    "values": {
      "containerResources": [
        {
          "containerName": "<container>",
          "requests": {
            "cpu": "577m",
            "memory": "32Mi"
          },
          "limits": {
            "cpu": "1154m",
            "memory": "128Mi"
          }
        }
      ]
    }
  }
]

A resource’s optimization goal indicates which of two competing criteria to maximize when computing recommended request values: cost savings or workload reliability.

Optimize Live always produces values that satisfy both criteria, but goal-setting can shift the balance toward one or the other.

The available goals are Balanced (default), Savings, and Reliability. Per-container values display recommendations for all goals.

This can provide a helpful comparison to see what Optimize Live would recommend for a different goal.

Apply recommendations

The stormforge create and stormforge apply commands can both apply recommendations.

Create and apply

Command:

stormforge create recommendation \
  --namespace <namespace> \
  --resource <resource-type> \
  --name <workload> \
  --auto-deploy \
  --wait

Example output:

recommendation "<cluster-1>/<namespace>/<resource-type>/<workload>/<recommendation>" applied.
recommendation "<cluster-2>/<namespace>/<resource-type>/<workload>/<recommendation>" applied.

Use the stormforge create command with the --auto-deploy flag to create and automatically apply a recommendation.

In this example, a cluster name isn’t supplied. The recommendation is applied to matching workloads across all clusters.

Apply the latest recommendation

First, check for recommendations.

Command:

stormforge get recommendations --cluster <cluster> --namespace <namespace> --state Generated

Then, apply the latest recommendation.

Command:

stormforge apply --cluster <cluster> --namespace <namespace> --resource <resource-type> --name <workload>

Example output:

recommendation "<cluster>/<namespace>/<resource-type>/<workload>/<recommendation>" applied.

Applies the most recently generated recommendation to the specified workload.

Create with a validity period and apply

Command:

stormforge create recommendation \
  --cluster <cluster> \
  --namespace <namespace> \
  --resource <resource-type> \
  --name <workload> \
  --valid-for P7D \
  --auto-deploy \
  --wait

Example output:

recommendation "<cluster>/<namespace>/<resource-type>/<workload>/<recommendation>" applied.

Creates and automatically deploys a recommendation that remains valid for 7 days.

Next steps

View the full StormForge CLI command reference

Last modified March 24, 2026