by click-contrib

click-contrib / click-completion

Add or enhance bash, fish, zsh and powershell completion in Click

218 Stars 29 Forks Last release: Not found MIT License 69 Commits 10 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:


Enhanced completion for Click

Add automatic completion support for fish, Zsh, Bash and PowerShell to Click.

All the supported shells are able to complete all the command line arguments and options defined with click. In addition, fish and Zsh are also displaying the options and commands help during the completion.



In order to activate the completion, you need to:

  • initialize the
  • inform your shell that completion is available for your script, and how.


in order to enhance the native completion capabilities. This is done very simply:
import click_completion

Once done, your click application is ready for completion.

Inform your shell

has some functions to produce the code to be executed by the shell during the completion, and to permanently install this code in a place that is automatically loaded by the shell.

The key functions are:

  • get_code
  • install

An example of usage can be found in examples/click-completion-command and in examples/click-completion-callback


obviously depends on
is used to generate the shell specific code.

And of course to make it useful, you'll need to use fish, Bash, Zsh or PowerShell.

Customizing completion

Application level

has a
function that can be replaced by a custom one in order to customize the completion. Some extra environment variable to be used during the completion can be passed to
. An example is available in examples/click-completion-command.

Parameter type level

The custom parameter type may reimplement the

method in order to customize the completion result. The
method takes the current context and the incomplete argument to be completed. It can return either a list of argument value that match the incomplete argument, or a list of tuples
(arg, help)
. This last form is preferred because it allows to display the help during the completion for the shells that supports it.

An example can be found in the class

in clickcompletion/

How it works

As click, the general way

works is through a magic environment variable called
, where
 is your application
executable name in uppercase with dashes replaced by underscores.

If your tool is called foo-bar, then the magic variable is called

. By exporting it with the
value it will spit out the activation script which can be trivially activated.

For instance, to enable fish completion for your foo-bar script, this is what you would need to put into your

eval (env _FOO_BAR_COMPLETE=source-fish foo-bar)

From this point onwards, your script will have fish completion enabled.

The above activation example will always invoke your application on startup. This might be slowing down the shell activation time significantly if you have many applications. Alternatively, you could also ship a file with the contents of that, which is what Git and other systems are doing.

This can be easily accomplished:

_FOO_BAR_COMPLETE=source-fish foo-bar > ~/.config/fish/completions/


Licensed under the MIT, see LICENSE.


Contributions are all very welcome!

This may be in the form of bug reports, pull requests, …

A few subjects need some attention currently:

  • documentation
  • tests
  • argument parsing

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.