Skip to main content

Installation

This guide covers installing Kuve on your system.

Prerequisites​

Required​

  • Operating System: Linux or macOS
  • Go: Version 1.25 or later (for building from source)
  • Git: For cloning the repository

Optional​

  • Make: For using Makefile commands
  • kubectl: Will be managed by Kuve after installation

Installation Methods​

This is the recommended method for most users:

# Clone the repository
git clone https://github.com/germainlefebvre4/kuve.git
cd kuve

# Build and install using make
make install

This will:

  1. Build the kuve binary
  2. Copy it to ~/.kuve/bin/kuve
  3. Create necessary directory structure

Using Make​

If you have already cloned the repository:

cd kuve

# Build only (creates binary in current directory)
make build

# Build and install
make install

# Clean build artifacts
make clean

Manual Build​

If you prefer to build manually without Make:

# Build the binary
go build -o kuve main.go

# Install to a directory in your PATH
sudo mv kuve /usr/local/bin/

# Or install to user directory
mkdir -p ~/.kuve/bin
mv kuve ~/.kuve/bin/

Post-Installation Setup​

After installation, you need to configure your shell to use Kuve.

Add to PATH​

The ~/.kuve/bin directory must be in your PATH to use kubectl managed by Kuve:

export PATH="$HOME/.kuve/bin:$PATH"
Important

This needs to be added to your shell configuration file to persist across sessions.

Configure Your Shell​

Choose your shell below and add the configuration:

Bash​

Add to ~/.bashrc:

# Kuve - Kubernetes Client Switcher
export PATH="$HOME/.kuve/bin:$PATH"

Apply changes:

source ~/.bashrc

Zsh​

Add to ~/.zshrc:

# Kuve - Kubernetes Client Switcher
export PATH="$HOME/.kuve/bin:$PATH"

Apply changes:

source ~/.zshrc

Fish​

Add to ~/.config/fish/config.fish:

# Kuve - Kubernetes Client Switcher
set -gx PATH "$HOME/.kuve/bin" $PATH

Apply changes:

source ~/.config/fish/config.fish

Shell Completion (Optional)​

Kuve supports shell completion for enhanced user experience:

Bash​

# System-wide (requires sudo)
kuve completion bash | sudo tee /etc/bash_completion.d/kuve

# Current session only
source <(kuve completion bash)

# Add to ~/.bashrc for persistence
echo 'source <(kuve completion bash)' >> ~/.bashrc

Zsh​

# Generate completion file
kuve completion zsh > "${fpath[1]}/_kuve"

# Reload completions
autoload -U compinit && compinit

Fish​

# Generate completion file
kuve completion fish > ~/.config/fish/completions/kuve.fish

PowerShell​

kuve completion powershell | Out-String | Invoke-Expression

Verification​

After installation and configuration, verify that Kuve is working correctly:

Check Kuve Installation​

# Check if kuve is accessible
which kuve
# Expected output: /home/username/.kuve/bin/kuve

# Check version
kuve --version
# Expected output: kuve version dev

# View help
kuve --help

Test Directory Structure​

# Verify Kuve directories were created
ls -la ~/.kuve/
# Expected: bin/ and versions/ directories

Directory Structure​

After installation, Kuve creates the following structure:

~/.kuve/
├── bin/              # Contains kuve binary and kubectl symlink
│   ├── kuve          # Kuve executable
│   └── kubectl       # Symlink to active kubectl version
└── versions/         # Installed kubectl versions
    ├── v1.28.0/
    │   └── kubectl
    └── v1.29.0/
        └── kubectl

Upgrading Kuve​

To upgrade Kuve to a newer version:

cd kuve
git pull origin main
make install

Troubleshooting​

Command Not Found​

If you get kuve: command not found:

  1. Verify installation:

    ls -l ~/.kuve/bin/kuve

  2. Check PATH:

    echo $PATH | grep .kuve

  3. Add to PATH if missing and restart shell

Permission Denied​

If you get permission errors:

chmod +x ~/.kuve/bin/kuve

Build Errors​

If build fails:

  1. Verify Go version:

    go version  # Should be 1.25+

  2. Update dependencies:

    go mod tidy
    go mod download

Next Steps​

Now that Kuve is installed:

  1. Quick Start - Get up and running in minutes
  2. Shell Setup - Configure advanced shell features
  3. Basic Usage - Learn the essential commands