fix(cli): list self-hosted cluster registrations

Add an explicit ICMS-backed registration list command that uses the admin JWT, and update the self-hosted documentation and embedded agent skill to use it.

Closes #1197

Signed-off-by: Mike Camp <mcamp@nvidia.com>

Author: mikeyrcamp

ai-tooling/user/skills/nvcf-self-managed-cli/SKILL.md

@@ -91,7 +91,7 @@ nvcf-cli self-hosted uninstall --no-apply --compute-plane --cluster-name=ncp-loc
 
 | Env var | Token type | Used by |
 |---|---|---|
-| `NVCF_TOKEN` | Admin JWT | `function create` / `deploy` / `update` / `delete`, cluster management (`cluster register`/`rotate`/`delete`, `self-hosted` ops). Required for admin commands; preferred for the rest. |
+| `NVCF_TOKEN` | Admin JWT | `function create` / `deploy` / `update` / `delete`, cluster management (`cluster register`/`registration list`/`rotate`/`delete`, `self-hosted` ops). Required for admin commands; preferred for the rest. |
 | `NVCF_API_KEY` | `nvapi-...` API key | `function invoke` / `list` / `get`, queue details. Falls back to `NVCF_TOKEN` when unset. |
 
 Token generation flow:
@@ -148,6 +148,7 @@ After `init`, the credentials live in `~/.nvcf-cli.state`, so later commands wor
 | `nvcf-cli self-hosted status [--cluster-name=X] [--watch] [--json]` | Snapshot dashboard of cluster identity + component health + recent events | Routine health checks; `--watch` for live |
 | `nvcf-cli init` | Mint admin token from API Keys service via the public api gateway | Before any cluster-management operation; idempotent |
 | `nvcf-cli cluster register --name=X --nca-id=Y --region=Z [--ignore-existing]` | Register a cluster JWKS+OIDC issuer with ICMS | Standalone register (without compute-plane install) |
+| `nvcf-cli cluster registration list --nca-id=Y [--icms-url=URL]` | List self-hosted cluster registrations from ICMS | Check registered compute-plane names and IDs with the admin token |
 | `nvcf-cli cluster rotate --cluster-id=ID` | Rotate cluster JWKS in ICMS | When NVCA's K8s signing key changed and PSAT verification started 401-ing |
 | `nvcf-cli cluster delete --cluster-id=ID` | Remove cluster registration from ICMS | **Confirm with user.** Destroys ICMS state for the cluster. |
 | `nvcf-cli api-key generate --description="…" --expires-in=1h` | Mint both a function API key and a task API key (default) | Before invoking functions or creating tasks; run after every `init` |
@@ -212,7 +213,7 @@ For step-by-step playbooks, load the prompt that matches the user's intent:
 - `nvcf-cli self-hosted down` or `uninstall` in any form — destructive. **ALWAYS run with `--plan-only` (`down`) or `--no-apply` (`uninstall`) first** and show the user what would happen. State which compute plane(s) and whether persistent state would be wiped.
 - `nvcf-cli self-hosted down --remove-persistent` (or `uninstall --remove-persistent`) — deletes Cassandra rows, OpenBao seal keys, sr-default user data. **Loss is unrecoverable.** Confirm explicitly that this is what the user wants.
 - `nvcf-cli self-hosted uninstall --control-plane --force-with-registered-clusters` — orphans every registered compute plane (PSAT auth breaks immediately). State the consequence before passing this flag.
-- `nvcf-cli self-hosted down --all` — nukes everything. Always show the cluster list (`nvcf-cli cluster list`) and get confirmation.
+- `nvcf-cli self-hosted down --all` nukes everything. Always show the registered clusters (`nvcf-cli cluster registration list --nca-id=<nca-id>`) and get confirmation.
 - `nvcf-cli cluster delete` — removes the cluster's ICMS registration; the compute plane immediately stops being able to authenticate.
 - `nvcf-cli function delete` — removes a function and any active deployment.
 - `nvcf-cli task delete` — permanently removes the task record. Stop, state the task ID and current status, then wait for a subsequent user reply that explicitly confirms deletion of that specific task before running this command. Do not treat the user's original delete request as confirmation.
