kubectl.nvim: kubectl output you can navigate inside Neovim

What the plugin actually does

kubectl.nvim processes kubectl outputs to enable vim-like navigation in a buffer for your cluster, and the repository description puts the ambition in a sentence: streamline your Kubernetes management within Neovim, control and monitor your cluster without leaving your coding environment.

That is a narrow and specific claim. It is not a replacement for kubectl, and it is not a new Kubernetes client in the sense of speaking the API itself. It takes the output of kubectl, parses it, and presents it as a buffer you can move through with the keys you already use.

The required dependency is Neovim 0.10 or newer, and the plugin is written in Lua. The licence is Apache-2.0, the default branch is main, and the last push to the repository was on 2026-10-14.

The release naming is the first clue to how the project is maintained. The recent releases are v2.45.0, v2.46.0 and v2.46.1, and the last two carry the Kubernetes version in the title, v2.46.0 with Kubernetes v1_35 and v2.46.1 with Kubernetes v1_35. So the plugin is versioned in step with Kubernetes itself rather than on its own schedule, which is a strong signal about what it depends on and how often it has to change.

The feature list in the README is a catalogue of buffers: a hierarchy view, coloured output, floating windows, completion, a set of commands, and then a long list of specific actions from exec into a container to port forwarding. That last group is where the plugin stops being a viewer.

The hierarchy view and the floating windows

The core idea of the plugin is a hierarchy that you navigate with the keyboard, and the README describes it as navigating your cluster in a buffer, using hierarchy where possible, with backspace for up and enter for down, for example root, then deployment, then pod, then container.

So the buffer is not a table of pods. It is a tree, and the keys that move a cursor in a buffer move you down the tree, while backspace takes you back up. The phrase where possible in the README is the qualification: the tree exists where the resource relationships are known to kubectl output, and not for every resource type.

On top of that there is coloured output with smart highlighting, so the columns a kubectl table has are visually separated rather than being a wall of spaces, and there are floating windows for contextual information such as logs, description and containers. Floating rather than split is the right choice for that kind of detail: a split changes the geometry of the buffer you are reading, while a float appears over it and disappears.

Completion is offered as a separate feature, and the commands section says that all commands support tab completion, which is the part that makes the plugin usable without memorising resource names.

Taken together, these are the features of a buffer-oriented interface rather than a table viewer. The README's screenshots show a light theme version of the plugin, and the design goal is visible in them: the output of a cluster is navigable with the same muscle memory as a file.

The command surface: Kubectl, Kubens, Kubectx

There are three commands, and they divide into running kubectl and opening interactive views.

:Kubectl get endpoints            -- Run kubectl and show output in split
:Kubectl view [resource]          -- Open interactive view for any resource
:Kubectl top                      -- Open top dashboard
:Kubectl diff [path]              -- Diff resources
:Kubens [namespace]               -- Switch or select namespace
:Kubectx [context]                -- Switch or select context

The first form is the escape hatch and the most important one to understand. It runs the kubectl command you would have typed and shows the output in a split, so anything the plugin does not model can still be done. Everything else is an interactive view built on top of that output.

The view command is the general case, opening an interactive view for any resource. The top command opens a dashboard, and diff compares resources at a path. Kubens and Kubectx are the two operations that every Kubernetes user does dozens of times a day and that the plugin turns into a picker: switch or select a namespace, switch or select a context.

The README also shows the context switch happening from the command line, with the context name given directly, or from the context view. So the interactive view is an alternative to the command, not a replacement for it, and both paths are supported.

That combination, a literal command that runs kubectl plus a set of views, is the design in miniature: the plugin is a presentation layer over an existing command, not a reimplementation of the client.

The actions: exec, logs, port forward, diff and lineage

The longer part of the feature list is the set of operations you would otherwise leave the editor for.

Exec into containers is done from the pod view: select a pod by pressing the carriage return key and then again on the container you want to exec into. Tail logs is a separate feature with its own view. Port forward is there. And the diff view is exposed as :Kubectl diff with a path, with optional dependencies for the diff engine.

There is also sorting, by moving the cursor to anywhere in a column and pressing gs, which sorts the buffer by that column. That is the kind of detail that only makes sense in a buffer, because a table view would give you sorting as a flag rather than as a keystroke in the place you are already looking.

The aliases feature is described as a fallback view that directs custom resources and has basic functionality such as desc, edit and del. That word fallback is informative: custom resources do not fit the hierarchical view the plugin builds, so they get a plainer presentation rather than a broken one.

There is an overview screen and a picker for recent items, which is how you get back to the thing you were looking at thirty seconds ago without retyping a resource name.

And there is lineage, described as a plugin similar to kube-lineage, which shows what a resource depends on and what depends on it. That one carries a warning: it is a beta feature and not all bugs are sorted out. It is the kind of feature that would be the most valuable on a large cluster and the most likely to be wrong, and the plugin's author says so rather than hiding it.

One release per Kubernetes version, and how to handle an old cluster

The compatibility section is the part to read before you install, and it is short.

Each release targets a single Kubernetes version, shown in the release title on the releases page, and releases follow Kubernetes forward rather than supporting a range of older versions.

