tkctx

README

tkctx

A minimal CLI that switches Kubernetes and Talos contexts together. It reads configuration files directly, so kubectl and talosctl are not required at runtime.

Features

• Recursively discovers kubeconfig files under ~/.kube/.
• Recursively discovers talosconfig files under ~/.talos/.
• Switches matching Kubernetes and Talos contexts with one command.
• Makes contexts from nested files effective through the standard ~/.kube/config and ~/.talos/config files.
• Unsets the other platform when a cluster exists only in Kubernetes or Talos.
• Treats a Kubernetes context such as admin@stable as the cluster stable while preserving the qualified name in kubeconfig.
• Generates dynamic completion for Bash and Zsh.
• Updates configuration files atomically and preserves their permissions.

Kubernetes cache directories ~/.kube/cache/ and ~/.kube/http-cache/ are skipped.

Installation

Prebuilt archives are published on the GitHub Releases page for:

• Linux (amd64, arm64);
• macOS / Darwin (amd64, arm64);
• Windows (amd64, arm64).

Every release includes checksums.txt for artifact verification. Linux and macOS binaries are packaged as .tar.gz, while Windows binaries are packaged as .zip.

Go 1.26 or newer is required to install from source:

go install github.com/exdial/tkctx@latest

Or build the repository locally:

git clone https://github.com/exdial/tkctx.git
cd tkctx
go build -trimpath -o tkctx .

Usage

List discovered contexts as YAML:

$ tkctx
contexts:
  talos:
    - home
    - stable
  kube:
    - demo
    - home
    - stable

Switch a cluster:

$ tkctx stable
Switched to context "stable".

The switching rules are:

• if the cluster exists in both platforms, both contexts are selected;
• if it exists only in Kubernetes, Kubernetes is selected and the current Talos context is unset;
• if it exists only in Talos, Talos is selected and the current Kubernetes context is unset.

When a selected context is stored in a nested file, tkctx imports its definition into the default config that kubectl or talosctl actually reads. For Kubernetes it also imports the referenced cluster and user, rebases relative certificate/key paths, and renames conflicting dependencies instead of overwriting existing credentials. Source files in subdirectories are left unchanged; existing entries and permissions in the default configs are preserved.

Both the canonical cluster name and a qualified Kubernetes context name can be used:

tkctx stable
tkctx admin@stable

Shell completion

Bash

Load completion in the current shell:

source <(tkctx completion bash)

Zsh

Enable the Zsh completion system and load completion:

autoload -Uz compinit
compinit
source <(tkctx completion zsh)

Completion candidates are discovered dynamically, so newly added clusters appear without regenerating the script.

Creating a release

Push a semantic-version tag to start the release workflow:

git tag v0.1.0
git push origin v0.1.0

The workflow runs tests, cross-compiles all supported targets, generates checksums and publishes the archives to a GitHub Release.

Development

The repository includes a pinned Go version in mise.toml:

mise install
mise exec -- make check

The Makefile provides these development commands:

Command	Purpose
make or make build	Build ./tkctx with release flags.
make install	Install the CLI with go install.
make fmt	Format all Go packages.
make fmt-check	Verify that Go files are formatted.
make test	Run race-enabled tests and write coverage.out.
make vet	Run go vet on all packages.
make check	Run formatting verification, vetting, and tests.
make snapshot	Build snapshot release artifacts with GoReleaser.
make clean	Remove ./tkctx, dist, and coverage.out.

GO, BINARY, GOFLAGS, and LDFLAGS can be overridden, for example:

make GO=/path/to/go BINARY=tkctx-dev build

See CONTRIBUTING.md for contribution guidelines.

License

This project is licensed under the MIT License.