How To

Completing kubectl Plugins

Learn how to configure shell completion for your plugins and boost your productivity with easy auto-complete!

Arun Babu Neelicattu

Arun Babu Neelicattu

— 2 min read
Completing kubectl Plugins

If you are familiar with using kubectl plugins, you may also know the frustration when your muscle memory kicks in and you hit [TAB] [TAB]—only to get a list of files in the directory instead of the commands you expected.

Let’s fix this: here’s how to configure shell completion for your plugin commands.

The __complete Command Convention

When a user requests completion for a plugin (e.g., by typing kubectl some-plugin [TAB]), kubectl does not handle the completion itself. Instead, it executes the plugin binary with a special first argument: __complete.

The plugin is then responsible for inspecting the subsequent arguments and printing a list of possible completion suggestions to standard output, one suggestion per line.

You can test this behavior using the following command, which uses the krew plugin as an example.

kubectl krew __complete u
uninstall	Uninstall plugins
update	Update the local copy of the plugin index
upgrade	Upgrade installed plugins to newer versions
:4
Completion ended with directive: ShellCompDirectiveNoFileComp

Setup Completion Directory For Plugins

Create the completion directory

install -d ~/.config/.kubectl-plugin-completions
💡
If you are a mkdir fan, use mkdir -p instead of install -d.

Append completions directory to $PATH

💡
Once you have completed this step, you need to reload your shell session or manually update the $PATH.

For Bash Users:

echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.bashrc

For ZSH Users:

echo 'export PATH=$PATH:~/.config/.kubectl-plugin-completions' >> ~/.zshrc

For Fish Users:

fish_add_path ~/.config/.kubectl-plugin-completions

Configure Plugin Completion Script

💡
You should update PLUGIN variable to the name of the plugin before executing the script.
PLUGIN=krew

COMPLETION_SCRIPT="${HOME}/.config/.kubectl-plugin-completions/kubectl_complete-${PLUGIN}"

cat >"${COMPLETION_SCRIPT}" <<EOF
#!/usr/bin/env sh

# Call the plugin's __complete command, passing it all of the shell's
# completion arguments. kubectl will route the request to the correct plugin.
kubectl "${PLUGIN}" __complete "\$@"
EOF

This script creates a kubectl_complete-krew (the suffix is the plugin name) file in the completion directory you created.

Testing Completion

ℹ️
You should test this in a new shell session so the above changes take effect.

The following example uses tab completion for the krew plugin.

kubectl krew 
help       (Help about any command)
index      (Manage custom plugin indexes)
info       (Show information about an available plugin)
install    (Install kubectl plugins)
list       (List installed kubectl plugins)
search     (Discover kubectl plugins)
uninstall  (Uninstall plugins)
update     (Update the local copy of the plugin index)
upgrade    (Upgrade installed plugins to newer versions)
version    (Show krew version and diagnostics)

Voilà 🎉—your muscle memory can work as expected, without surprises!

Read more