@@ -223,7 +224,7 @@ For step-by-step playbooks, load the prompt that matches the user's intent:
 - Run `nvcf-cli self-hosted status` before assuming a cluster exists / is healthy.
 - Show the planned action (cluster name, function name, GPU type, cost if known) before creating.
 - Before creating or deploying a container or LLM function, confirm the exact function name and container image with the user. For LLM functions, also confirm the exact model name used in `models[].name` and OpenAI `model: "<function-id>/<model-name>"`. If any value is missing, ask the user instead of guessing or submitting example placeholders.
-- Confirm exact resource names before deletion — match against `cluster list` / `function list` output.
+- Confirm exact resource names before deletion. Match against `cluster registration list` / `function list` output.
 - In CI / non-interactive contexts, use `--non-interactive --token=$JWT`. Never propose interactive `nvcf-cli init` when `$CI` is set.
 
 **NEVER paste these into chat / logs / feedback:**
@@ -285,6 +286,7 @@ nvcf-cli self-hosted status                   # snapshot
 nvcf-cli self-hosted status --watch           # live
 nvcf-cli init                                 # mint admin token (clears all saved API keys)
 nvcf-cli cluster register …                   # register cluster
+nvcf-cli cluster registration list --nca-id=<nca-id> # list self-hosted registrations
 nvcf-cli api-key generate --description=…     # mint both function and task API keys (run after every init)
 nvcf-cli api-key generate --for function …    # function key only
 nvcf-cli api-key generate --for task …        # task key only

ai-tooling/user/skills/nvcf-self-managed-cli/examples/multi-cluster.md

@@ -24,7 +24,8 @@ for CTX in admin@gpu-east-1 admin@gpu-west-1 admin@gpu-eu-1; do
 done
 
 # 3. Verify all compute planes registered:
-nvcf-cli cluster list --json | jq '.clusters[] | {name, region, lastHeartbeat}'
+nvcf-cli cluster registration list --nca-id=$NCA_ID --icms-url=$ICMS --json \
+  | jq '.clusters[] | {name: .clusterName, status, nvcaVersion}'
 ```
 
 ## Compute-plane-only operator scenario
@@ -80,7 +81,8 @@ The `clusters` array (using cluster names, not IDs) limits scheduling to those c
 
 ```sh
 # List all registered compute planes:
-nvcf-cli cluster list --json | jq -r '.clusters[].name' > clusters.txt
+nvcf-cli cluster registration list --nca-id=$NCA_ID --icms-url=$ICMS --json \
+  | jq -r '.clusters[].clusterName' > clusters.txt
 
 # Status snapshot per compute plane (assuming each context name matches):
 while read NAME; do

ai-tooling/user/skills/nvcf-self-managed-cli/prompts/add-compute-plane.md

@@ -7,7 +7,7 @@ User has a working NVCF control plane (running somewhere) and wants to register
 - **kubectl context for the new compute plane** in their `KUBECONFIG`.
 - **Public ICMS URL** of the existing control plane (e.g. `https://icms.nvcf.example.com`).
 - **Admin JWT** for the control plane's account, OR ability to mint one via `nvcf-cli init` against the control plane's public api endpoint. (Admin tokens come from the API Keys service via the public api gateway — kubectl access to the control plane is NOT required to obtain one.)
-- **A unique `--cluster-name`** that doesn't collide with already-registered clusters. Use `nvcf-cli cluster list` from a control-plane context to check.
+- A unique `--cluster-name` that doesn't collide with already-registered clusters. Use `nvcf-cli cluster registration list --nca-id=$NCA_ID --icms-url=$ICMS` to check.
 
 ## Steps
 
@@ -53,4 +53,4 @@ User has a working NVCF control plane (running somewhere) and wants to register
 - **Re-registering the same cluster** (re-running on the same compute plane that was previously registered): expected, no-op semantics.
 - **Different physical cluster but same name**: the second attempt will reuse the ICMS row, but the new compute plane's JWKS will be silently *replaced* — the old compute plane's NVCA agent will start failing PSAT auth. **Confirm with the user** that they meant to overwrite.
 
-When in doubt, run `nvcf-cli cluster list` first and ask the user before proceeding with a name that already exists.
+When in doubt, run `nvcf-cli cluster registration list --nca-id=$NCA_ID --icms-url=$ICMS` first and ask the user before proceeding with a name that already exists.

ai-tooling/user/skills/nvcf-self-managed-cli/prompts/rotate-cluster-jwks.md

