Last modified May 30, 2023

gsctl CLI reference

gsctl is the command line utility to manage your Giant Swarm clusters.

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.

Commands

Follow the links below for a detailed documentation, where available. You can also always use gsctl <command> --help.

Command	Description
`completion`	Create completion scripts for Bash and Zsh
`create cluster`	Create a new cluster
`create keypair`	Create and download new key pair
`create kubeconfig`	Create/download new key pair and update `kubectl` configuration
`create nodepool`	Create a new node pool
`delete cluster`	Delete a cluster
`delete nodepool`	Delete a node pool
`delete endpoint`	Delete endpoint
`info`	Print information on status, configuration, and the installation
`list endpoints`	List endpoints
`list clusters`	List clusters
`list organizations`	List organizations
`list keypairs`	List key pairs
`list nodepools`	List node pools
`list releases`	List workload cluster releases
`login`	Sign in as a user
`logout`	Sign out
`ping`	Check API connection
`scale cluster`	Add or remove worker nodes of a KVM cluster
`select endpoint`	Select an endpoint
`show cluster`	Show cluster details
`show nodepool`	Show node pool details
`show release`	Show details on a workload cluster release
`update cluster`	Modify cluster details (name, labels)
`update nodepool`	Modify (rename, scale) a node pool
`update organization set-credentials`	Set provider credentials for an organization
`upgrade cluster`	Upgrade a cluster

For finding out which version of gsctl you currently have installed, and other useful information about the build, use the gsctl --version command.

Installing and updating

gsctl comes as a self-contained binary for Mac, Linux, and Windows. Below you find installation instructions for different platforms. If you want to build gsctl from source, find everything you need in its GitHub repository.

The current gsctl version is null. Find details in the release notes.

Homebrew provides the most convenient way to install gsctl and keep it up to date. To install, use this command:

brew tap giantswarm/giantswarm
brew install gsctl

For updating:

brew upgrade gsctl

To install without homebrew, download the latest release from GitHub, unpack the binary and move it to a location covered by your PATH environment variable.

Arch Linux

gsctl can be installed using an AUR helper, such as yay or pacaur:

yay -S gsctl-bin

Other distributions

Download the latest release from GitHub, unpack the binary and move it to a location covered by your PATH environment variable.

scoop enables convenient installs and updates for Windows PowerShell users. Before you can install gsctl for the first time, execute this:

scoop bucket add giantswarm https://github.com/giantswarm/scoop-bucket.git

To install:

scoop install gsctl

To update:

scoop update gsctl

To install without scoop, download the latest release from GitHub, unpack the binary and move it to a location covered by your PATH environment variable.

Configuration

gsctl keeps its own settings under $HOME/.config/gsctl/. There is a configuration file called config.yaml. Key pairs are stored in the certs subdirectory.

The following environment variables can be used to affect some behavior:

GSCTL_CONFIG_DIR: Path to the gsctl configuration directory.
GSCTL_ENDPOINT: This can be used to specify an API endpoint URL.
GSCTL_AUTH_TOKEN: This can be used to specify an authentication token.
GSCTL_CAFILE: If your Giant Swarm REST API endpoint uses a certificate signed by an authority not known to your operating system, this variable can be set to the path of a custom CA (certification authority) bundle. A CA bundle is a text file containing one or more CA certificates in PEM format.
GSCTL_CAPATH: Similar to GSCTL_CAFILE, but GSCTL_CAPATH is expected to point to a directory containing one or more PEM files.
GSCTL_DISABLE_COLORS: When this variable is set to any non-empty string, all terminal output will be monochrome.
GSCTL_DISABLE_CMDLINE_TRACKING: When this variable is set to any non-empty string, command lines won’t be submitted to the API. Otherwise, command lines are submitted to learn about the tool’s usage and find ways to improve.
HTTP_PROXY, HTTPS_PROXY and NO_PROXY can be used to define proxy server usage as detailed in the Go net/http ProxyFromEnvironment docs.

In addition, global command-line options are available.

Known bugs and limitations

Check our issues with label kind/bug.

Changelog

You’ll find info on changes in the release description.

Feedback

We welcome your feedback on gsctl. If you feel like sharing openly, use the GitHub repository and create an issue, so other users can participate. Otherwise, please use the common Giant Swarm support channels.

Need help, got feedback?

We listen to your Slack support channel. You can also reach us at support@giantswarm.io. And of course, we welcome your pull requests!