Skip to main content

Commands

Detailed documentation for each Kuve command.

This page provides in-depth information about each command's behavior, use cases, and examples.

install​

Install a specific kubectl version.

Usage​

kuve install <version>

Behavior​

  1. Validates version format
  2. Checks if version already installed
  3. Determines platform (OS/architecture)
  4. Downloads kubectl binary from dl.k8s.io
  5. Saves to ~/.kuve/versions/<version>/kubectl
  6. Makes binary executable
  7. Confirms installation

Requirements​

  • Internet connection
  • ~50MB disk space per version
  • Write permissions in ~/.kuve/

Error Conditions​

ErrorCauseSolution
Already installedVersion existsUse existing or uninstall first
Download failedNetwork/URL issueCheck connection, verify version exists
Permission deniedNo write accessFix ~/.kuve/ permissions
Disk fullInsufficient spaceFree up disk space

See Also​

uninstall​

Remove an installed kubectl version.

Usage​

kuve uninstall <version>

Behavior​

  1. Validates version is installed
  2. Checks if version is currently active
  3. Removes version directory
  4. Confirms removal

Restrictions​

  • Cannot uninstall the currently active version
  • Must switch to another version first

Error Conditions​

ErrorCauseSolution
Not installedVersion doesn't existCheck kuve list installed
Currently activeVersion in useSwitch to another version first
Permission deniedNo write accessFix permissions

See Also​

switch​

Change the active kubectl version.

Usage​

kuve switch <version>

Aliases​

  • kuve use <version>

Behavior​

  1. Validates version is installed
  2. Updates symlink: ~/.kuve/bin/kubectl → ~/.kuve/versions/<version>/kubectl
  3. Confirms switch

Technical Details​

  • Uses symbolic links for instant switching
  • No file copying involved
  • Changes take effect immediately

Error Conditions​

ErrorCauseSolution
Not installedVersion doesn't existInstall version first
Invalid versionBad formatUse correct format (v1.28.0)

Verification​

After switching, verify:

kuve current
kubectl version --client

See Also​

  • current - Check active version
  • use - Use version from file/cluster

current​

Show the currently active kubectl version.

Usage​

kuve current

Behavior​

  1. Reads symlink at ~/.kuve/bin/kubectl
  2. Extracts version from target path
  3. Displays version

Output Format​

Current kubectl version: v1.28.0

Use Cases​

  • Verify successful switch
  • Check version before operations
  • Debugging version issues
  • Scripting version checks

Error Conditions​

ErrorCauseSolution
No version activeNo symlink or brokenInstall and switch to a version

See Also​

list installed​

List all locally installed kubectl versions.

Usage​

kuve list installed

Behavior​

  1. Reads ~/.kuve/versions/ directory
  2. Lists all version subdirectories
  3. Marks currently active version with *
  4. Sorts by version number

Output Format​

Installed kubectl versions:
  v1.26.3
* v1.28.0
  v1.29.1

* = current version (v1.28.0)

Use Cases​

  • Audit installed versions
  • Determine cleanup candidates
  • Verify installations
  • Check disk usage

See Also​

list remote​

Show the latest stable kubectl version.

Usage​

kuve list remote

Behavior​

  1. Queries official Kubernetes releases
  2. Fetches latest stable version
  3. Displays version

Output Format​

Latest stable version: v1.29.1

Requirements​

  • Internet connection
  • Access to Kubernetes release API

Use Cases​

  • Check for updates
  • Determine version to install
  • Stay current with releases

See Also​

use​

Use kubectl version from file or cluster.

Usage​

# From file
kuve use

# From cluster
kuve use --from-cluster
kuve use -c

Mode: From File (Default)​

Behavior​

  1. Searches for .kubernetes-version in current directory
  2. Reads version from file
  3. Installs version if needed
  4. Switches to version

Requirements​

  • .kubernetes-version file must exist
  • File must contain valid version

Mode: From Cluster​

Behavior​

  1. Connects to current Kubernetes cluster
  2. Queries cluster version
  3. Normalizes version (removes vendor suffixes)
  4. Installs version if needed
  5. Switches to version

Requirements​

  • Valid kubeconfig
  • Cluster access
  • kubectl binary available (from kuve or system)

Version Normalization​

Cluster versions are normalized:

  • v1.28.3-gke.1234 → v1.28.0
  • v1.27.5-eks-abc123 → v1.27.0
  • v1.29.1+k3s1 → v1.29.0

See Also​

init​

Create a .kubernetes-version file.

Usage​

# Use current version
kuve init

# Specify version
kuve init <version>

Behavior​

  1. Determines version (current or specified)
  2. Creates .kubernetes-version in current directory
  3. Writes version to file
  4. Confirms creation

File Format​

v1.28.0

Use Cases​

  • Set project kubectl requirement
  • Document version dependency
  • Enable version file workflow
  • Team standardization

Best Practices​

  1. Commit to version control:

    git add .kubernetes-version
    git commit -m "Add kubectl version requirement"

  2. Create at project root

  3. Document in README

See Also​

completion​

Generate shell completion scripts.

Usage​

kuve completion <shell>

Supported Shells​

  • bash
  • zsh
  • fish
  • powershell

Installation​

Bash​

# Current session
source <(kuve completion bash)

# Persistent
kuve completion bash | sudo tee /etc/bash_completion.d/kuve

Zsh​

kuve completion zsh > "${fpath[1]}/_kuve"
autoload -U compinit && compinit

Fish​

kuve completion fish > ~/.config/fish/completions/kuve.fish

Features​

  • Command completion
  • Version completion (where applicable)
  • Flag completion

See Also​

version​

Show Kuve version information.

Usage​

kuve version
kuve --version

Output Format​

kuve version dev

Use Cases​

  • Verify installation
  • Report bugs (include version)
  • Check for updates

help​

Display help information.

Usage​

kuve help [command]
kuve [command] --help

Examples​

# General help
kuve help

# Command help
kuve help install
kuve install --help

Features​

  • Command descriptions
  • Usage examples
  • Available flags
  • Related commands

Command Comparison​

CommandPurposeRequires VersionModifies State
installAdd versionNoYes (adds files)
uninstallRemove versionYesYes (removes files)
switchChange activeYesYes (symlink)
currentShow activeNoNo
list installedShow localNoNo
list remoteShow latestNoNo
useUse from file/clusterNo*Yes (symlink)
initCreate fileNoYes (file)

* Auto-installs if needed

Next Steps​