@@ -10,7 +10,7 @@ User says NVCA stopped authenticating, or PSAT auth is 401-ing against ICMS. The
 
 ## Steps
 
-1. **Confirm the cluster ID.** `nvcf-cli cluster list` (against the control plane). Identify the row matching the user's compute plane.
+1. Confirm the cluster ID. Run `nvcf-cli cluster registration list --nca-id=$NCA_ID --icms-url=$ICMS`. Identify the row matching the user's compute plane.
 
 2. **Rotate.** From a context that can reach the compute plane's K8s API (because rotation re-fetches the K8s API's `/openid/v1/jwks`):
 

ai-tooling/user/skills/nvcf-self-managed-cli/reference/commands.md

@@ -28,7 +28,7 @@ Full subcommand list. Always pair with [flags.md](flags.md) for global flags and
 | Command | Purpose | Notes |
 |---|---|---|
 | `cluster register --name=X --nca-id=Y [--region=Z] [--ignore-existing]` | Register a JWKS+OIDC with ICMS | Used by `up` Phase 5 internally; standalone for manual registration |
-| `cluster list` | List registered clusters | Output is YAML by default; `--json` for machine |
+| `cluster registration list --nca-id=Y [--icms-url=URL]` | List self-hosted cluster registrations from ICMS | Uses the admin token; `--json` for machine-readable output |
 | `cluster rotate --cluster-id=ID` | Re-fetch JWKS from K8s and PUT to ICMS | After K8s API server signing key rotation |
 | `cluster delete --cluster-id=ID` | Remove ICMS row | **DESTRUCTIVE: confirm with user** |
 

docs/user/cli.md

