# Common StormForge CLI workflows > Common StormForge CLI tasks, from authentication to managing recommendations --- Site [llms.txt](/llms.txt) --- The StormForge CLI lets you interact with StormForge to inspect workloads, view optimization data, and manage recommendations. This guide covers common workflows: - Authenticate and configure the CLI - Explore clusters and workloads - Find workloads with auto-deploy enabled - View and generate recommendations - Query recommendation data - Apply recommendations to workloads Typical workflow: ``` Identify workload → Inspect recommendation → Apply recommendation ``` Common workflow commands: ```sh stormforge get workloads --cluster stormforge get recommendations --cluster --namespace --name stormforge apply --cluster --namespace --resource --name ``` --- ## In this guide - [Common commands](#common-commands) - [Get started with the CLI](#get-started) - [Explore clusters and workloads](#explore) - [Find workloads with auto-deploy enabled](#find-auto-deploy) - [View and generate recommendations](#view-recs) - [Query recommendation data](#query-recs) - [Apply recommendations](#apply-recs) ## Common commands {#common-commands} | Task | Command | | --------------------- | ----------------------------------------------------------- | | Authenticate | [`stormforge login`][stormforge-login] | | List clusters | [`stormforge get clusters`][stormforge-clusters] | | List workloads | [`stormforge get workloads`][stormforge-get-workloads] | | View workloads | [`stormforge view workloads`][stormforge-view-workloads] | | List recommendations | [`stormforge get recommendations`][stormforge-get-recs] | | Create recommendation | [`stormforge create recommendation`][stormforge-create-rec] | | Apply recommendations | [`stormforge apply`][stormforge-apply] | ## Get started with the CLI {#get-started} Authenticate and configure the StormForge CLI. ### Authenticate Command: ```sh stormforge login ``` Example output: ```sh You are now logged in. ``` Opens a browser window and authenticates using your StormForge account. ### Get the CLI version Command: ```sh stormforge version ``` Example output: ```sh stormforge version 6.1.1 ``` Displays the installed StormForge CLI version. ### Set up autocompletion Command: ```sh 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 {#explore} Retrieve cluster and workload information. ### List clusters Command: ```sh stormforge get clusters -o wide ``` Example output: ```sh NAME AGENT VERSION APPLIER VERSION KUBERNETES VERSION STATE AGE 2.27.2 2.12.0 1.34.0 Created 3 hours ``` The `wide` output option includes additional cluster metadata, such as the StormForge Agent and Kubernetes versions. ### View cluster details Command: ```sh stormforge get clusters -o yaml ``` Example output: ```yaml _metadata: ... name: stormforge: products: - 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: ```sh stormforge get workloads --cluster -o wide ``` Example output: ```sh CLUSTER NAMESPACE TYPE NAME AUTO DEPLOY HPA ENABLED GPU ENABLED STATE AGE false false false Created 3 hours false false false Created 3 hours ``` The `wide` output includes the `AUTO DEPLOY`, `HPA ENABLED`, and `GPU ENABLED` status columns for each workload. ### View detailed workload information Command: ```sh stormforge get workloads \ --cluster \ --namespace \ --resource \ --name \ -o yaml ``` Example output: ```yaml cluster: resource: namespace: name: 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: ```sh stormforge view workloads --cluster --over-provisioned ``` Example output: ```sh WORKLOAD NAME CLUSTER NAMESPACE TYPE STATUS OOM RATE SCORE NET IMPACT (CPU/MEMORY) 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 GPU workloads Command: ```sh stormforge view workloads --cluster --gpu ``` The `--gpu` flag returns workloads that StormForge identifies as using GPUs. It requires StormForge CLI version 6.2.8 or later. ### Sort workloads by auto-deploy status Command: ```sh stormforge get workloads \ --cluster \ --sort-by auto_deploy \ -o wide ``` Example output: ```sh CLUSTER NAMESPACE TYPE NAME AUTO DEPLOY HPA ENABLED GPU ENABLED STATE AGE false true false Created 3 weeks false false false Created 3 weeks true false false Created 3 weeks ``` Sorting by `auto_deploy` groups workloads by their auto-deploy status. ## Find workloads with auto-deploy enabled {#find-auto-deploy} Identify workloads with auto-deploy enabled across your environment. ### List auto-deploy-enabled workloads in a cluster Command: ```sh stormforge view workloads --cluster --auto-deploy ``` Example output: ```sh WORKLOAD NAME CLUSTER NAMESPACE TYPE STATUS OOM RATE SCORE NET IMPACT (CPU/MEMORY) Ready 0 91 -$2.10/mo. (-0.095/-48MiB) Ready 0 78 -$0.84/mo. (-0.040/-20MiB) ``` The `--auto-deploy` flag returns workloads configured to have recommendations applied automatically. ### Filter by namespace Command: ```sh stormforge view workloads \ --cluster \ --namespace \ --auto-deploy ``` Combines `--namespace` and `--auto-deploy` flags to return results for a single namespace in a cluster. ### Filter with field-selector when piping to jq Use `--field-selector auto_deploy=true` with `stormforge get workloads` to reduce the JSON blob before passing it to `jq` or other tools. The `--field-selector` flag filters on any sortable column (see `--sort-by` in the [CLI reference][stormforge-get-workloads]). Command: ```sh stormforge get workloads \ --cluster \ --field-selector auto_deploy=true \ -o json | jq '.results[].name' ``` ## View and generate recommendations {#view-recs} Inspect recommendation status and generate recommendations on demand. ### View recommendation status Command: ```sh stormforge get recommendations --cluster --name -o wide ``` Example output: ```sh CLUSTER NAMESPACE TYPE NAME TIMESTAMP SCORE NET IMPACT (CPU/MEMORY) STATE STATUS 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][learning]. The [optimization score][impact] of 84 indicates that the workload is close to optimal size. ### View recommendation details Command: ```sh stormforge get recommendations --cluster --name -o yaml ```
View the example output ```yaml name: "1772819220" workload: cluster: namespace: name: timestamp: "2026-03-06T17:47:00Z" pods: - observed: metrics: containerResources: - containerName: usage: cpu: 0.11 memory: 4012426 requests: cpu: 0.5 memory: 134217728 values: containerResources: - containerName: requests: cpu: 500m memory: 128Mi limits: cpu: 1 memory: 128Mi recommended: values: containerResources: - containerName: 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. ### Locate recommendations that failed to generate Command: ```sh stormforge get recommendations --cluster --state FailedToGenerate ``` Example output: ```sh CLUSTER NAMESPACE TYPE NAME TIMESTAMP SCORE NET IMPACT (CPU/MEMORY) STATE 1772794020 -- (--/--) FailedToGenerate ``` StormForge can fail to generate a recommendation if, for example, a workload lacks recent usage data. Use the `--state` flag to list recommendations in the `FailedToGenerate` state. In this example, StormForge was unable to generate a recommendation due to insufficient recent usage data. ### Generate a recommendation Command: ```sh stormforge create recommendation --cluster --namespace --resource --name --wait ``` Example output: ```sh recommendation "////" created. ``` You can generate a recommendation on demand using the CLI ([or the UI][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 {#query-recs} Use the [jq] tool with JSON-formatted output to extract and analyze specific recommendation fields. ### Show observed usage for each container in a workload Command: ```sh stormforge get recommendations /// -o json | jq '.results[].pods[].observed.metrics' ```
View the example output ```json { "containerResources": [ { "containerName": "", "usage": { "cpu": 0, "memory": 124995 } }, { "containerName": "", "usage": { "cpu": 0.10, "memory": 4209629 }, "requests": { "cpu": 0.5, "memory": 134217728 } } ] } ```

