🚀 Enhanced Teleport kubectl wrapper with auto-authentication
A Go binary for quickly logging into Kubernetes clusters via Teleport with intelligent configuration and cross-shell compatibility.
- 🚀 Quick login with
tkube <env> <cluster> - 🔐 Automatic Teleport authentication with session expiration tracking
- ⚙️ Simple JSON configuration with environment-specific settings
- 🎯 Smart tab completion with helpful messages for missing dependencies
- 🖥️ Cross-shell compatibility (works with any shell)
- 📦 Single binary - no shell-specific dependencies
- 🔧 Multi-version tsh support - use different tsh versions for different environments
- 📥 Automatic tsh installation - downloads the official tsh binaries from the Teleport CDN based on the server version.
- ⏰ Session status display - color-coded session health with remaining time
# Add the tap and install
brew tap lidin10/tap
brew install tkube
# Verify installation
tkube version# Download the latest release for your platform
# For Apple Silicon Macs
curl -L https://github.com/lidin10/tkube/releases/latest/download/tkube_darwin_arm64.tar.gz | tar xz
sudo mv tkube /usr/local/bin/
# For Intel Macs
curl -L https://github.com/lidin10/tkube/releases/latest/download/tkube_darwin_amd64.tar.gz | tar xz
sudo mv tkube /usr/local/bin/
# For Linux
curl -L https://github.com/lidin10/tkube/releases/latest/download/tkube_linux_amd64.tar.gz | tar xz
sudo mv tkube /usr/local/bin/git clone https://github.com/lidin10/tkube
cd tkube
make build
make install# Connect to a cluster
tkube prod my-cluster
# Show available environments and auth status with session times
tkube status
# ✅ prod → teleport.prod.env:443 (10h59m left)
# ⚠️ test → teleport.test.env:443 (1h30m left)
# Show help
tkube help
# Show version
tkube version
# Log out from Teleport servers
tkube logout # Log out from all environments
tkube logout prod # Log out from specific environment
# Generate shell completion
tkube completion bash # for bash
tkube completion zsh # for zsh
tkube completion fish # for fish
# Manage tsh versions (now at root level)
tkube tsh-versions # List installed tsh versions
tkube install-tsh 17.7.1 # Install specific tsh version
# Configuration management
tkube config show # Show current configuration
tkube config path # Show configuration file pathConfiguration is stored in ~/.tkube/config.json:
{
"environments": {
"prod": {
"proxy": "teleport.prod.env:443",
"tsh_version": "16.4.0",
"user": "my-prod-username"
},
"test": {
"proxy": "teleport.test.env:443",
"tsh_version": "17.7.1"
}
},
"auto_login": true,
"default_user": "my-teleport-username"
}tkube supports three levels of user configuration for Teleport authentication:
- Environment-specific user: Set
"user": "username"in environment config - Default user: Set
"default_user": "username"at the top level (applies to all environments without specific user) - System user: Automatically uses your system username as fallback
Priority: Environment-specific user > Default user > System user
This is useful when:
- Your Teleport username differs from your system username
- You use different usernames for different environments (e.g., different identity providers)
- You want to explicitly control which user is used for authentication
The configuration file is automatically created with example values on first run.
tkube supports using different versions of tsh for different environments, which is useful when:
- Different Teleport servers require different tsh versions
- You need to test compatibility with different versions
- Your system tsh version is incompatible with some servers
# Install a specific tsh version (downloads real binaries from Teleport CDN)
tkube install-tsh 17.7.1
# Auto-detect and configure versions for all environments
tkube auto-detect-versions
# List installed versions and their usage
tkube tsh-versionsNote: The install-tsh command now downloads real tsh binaries from the official Teleport CDN (https://cdn.teleport.dev/) and supports multiple package formats (.tar.gz, .pkg, .app bundles) with automatic platform detection.
~/.tkube/
├── config.json
├── sessions/ # Isolated session directories per environment
│ ├── prod/ # Prod environment sessions
│ └── test/ # Test environment sessions
└── tsh/ # Downloaded tsh binaries
├── 16.4.0/
│ └── tsh
└── 17.7.1/
└── tsh
tkube keeps Teleport sessions completely isolated between environments:
- Each environment has its own session directory under
~/.tkube/sessions/<env>/ - Login to one environment doesn't affect authentication status of others
tkube logout <env>only affects the specified environmenttkube statusshows real authentication state per environment
- Teleport CLI (
tsh) - will be downloaded automatically after your first attempt to connect to a cluster. - kubectl - for automatic context switching.
Enable tab completion for your shell:
# Load completion for current session
source <(tkube completion bash)
# Install permanently (Linux)
tkube completion bash > /etc/bash_completion.d/tkube
# Install permanently (macOS with Homebrew)
tkube completion bash > /usr/local/etc/bash_completion.d/tkube# Load completion for current session
source <(tkube completion zsh)
# Install permanently
tkube completion zsh > "${fpath[1]}/_tkube"# Load completion for current session
tkube completion fish | source
# Install permanently
tkube completion fish > ~/.config/fish/completions/tkube.fish# Connect to production cluster (with smart tab completion!)
tkube prod <TAB> # Shows available clusters or helpful messages
# If tsh version missing: "📦 tsh v16.4.0 not installed - run: tkube install-tsh 16.4.0"
# Connect to test environment
tkube test development
# Check authentication status with session times
tkube status
# ✅ prod → teleport.prod.env:443 (10h59m left)
# ⚠️ test → teleport.test.env:443 (1h30m left)
# ❌ dev → teleport.dev.env:443 (expired)
# Auto-detect required tsh versions
tkube auto-detect-versions
# Detected: prod requires tsh v16.4.0
# Detected: test requires tsh v17.7.1
# Install detected versions
tkube install-tsh 16.4.0
tkube install-tsh 17.7.1
# Configure different users for environments
tkube config show # Check current config
# Edit ~/.tkube/config.json to add user settings:
# {
# "environments": {
# "prod": {
# "proxy": "teleport.prod.env:443",
# "tsh_version": "16.4.0",
# "user": "prod-username"
# }
# },
# "default_user": "my-teleport-username"
# }
# Get help
tkube help# Build for current platform
make build
# Build for all platforms
make build-all
# Run tests
make test
# Clean build artifacts
make cleanThis project uses semantic-release for automated versioning and releases. Releases are triggered automatically when commits are pushed to the main branch using conventional commit messages:
# Feature (minor version bump)
git commit -m "feat: add new cluster validation"
# Bug fix (patch version bump)
git commit -m "fix: resolve connection timeout issue"
# Breaking change (major version bump)
git commit -m "feat!: change configuration format"
# or
git commit -m "feat: change config format
BREAKING CHANGE: configuration file format has changed"The automated release process:
- Analyzes commit messages since the last release
- Determines the version bump (patch/minor/major)
- Generates changelog and release notes
- Creates GitHub release with binaries
- Updates Homebrew tap automatically
Please use conventional commit messages for your contributions to ensure proper automated releases.