zsh-dokku

Native zsh completion for the Dokku CLI.

The completer discovers commands and resources from your connected Dokku system, including commands provided by installed plugins.

Features

• Native zsh completion with no bash compatibility layer.
• Dynamic core and plugin goals such as apps:*, postgres:*, and redis:*.
• Context-aware completion for apps, service instances, networks, domains, config keys, flags, and enumerated flag values.
• Short-lived resource caches isolated by Dokku connection.
• No bundled inventory of server resources.

Requirements

• zsh with its standard completion system (compinit).
• dokku available on PATH.
• A working Dokku client context, such as DOKKU_HOST or a Git remote named dokku.

The completer queries commands such as dokku --quiet help --all and dokku apps:list, so the client must be able to reach the server.

Install

Standalone completion

Install only the completion file:

mkdir -p ~/.zfunc
curl -fsSL -o ~/.zfunc/_dokku \
  https://raw.githubusercontent.com/iloveitaly/zsh-dokku/master/completions/_dokku

Add the directory to fpath before compinit in ~/.zshrc:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

Open a new shell after installation.

To update, run the same curl command again and open a new shell.

zinit

zinit light iloveitaly/zsh-dokku

Update later with:

zinit update iloveitaly/zsh-dokku

The zinit installation clones the repository and loads zsh-dokku.plugin.zsh, which adds completions/ to fpath.

Verify

Check that zsh registered the completer:

echo ${_comps[dokku]}

The expected value is:

_dokku

Try a few completions by pressing the actual Tab key:

dokku <Tab>
dokku apps:destroy <Tab>
dokku apps:list <Tab>
dokku postgres:info <Tab>
dokku config:get <app> <Tab>

Examples:

• dokku apps:destroy <Tab> offers live app names.
• dokku apps:list <Tab> offers --format; apps:list does not accept an app positional.
• dokku postgres:info <Tab> offers live Postgres service names when that plugin is installed.
• dokku apps:list --format <Tab> offers supported format values.

Reload after updating

A new shell will load the updated file. To reload it in the current shell:

unfunction _dokku 2>/dev/null
autoload -Uz _dokku

Cache and troubleshooting

Goal help is cached longer than mutable resource values. Force the goal cache to refresh with:

rm -f "${XDG_CACHE_HOME:-$HOME/.cache}/dokku/completion"

Remove all completion caches when diagnosing connection or inventory changes:

rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/dokku/completion.d"

If completion produces no results, first verify the same shell can reach Dokku:

command -v dokku
dokku --quiet help --all
dokku apps:list

The completion intentionally returns no resource candidates when the Dokku client is unconfigured, a query fails without a usable cache, or the server cannot safely expose values for that argument.

Development

Repository development, the local Dokku harness, and test commands are documented in AGENTS.md.