### Show current request and limit values Command: ```sh stormforge get recommendations /// -o json | jq '.results[].pods[].observed.values' ``` Example output: ```json { "containerResources": [ { "containerName": "", "requests": { "cpu": "500m", "memory": "128Mi" }, "limits": { "cpu": "1", "memory": "128Mi" } } ] } ``` ### Show recommended request and limit values Command: ```sh stormforge get recommendations /// -o json | jq '.results[].pods[].recommended' ```
View the example output ```json { "values": { "containerResources": [ { "containerName": "", "requests": { "cpu": "577m", "memory": "32Mi" }, "limits": { "cpu": "1154m", "memory": "128Mi" } } ], "scheduling": { "categories": [ "compute-optimized" ] } } } ```

### Show recommendations for all optimization goals Command: ```sh stormforge get recommendations /// -o json | jq '.results[].pods[].effective' ```
View the example output ```json [ { "goal": "savings", "values": { "containerResources": [ { "containerName": "", "requests": { "cpu": "577m", "memory": "32Mi" }, "limits": { "cpu": "1154m", "memory": "128Mi" } } ] } }, { "goal": "balanced", "values": { "containerResources": [ { "containerName": "", "requests": { "cpu": "577m", "memory": "32Mi" }, "limits": { "cpu": "1154m", "memory": "128Mi" } } ] } }, { "goal": "reliability", "values": { "containerResources": [ { "containerName": "", "requests": { "cpu": "577m", "memory": "32Mi" }, "limits": { "cpu": "1154m", "memory": "128Mi" } } ] } } ] ```

A resource's [optimization goal][goal] indicates which of two competing criteria to maximize when computing recommended request values: cost savings or workload reliability. StormForge **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 StormForge would recommend for a different goal. ## Apply recommendations {#apply-recs} The `stormforge create` and `stormforge apply` commands can both apply recommendations. ### Create and apply Command: ```sh stormforge create recommendation \ --namespace \ --resource \ --name \ --auto-deploy \ --wait ``` Example output: ```sh recommendation "////" applied. 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: ```sh stormforge get recommendations --cluster --namespace --state Generated ``` Then, apply the latest recommendation. Command: ```sh stormforge apply --cluster --namespace --resource --name ``` Example output: ```sh recommendation "////" applied. ``` Applies the most recently generated recommendation to the specified workload. ### Create with a validity period and apply Command: ```sh stormforge create recommendation \ --cluster \ --namespace \ --resource \ --name \ --valid-for P7D \ --auto-deploy \ --wait ``` Example output: ```sh recommendation "////" applied. ``` Creates and automatically deploys a [recommendation that remains valid][validity] for 7 days. ## Next steps {#next-steps} - View the full [StormForge CLI command reference][stormforge-cli] [goal]: /docs/configure/settings/goal/ [impact]: /docs/recommendations/view/#viewing-the-overall-projected-impact-of-a-recommendation [jq]: https://jqlang.org/ [learning]: /docs/concepts/#learning-period [scheduling]: /docs/recommendations/pod-scheduling/ [stormforge-apply]: /docs/stormforge-cli/reference/#stormforge-apply [stormforge-cli]: /docs/stormforge-cli/reference/ [stormforge-clusters]: /docs/stormforge-cli/reference/#stormforge-get-clusters [stormforge-login]: /docs/stormforge-cli/reference/#stormforge-login [stormforge-create-rec]: /docs/stormforge-cli/reference/#stormforge-create-recommendation [stormforge-get-recs]: /docs/stormforge-cli/reference/#stormforge-get-recommendations [stormforge-get-workloads]: /docs/stormforge-cli/reference/#stormforge-get-workloads [stormforge-view-workloads]: /docs/stormforge-cli/reference/#stormforge-view-workloads [ui]: /docs/recommendations/generate/ [validity]: /docs/concepts/#validity-period