For an older cluster, the instruction is to pin an older plugin release, a specific tag instead of the wildcard version selector. And the detail that makes that workable: pre-built binaries are attached to every tag, and the Lua and the binary always come from the same tag.

That last sentence is the important engineering one. The plugin has a Lua front end and a compiled binary, and a mismatch between the two would produce failures that look like bugs in the plugin. Pinning the tag pins both.

There is also a built-in health check. Run :checkhealth kubectl to see your client and server versions, along with a warning when they are more than one minor version apart, following the Kubernetes version skew policy for kubectl.

So the plugin does not just warn about a skew, it points at the policy that defines the skew. A cluster and a client more than one minor version apart is a configuration that Kubernetes itself considers unsupported for kubectl, and the plugin is telling you that your results may be unreliable before you start interpreting them.

The practical consequence for an adopter is that the plugin follows the Kubernetes release train rather than lagging behind it. That is the right choice for a project that parses kubectl output, because the output format does change between versions, but it means you maintain a version of the plugin per cluster version.

A Lua plugin over a Rust client and a Go bridge

The repository is a mixed-language project, and the layout explains why.

The Lua directory is the Neovim plugin itself, with a syntax/ directory for the highlighting. The kubectl-client/ directory is a Rust crate, and kubectl-telemetry/ is a second one. The go/ directory holds a Go library that is compiled into a C archive and linked into the Rust binary, which is what the Makefile does with the build_go target:

go -C go build -trimpath -ldflags="-s -w" -buildmode=c-archive -o libkubectl_go.a

So the plugin is a Lua front end over a Rust binary that embeds a Go library, which is the shape you would expect if the Go side is an existing kubectl implementation being reused rather than reimplemented.

The Cargo manifest is a workspace with kubectl-client as the default member and kubectl-telemetry alongside, using the second edition resolver. The release profile is tuned for size rather than speed: opt-level is s, LTO is fat, symbols are stripped, codegen units is one, and incremental compilation is off.

The build targets in the Makefile cover the platforms that matter, including a Windows target built for the x86_64-pc-windows-gnu triple, and a clean target that removes the Go archive along with the cargo build directory.

The quality tooling is Lua tooling plus a Rust toolchain: llscheck against the .luarc.json configuration, luacheck over the lua directory, and stylua in check mode, all bundled into a check target. The tests run inside a headless Neovim with the MiniTest runner, and there is a repro.lua file at the root for reproducing an issue.

The repository also carries AGENTS.md, CLAUDE.md and a .agents/ directory, which tells you that a good part of the work on this plugin is done with an AI assistant.

Installing it, and where kubectl.nvim is the wrong tool

Installation is the usual Neovim plugin block, and the plugin's README offers a choice of three ways to get the binary.

return {
  {
    "ramilito/kubectl.nvim",
    -- use a release tag to download pre-built binaries
    version = "2.*",
    -- OR build from source, requires nightly: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust
    -- build = 'make build',
    -- OR if you use nix, build from source with:
    -- build = 'nix run .#build-plugin',
    dependencies = "saghen/blink.lib",
    config = function()
      require("kubectl").setup()
    end,
  },
}

The three options are a pre-built binary from a release tag, a source build that needs a nightly Rust toolchain, and a Nix build. The plugin also depends on saghen/blink.lib, and the optional dependencies are kubediff or DirDiff for the diff feature and Helm for the helm view.

The wrong tool cases are worth naming. For automation, this is an interactive interface and not a scriptable one, so a pipeline that runs kubectl and parses the output should keep doing that. For a cluster you cannot upgrade, the compatibility policy means pinning a plugin version that matches, which works but means a second plugin version to maintain.

And for somebody who does not live in Neovim, the plugin is a lot of surface for a small gain, since kubectl output in a terminal is readable and the plugin's advantage is navigation rather than data.

The alternative approach for a Kubernetes-aware editor is a full IDE extension, which brings a richer resource tree, a resource editing form and a port-forwarding panel, at the cost of leaving your terminal-based editor entirely. The difference in approach is that an IDE extension reimplements the API client in the editor, while kubectl.nvim keeps kubectl as the client and reinterprets its output, which is why it can be right for a Neovim user whose cluster tools are already the command line ones.

Editorial conclusion

kubectl.nvim suits a developer who lives in Neovim and would rather read their cluster than switch to a terminal window, and who wants the same navigation model for their pods as for their code. It does not suit a cluster on an old Kubernetes version that you cannot upgrade, because each release targets one Kubernetes version and you have to pin an older tag, and it does not suit automation, since it is an interactive interface rather than a scriptable tool. Check three things before you adopt it: that your Neovim is 0.10 or newer, that your client and server versions are within the Kubernetes version skew policy, since the plugin's own checkhealth command warns when they are more than one minor version apart, and whether you will use the pre-built binaries or build from source, which needs a nightly Rust toolchain or Nix. The last push to the repository was on 2026-10-14 and the newest release is v2.46.1.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Ramilito/kubectl.nvim on GitHub
4. README
5. Releases