Install

clusterctl is one static binary. It needs no interpreter, no virtual environment and nothing installed on the nodes.

With mise

mise installs from the release assets, picks the build for your platform, and checks the download against the release checksums and the build provenance attestation:

$ mise use -g github:GSI-HPC/clusterctl
$ clusterctl version

mise leaves a release alone for its first 24 hours (its minimum_release_age setting), so on the day of a release it reports “no versions found … matching date filter” or picks the previous one. Name the version to take it sooner:

$ mise use -g github:GSI-HPC/clusterctl@1.4.0

Pin a version for a team by putting it in the project’s mise.toml:

[tools]
"github:GSI-HPC/clusterctl" = "1.4.0"

mise install then gives everyone the same binary, and mise lock records the digest so a later install is checked against it:

$ mise lock
$ git add mise.toml mise.lock

From a release

Download the archive under its own name, together with checksums.txt:

$ base=https://github.com/GSI-HPC/clusterctl/releases/latest/download
$ curl -fsSL --remote-name-all "$base/clusterctl_linux_amd64.tar.gz" "$base/checksums.txt"

Verify it before installing, against the checksums and against its build provenance attestation, which says which workflow, commit and tag produced it:

$ sha256sum -c checksums.txt --ignore-missing
$ gh attestation verify clusterctl_linux_amd64.tar.gz --repo GSI-HPC/clusterctl

Then install it:

$ tar xzf clusterctl_linux_amd64.tar.gz
$ install -m 0755 clusterctl ~/.local/bin/
$ clusterctl version

The checksum answers “are these the published bytes”; the attestation answers “who published them, from what”. A download is worth both.

Archives exist for linux_amd64, linux_arm64, darwin_amd64 and darwin_arm64.

From source

$ go install github.com/GSI-HPC/clusterctl/cmd/clusterctl@latest

Go 1.26 or newer. An older toolchain downloads the right one by itself.

A build from source reports its revision rather than a version, because the version of a release lives only in its signed tag:

$ clusterctl version
devel (a1b2c3d4e5f6) built 2026-09-22T14:42:30Z go1.26.0 linux/amd64

What has to be on the other end

clusterctl installs nothing on your hosts, but it does run programs there.

On your workstation: an OpenSSH client, and sshuttle if the site uses tunnels.

On the infrastructure hosts, depending on which roles a site configures:

clusterctl doctor --remote checks all of it and says what is missing.

Shell completion

$ clusterctl completion bash > /etc/bash_completion.d/clusterctl
$ clusterctl completion zsh  > "${fpath[1]}/_clusterctl"
$ clusterctl completion fish > ~/.config/fish/completions/clusterctl.fish

Completion knows your configuration: -n offers the groups your site defines and --context offers your contexts.