Auto-completion features

The walt command line tool provides handy auto-completion features (since WALT 8.0 for bash, and WALT 9.0 for zsh). This post describes how to set up auto-completion (if not working directly on the WALT server), presents some of its features, and provides a few insights of how it works.

Setup (if needed)

Bash and zsh auto-completion are automatically set up when you install or upgrade the WALT server. So if you use walt directly on the server (typically using your SSH account) there is no setup step needed. However, if you use the walt client tool on another machine, you will have to follow the few setup steps described in the documentation page for enabling the shell completion, and repeat these steps when you upgrade this walt client tool.

Features

This section is an overview of the completion features provided.

Basic command completion

As shown in the following terminal recording, one can obviously auto-complete the command categories, sub-commands, and options of the walt tool, by using the <tab> key. The recording also shows auto-completion of help topics (server-install in this case).

When using <tab><tab>, one can list all possible items, as usual. When relevant, we display a description of the available items, as shown below.

Zsh users may already be familiar with this kind of detailed completion display, but we managed to get the same thing with bash, using a few tricks in the completion script.

Advanced completion features

The completion module can also auto-complete objects specific to the WALT platform, such as node or OS image names.

The module can even help you with walt image cp or walt node cp by auto-completing the files and directories found inside an image or node.

Minor issue with current implementation

Note that currently auto-completion only works when typing the last word of the line. If you retrieved a previous command line from the history using ctrl-r or the arrow keys, you might want to edit the second to last argument for instance, but in this case auto-completion will not work.

This issue is tracked and I will edit this post when it is fixed.

Performance notes

Completion is obviously used in an interactive context, so completion scripts have to return completion items fast.

The first examples presented above relied on static completion data. For instance, the list of options of command walt node reboot does not change over time, unless walt is upgraded (in this case we will upgrade the completion script too). So the completion script just embeds this kind of static completion data, which allows for near-instantaneous auto-completion.

On the other hand, the completion script sometimes has to query the WALT server (e.g., to get the list of node names matching the first characters typed). In these cases, the completion script uses a Python program called walt-autocomplete-helper which, in turn, calls the shell_autocomplete entry point of the server API. We decided to write walt-autocomplete-helper in Python because the walt client tool itself is written in Python and we wanted to reuse the API interaction code. Writing fast short-lived Python programs can be challenging, but the workload of walt-autocomplete-helper is limited¹ and we could benefit from the optimization work already done on the client code.

The completion script also records the result of the previous completion in a short-lived cache, so when typing walt node shell <tab><tab> for instance, it calls walt-autocomplete-helper only once, not twice.

Implementation notes

Many projects maintain completion scripts separately from the source code. But those scripts are often outdated so sometimes they cannot handle the latest options or subcommands. Instead, we worked on auto-generating the completion scripts using Python introspection features, which resulted in subcommands walt advanced dump-bash-autocomplete and walt advanced dump-zsh-autocomplete.

In the client code, we use Python type annotations to associate the appropriate completion logic to a given command argument or option. For instance, the prototype of subcommand walt node shell has its argument specified as node_name: NODE. Subcommands dump-bash-autocomplete and dump-zsh-autocomplete retrieve this annotation by using introspection features, so when generating the completion script they can indicate that a NODE is expected there.

Last words

Now you know how much the auto-completion can help, when you use the walt command.

If you are a developer, we also hope this post has inspired you to implement auto-completion in your own command line tools, and perhaps it provided you with some advice on this subject.

Thanks to Jérémie Finiel for proofreading. If you have questions, we can answer you on the mailing list.