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).

Every release includes checksums.txt for artifact verification. Release binaries are packaged as .tar.gz archives.

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.

See CONTRIBUTING.md for contribution guidelines.

License

This project is licensed under the MIT License.