@@ -547,6 +547,18 @@ overrides (`selfManaged.icmsServiceHostHeaderOverride`,
 values. See [self-managed-clusters](./cluster-management/self-managed.md) for how the
 register values feed the operator install and when host-header overrides are required.
 
+List the self-hosted cluster registrations stored in ICMS with the admin token:
+
+```bash
+./nvcf-cli cluster registration list \
+  --nca-id <nca-id> \
+  --icms-url "http://<GATEWAY_ADDR>"
+```
+
+Use `--json` for machine-readable output. `cluster registration list` is distinct
+from `cluster list`, which lists NVCF cluster groups and requires API credentials
+with the corresponding NVCF API scope.
+
 ### General Commands
 
 | Command | Description |
@@ -1072,7 +1084,7 @@ Registry credential changes take up to about 5 minutes to take effect for task c
 | `function list`, `function list-ids`, `function list-versions`, `function get` | `NVCF_TOKEN` or `NVCF_API_KEY` | `list_functions` or `list_functions_details` | `NVCF_API_KEY` |
 | `function queue status`, `function queue position`, `function queue details` | `NVCF_TOKEN` or `NVCF_API_KEY` | `queue_details` | `NVCF_API_KEY` |
 | `registry-credential` commands | `NVCF_TOKEN` or `NVCF_API_KEY` | `manage_registry_credentials` | `NVCF_TOKEN` |
-| Self-hosted cluster register, list, rotate, delete | `NVCF_TOKEN` | `cluster-management` | `NVCF_TOKEN` |
+| Self-hosted cluster register, registration list, rotate, delete | `NVCF_TOKEN` | `cluster-management` | `NVCF_TOKEN` |
 | `task create` | `NVCF_NVCT_API_KEY` | `launch_task` | `NVCF_NVCT_API_KEY` |
 | `task list` | `NVCF_NVCT_API_KEY` | `list_tasks` | `NVCF_NVCT_API_KEY` |
 | `task get` | `NVCF_NVCT_API_KEY` | `task_details` | `NVCF_NVCT_API_KEY` |

src/clis/nvcf-cli/cmd/BUILD.bazel

@@ -27,6 +27,7 @@ go_library(
         "cluster_agent_validate.go",
         "cluster_dump.go",
         "cluster_registration.go",
+        "cluster_registration_list.go",
         "cluster_utils.go",
         "deploy.go",
         "exit_code_error.go",
@@ -108,6 +109,7 @@ go_test(
         "cluster_agent_test.go",
         "cluster_agent_validate_test.go",
         "cluster_dump_test.go",
+        "cluster_registration_list_test.go",
         "cluster_registration_test.go",
         "deploy_test.go",
         "exit_code_error_test.go",

src/clis/nvcf-cli/cmd/cluster.go

@@ -34,7 +34,8 @@ var clusterCmd = &cobra.Command{
 	Long: `Manage and query cluster resources and GPU availability.
 
 Available subcommands:
-- list: List available cluster groups`,
+- list: List available cluster groups
+- registration: Manage self-hosted cluster registrations`,
 }
 
 var clusterListCmd = &cobra.Command{

src/clis/nvcf-cli/cmd/cluster_registration.go

@@ -86,6 +86,11 @@ func initClusterRegistrationCmds() {
 	clusterCmd.AddCommand(clusterRegisterCmd)
 	clusterCmd.AddCommand(clusterRotateCmd)
 	clusterCmd.AddCommand(clusterDeleteCmd)
+	clusterCmd.AddCommand(clusterRegistrationCmd)
+	clusterRegistrationCmd.AddCommand(clusterRegistrationListCmd)
+	clusterRegistrationListCmd.Flags().String(clusterFlagNcaID, "", "NCA/tenant ID (required)")
+	addClusterICMSURLFlags(clusterRegistrationListCmd)
+	_ = clusterRegistrationListCmd.MarkFlagRequired(clusterFlagNcaID)
 
 	// Register flags
 	clusterRegisterCmd.Flags().String("name", "", "Cluster name (required)")

src/clis/nvcf-cli/cmd/cluster_registration_list.go

@@ -0,0 +1,92 @@
+/*
+SPDX-FileCopyrightText: Copyright (c) NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package cmd
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"nvcf-cli/internal/client"
+
+	"github.com/spf13/cobra"
+)
+
+var clusterRegistrationCmd = &cobra.Command{
+	Use:          "registration",
+	Short:        "Manage self-hosted cluster registrations",
+	SilenceUsage: true,
+}
+
+var clusterRegistrationListCmd = &cobra.Command{
+	Use:          "list",
+	Short:        "List self-hosted cluster registrations from ICMS",
+	SilenceUsage: true,
+	RunE:         runClusterRegistrationList,
+}
+
+func runClusterRegistrationList(cmd *cobra.Command, _ []string) error {
+	ncaID, _ := cmd.Flags().GetString(clusterFlagNcaID)
+
+	config, err := client.LoadConfig()
+	if err != nil {
+		return fmt.Errorf(errFailedToLoadConfig, err)
+	}
+	if err := requireAdminToken(config); err != nil {
+		return err
+	}
+
+	c, err := client.NewClient(config)
+	if err != nil {
+		return fmt.Errorf(errFailedToCreateClient, err)
+	}
+	defer c.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), config.DefaultTimeout)
+	defer cancel()
+
+	clusters, err := c.ListClusters(ctx, getICMSURL(cmd, config), ncaID)
+	if err != nil {
+		return fmt.Errorf("failed to list registered clusters from ICMS: %w", err)
+	}
+
+	if jsonOutput {
+		return json.NewEncoder(cmd.OutOrStdout()).Encode(map[string]interface{}{"clusters": clusters})
+	}
+
+	if len(clusters) == 0 {
+		fmt.Fprintln(cmd.OutOrStdout(), "No registered clusters found.")
+		return nil
+	}
+
+	fmt.Fprintf(cmd.OutOrStdout(), "Found %d registered cluster(s):\n\n", len(clusters))
+	for _, cluster := range clusters {
+		fmt.Fprintf(cmd.OutOrStdout(), "Name: %s\n", cluster.ClusterName)
+		fmt.Fprintf(cmd.OutOrStdout(), "ID: %s\n", cluster.ClusterID)
+		fmt.Fprintf(cmd.OutOrStdout(), "Cluster Group ID: %s\n", cluster.ClusterGroupID)
+		if cluster.ClusterStatus != "" {
+			fmt.Fprintf(cmd.OutOrStdout(), "Status: %s\n", cluster.ClusterStatus)
+		}
+		if cluster.NVCAVersion != "" {
+			fmt.Fprintf(cmd.OutOrStdout(), "NVCA Version: %s\n", cluster.NVCAVersion)
+		}
+		fmt.Fprintln(cmd.OutOrStdout(), "---")
+	}
+
+	return nil
+}