kubectl-peek

An interactive Kubernetes troubleshooting and terminal-workflow CLI.

kubectl-peek helps you inspect Secret relationships, investigate Events, enter Pod containers, select namespaces, and work safely across multiple Kubernetes contexts without changing the kubeconfig used by your other terminal sessions.

kubectl peek
├── secret       Inspect Secrets and discover related resources
├── events       Group, filter and investigate Kubernetes Events
├── exec         Select a Pod and open an interactive container shell
├── namespace    Select and persist a namespace
└── shell        Open an isolated context-aware Kubernetes shell

• Client-side only
• Uses your existing kubeconfig and Kubernetes permissions
• Installs no controller, agent, CRD or web interface
• Supports macOS, Linux and Windows
• Works as both kubectl-peek and the native kubectl peek plugin

Why kubectl-peek?

Everyday Kubernetes troubleshooting often requires several disconnected commands: changing contexts, selecting namespaces, finding Pods and containers, reading repetitive Events, inspecting Secrets, and tracing the resources that use them.

kubectl-peek turns those workflows into focused interactive experiences while keeping the active Kubernetes scope visible and predictable.

Workflow	Problem it solves	Command
Isolated shell	Work in another context without changing other terminals	kubectl peek shell
Events	Group noisy Events and drill into affected resources	kubectl peek events --warnings --browse
Secrets	Decode a Secret and discover who uses or produces it	kubectl peek secret
Pod access	Select the correct Pod and container interactively	kubectl peek exec
Namespace	Select a namespace and either persist it or open an isolated shell within it	kubectl peek namespace

Isolated Kubernetes shells

Open independent terminal sessions for different clusters and namespaces without modifying the original kubeconfig:

kubectl peek shell

Each child shell receives a temporary flattened kubeconfig through KUBECONFIG. The prompt keeps the selected context and namespace visible:

[k8s:production ns:payments] user@host %

Tools such as kubectl, helm and flux use the isolated scope only inside that shell. Temporary files are removed after exit.

Full shell and namespace documentation

Namespace workflows

Select and persist a namespace for the active or explicitly selected context:

kubectl peek namespace
kubectl peek namespace monitoring
kubectl peek namespace --context staging

A namespace-first isolated shell is also available:

kubectl peek namespace --shell

Full shell and namespace documentation

Secret inspection and relationship discovery

Select a Secret interactively, decode its values and discover workloads, operators or custom resources related to it:

kubectl peek secret
kubectl peek secret database -n production
kubectl peek secret --rules ./examples/rules-all.yaml

Built-in discovery covers common Kubernetes resources. Declarative YAML rules extend discovery to resources such as External Secrets Operator, cert-manager, Crossplane, Vault operators, Argo CD and internal CRDs.

Secret inspection · Custom discovery rules

Kubernetes Event investigation

Browse Events ordered by their latest occurrence, group repeated records and inspect occurrence counts, first/last seen timestamps, sources and messages:

kubectl peek events
kubectl peek events --warnings
kubectl peek events --warnings --browse
kubectl peek events -A --non-normal

Browse mode provides hierarchical navigation:

Kind → Resource → Events → Detail

Full Event documentation

Interactive Pod exec

Select a running Pod, choose a container when necessary, and open an interactive shell:

kubectl peek exec
kubectl peek exec api -n staging
kubectl peek exec api --container application --shell /bin/sh

kubectl-peek tries /bin/bash first and falls back to /bin/sh.

Full Pod exec documentation

Installation

Homebrew

brew tap pierinho13/tools
brew install --cask kubectl-peek

Upgrade:

brew update
brew upgrade --cask kubectl-peek

GitHub Releases

Download the archive for your operating system and architecture from the Releases page, extract it, and place the binary in your PATH.

tar -xzf kubectl-peek_<version>_<os>_<arch>.tar.gz
chmod +x kubectl-peek
sudo mv kubectl-peek /usr/local/bin/

Build from source

git clone https://github.com/pierinho13/kubectl-peek.git
cd kubectl-peek
go build -o kubectl-peek .
sudo mv kubectl-peek /usr/local/bin/

Verify:

kubectl peek --help
kubectl peek --version

Quick start

# Show all workflows
kubectl peek

# Inspect a Secret
kubectl peek secret

# Investigate Warning Events
kubectl peek events --warnings --browse

# Open a container shell
kubectl peek exec

# Open an isolated Kubernetes shell
kubectl peek shell

# Persist a namespace
kubectl peek namespace

Global overrides:

--context string      Kubernetes context
--kubeconfig string   Path to the kubeconfig file

Interactive controls

↑ / ↓     Move through results
j / k     Move down or up
← / →     Change page
/         Filter visible results
Enter     Select
Esc       Leave filter mode or cancel
Ctrl+C    Cancel

Security model

kubectl-peek runs locally and uses the permissions of the active Kubernetes identity. It does not install anything in the cluster.

Secret values are decoded and printed to the terminal. They may remain visible in terminal scrollback, recordings, screen sharing, screenshots or captured output. Use Secret inspection only in trusted environments.

Temporary kubeconfigs created for isolated shells:

• contain the effective Kubernetes configuration;
• preserve authentication and exec plugins;
• embed referenced certificate and key data;
• are created with 0600 permissions;
• are exposed only to the child shell;
• are removed after the shell exits normally;
• do not modify the original kubeconfig.

Permissions and security details

Documentation

• Shells and namespaces
• Secret inspection
• Custom discovery rules
• Event investigation
• Pod exec
• Permissions and security
• Development and troubleshooting

Roadmap

Potential improvements include:

• optional Secret value masking and explicit reveal behavior;
• JSON and YAML output;
• non-interactive workflows;
• dependency graph output;
• ConfigMap and cross-namespace discovery;
• reusable community rule collections;
• live Event refresh and export formats;
• Pod log browsing and container diagnostics;
• richer isolated-shell status and integrations.

Contributing

Contributions are welcome. See CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md.

License

Licensed under the MIT License.