Last modified March 2, 2022

'gsctl list clusters' command reference

gsctl and the REST API are being phased out. We recommend to familiarize yourself with our Management API and the kubectl gs plugin as a future-proof replacement. We provide a migration page to help you with the transition.

The gsctl list clusters command shows all clusters you have access to with a few details like cluster ID, name, creation date, and owner organization.


$ gsctl list clusters
feogv  acme          Staging     3.0.2    25d
pmb9q  acme          Production  3.0.2    21d
z63so  testteam      Dan's Test  2.7.2    13h

The details displayed are:

  • ID: The unique cluster ID.
  • ORGANIZATION: The cluster’s owner organization.
  • NAME: The name selected for the cluster on creation.
  • RELEASE: The version of the workload cluster release used by the cluster. For older clusters, this may be n/a.
  • AGE: How long ago was the cluster created.

The --selector flag can be used to filter the output based on a set of requirements.

$ gsctl list clusters --selector environment=testing
z63so  testteam      Dan's Test  2.7.2    13h

In this example, cluster z63so is the only cluster with label environment=testing. More information about possible queries can be found in the Kubernetes Labels and Selectors documentation.

Argument reference

  • --output or -o: Using this flag with the value json, the output can be printed in JSON format. This is convenient for use in automation. The default output format is table, which results in an output like shown above.
  • --show-deleting: Set this flag to also list clusters that are currently being deleted and add a DELETING SINCE column.
  • --selector or -l: Label selector query to filter clusters on. Accepts a single string containing multiple selector requirements which are comma-separated. In the case of multiple requirements, all must be satisfied so the comma separator acts as a logical AND (&&) operator. This feature is only available for clusters with workload cluster release v10.0.0 and above on AWS.
  • --sort or -s: Sort clusters by one of the columns, in ascending order. The default value is id. Accepted values: id, created, name, organization, release, deleting-since. Providing a small part of the column name is also accepted: d/del/deleting are all valid for the deleting-since value.