A bash/zsh tool that automatically switches kubectl context and namespace based on your current directory. kns uses .kns.conf files to manage Kubernetes contexts per project.

• 🚀 Automatic context switching - Changes kubectl context when you cd into a directory
• 📁 Directory-based configuration - Uses .kns.conf files (similar to asdf's .tool-versions)
• 🔄 Parent directory lookup - Finds and merges .kns.conf from current and parent directories
• ⚡ Quick kubectl shortcuts - Fast access to common kubectl commands
• 🐳 Pod & Container management - Set current pod/container per directory for easy access
• 🐚 Bash & Zsh compatible - Works on both shells

Install with a single command:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/nbu/kns/main/install-standalone.sh)"

Or if you prefer to review the installer first:

curl -fsSL https://raw.githubusercontent.com/nbu/kns/main/install-standalone.sh -o /tmp/install-kns.sh
bash /tmp/install-kns.sh

Note: The installer will automatically:

• Download the kns and kns.sh scripts
• Install them to ~/.local/bin (or custom INSTALL_DIR)
• Add them to your PATH
• Set up shell integration

git clone <repository-url>
cd k
./install.sh
source ~/.bashrc  # or ~/.zshrc

1. Copy the kns script to a directory in your PATH:

   cp kns ~/.local/bin/kns
   chmod +x ~/.local/bin/kns

2. Add to your ~/.bashrc or ~/.zshrc:

   export PATH="$HOME/.local/bin:$PATH"
   source ~/.local/bin/kns.sh

3. Reload your shell:

   source ~/.bashrc  # or ~/.zshrc

Navigate to your project directory and set the context:

cd /path/to/my-project
kns set production-cluster production

This creates a .kns.conf file in the current directory:

# Auto-generated by kns
KNS_CONTEXT="production-cluster"
KNS_NAMESPACE="production"

Now, whenever you cd into this directory (or any subdirectory), the context will automatically switch to production-cluster with namespace production.

Note: You can have different properties in different .kns.conf files. For example:

• Parent directory can have KNS_CONTEXT and KNS_NAMESPACE
• Current directory can have KNS_POD and KNS_CONTAINER
• Values are automatically merged when found

• kns set <context> [namespace] - Set context for current directory

  kns set my-cluster my-namespace
  kns set my-cluster  # namespace is optional

• kns current - Show current context/namespace/pod/container from .kns.conf

  kns current
  # Output:
  # Source: /path/to/.kns.conf
  # Context: production-cluster
  # Namespace: production
  # Pod: my-pod-123
  # Container: app

• kns use <context> [namespace] - Manually switch context

  kns use staging-cluster staging

• kns list - List all available kubectl contexts

  kns list

• kns link <context> [namespace] - Alias for set

  kns link production-cluster production

• kns unlink - Remove context from current directory

  kns unlink

• kns gp - kubectl get pods
• kns gs - kubectl get services
• kns gd - kubectl get deployments
• kns ns - kubectl get namespaces

All shortcuts automatically switch context based on .kns.conf before executing.

• kns sp <pod-name> - Set current pod for this directory

  kns sp my-pod-123

• kns sc <container-name> - Set current container (requires pod to be set first)

  kns sc my-container

• kns gc - List containers of current pod

  kns gc
  # Output:
  # Pod: my-pod-123
  # Containers:
  #   - app (current)
  #   - sidecar

• kns exec <command> [args...] - Execute command in current pod/container

  kns exec ls -la /tmp
  kns exec cat /etc/hosts

• kns cp <source> <dest> - Copy files to/from pod (use pod: prefix for pod paths)

  kns cp local.txt pod:/tmp/file.txt        # Copy to pod
  kns cp pod:/tmp/file.txt local.txt       # Copy from pod

• kns sh - Interactive shell into current pod/container

  kns sh

# Set up a project
cd ~/projects/my-app
kns set production-cluster production

# Navigate to subdirectory - context switches automatically
cd ~/projects/my-app/src
# ✓ Switched to context: production-cluster (namespace: production)

# Use kubectl shortcuts
kns gp
kns gs

# Set up pod and container for this directory
kns sp my-pod-123
kns sc app-container
kns gc                              # List containers

# Work with the pod
kns exec ls -la /tmp
kns cp config.yaml pod:/app/config.yaml
kns sh                              # Interactive shell

# Switch to different context manually
kns use staging-cluster staging

# Remove context from directory
kns unlink

You can split configuration across multiple directories:

# In parent directory (~/projects/my-app/.kns.conf)
KNS_CONTEXT="production-cluster"
KNS_NAMESPACE="production"

# In subdirectory (~/projects/my-app/frontend/.kns.conf)
KNS_POD="frontend-pod-123"
KNS_CONTAINER="nginx"

# When in frontend/, kns will use:
# - Context/namespace from parent directory
# - Pod/container from current directory

1. Configuration files: kns looks for .kns.conf files in the current directory and parent directories (similar to how asdf finds .tool-versions). It merges values from all found files, with current directory values taking precedence.

2. Automatic switching: The shell integration hooks into the cd command. When you change directories, it:

   • Searches for .kns.conf in the current and parent directories
   • Sources all found files to get KNS_CONTEXT, KNS_NAMESPACE, KNS_POD, and KNS_CONTAINER
   • Automatically runs kubectl config use-context and sets the namespace

3. Manual commands: All kns commands can be used manually, and shortcuts automatically apply the context before running kubectl commands.

4. Pod/Container management: When you set a pod with kns sp, it's stored in the local .kns.conf file. Commands like kns exec, kns cp, and kns sh automatically use the current pod and container from the configuration.

To disable the automatic context switch messages, set:

export KNS_QUIET=1

Set INSTALL_DIR before running install:

INSTALL_DIR=/usr/local/bin ./install.sh

Set KNS_CONFIG_DIR to change where global config is stored:

export KNS_CONFIG_DIR="$HOME/.config/kns"

• bash or zsh
• kubectl installed and configured
• Write access to ~/.local/bin (or custom install directory)

• Make sure you've sourced kns.sh in your shell rc file
• Check that .kns.conf exists in the directory (or parent directory)
• Verify the file contains KNS_CONTEXT variable
• Try running kns current to see if the file is detected and what values are being used

• Make sure you've set the pod with kns sp <pod-name>
• Verify the pod exists: kubectl get pod <pod-name>
• Check that you're in the correct context/namespace
• Run kns current to see current configuration

• Some minimal/distroless containers don't have common commands like ls or shells
• Try using full paths to executables: kns exec /app/my-binary
• Use kubectl exec directly if you know the executable path
• Check what's available: kubectl exec <pod> -- ls /bin /usr/bin

• Ensure kubectl is installed and in your PATH
• Verify with which kubectl

• Make sure kns script is executable: chmod +x kns
• Check that install directory is writable

This project is licensed under the MIT License - see the LICENSE file for details.

[Add contribution guidelines here]

If you find kns useful and would like to support its development, consider:

• ⭐ Star the repository - Show your appreciation
• 💰 GitHub Sponsors - Sponsor me on GitHub
• ☕ Ko-fi - Buy me a coffee

Your support helps maintain and improve this project. Thank you!