How to install bash completion for Qubes OS commands

Community Guides
, , ,
1

How to install bash completion for Qubes OS commands

Intro

According to the poll/post “What would you like to see improved in Qubes OS?” the commands completion (including full calling syntax) for Qubes OS is a very desired thing.

As a developer of project qubes-completion that provides advanced completions for about 40 qvm- and qubes- commands, I decided to make this Guide. The project is stable and ready for use.

Be aware

The project provides completion inside dom0, so it have to work inside dom0. It is not recommended to install third-party software in dom0, especially if you distrust the code origin. Luckily, the completion is provided by a single-file script, it has no blobs, is not obfuscated and written in bash, so advance users can view the code before using it, or at least check that the code does not use anything user-privileged like sudo nor network-related stuff. The script is quite advanced and provides clever completion for about 40 Qubes OS commands, so it is quite big.

How to install (short version)

  1. In dom0:
    sudo qubes-dom0-update -y bash-completion
  2. In any qube (e.g. personal):
    Download the latest qubes-completion.sh file from Assets section on project page to /home/user/Downloads/
  3. In dom0:
    qvm-run --pass-io personal 'cat /home/user/Downloads/qubes-completion.sh' | sudo tee '/etc/bash_completion.d/qubes-completion.sh' | wc -l

After the last step you should see the number of lines that were copied, it should be more than zero.

How to install (step by step guide with comments)

1. Install bash-completion to dom0

The first step is to install general bash-completion package from official Fedora repository. To do so run in terminal of dom0:

sudo qubes-dom0-update -y bash-completion

Explanation: the project qubes-completion requires bash-completion. The bash-completion package was missed in Qubes OS (Fedora part) by mistake, but present in Debian official templates. It is also installed in nearly all GNU/Linux distributions out of box, so it worth installing it whether you plan to use qubes-completion or not. I hope bash-completion will be pre-installed in the future releases. Project bash-completion is a great help in Qubes OS by itself.

2. Download the latest qubes-completion.sh script

Currently qubes-completion is not provided as a package, you will have to manually download it from Releases page of the github project. To do so go to the Assets section of the latest available release and download file qubes-completion.sh to some location like /home/user/Downloads/using any qube connected to the internet (e.g. personal).

Now is the moment you optionally can view the source code of downloaded qubes-completion.sh before it is going to be used in dom0.

3. Copy downloaded qubes-completion.sh file to the dom0

To do that in terminal of dom0 run:
qvm-run --pass-io personal 'cat /home/user/Downloads/qubes-completion.sh' | sudo tee '/etc/bash_completion.d/qubes-completion.sh' | wc -l

Where:

  • personal is a name of the qube used to download qubes-completion.sh script
  • /home/user/Downloads/qubes-completion.sh is an full path to the downloaded file inside personal qube.

After this step you should see the number of lines that were copied, it should be more than zero.

More information about how this command copies file in dom0 can be found in the official Qubes OS documentation in Copying to dom0 chapter.
The | wc -l part at the end of the command counts number of lines of output. It can be omitted; without it you will see the the whole content of the file printed in your terminal but the file-copy result will be the same.

What can it do?

Project qubes-completion provides typing completions and hints for commands specific to Qubes OS operation system by completing all flags and arguments, qube names, firewall rules, devices, prefs, features, tags, packages and etc. Typing completion are provided for almost all commands starting with qvm- and qubes- prefixes and several others.

The awesome examples of use can be found in the project documentation or in the forum topic.

While the project is expected to be the most valuable for advanced users who frequently use terminal in Qubes OS to manage the system, it is also useful for average users. To use bash completions user should press Tab key once or twice when typing commands in terminal that runs bash.

List of supported commands

Currently completion is provided for Qubes OS commands listed below.

List of supported commands (click to see)

Symbol * marks commands that have completion with limited implementation or a room for improvement.

  • qvm-create *
  • qvm-clone
  • qvm-remove
  • qvm-device
  • qvm-block
  • qvm-usb
  • qvm-pci
  • qvm-prefs
  • qvm-features
  • qvm-volume *
  • qvm-backup
  • qvm-backup-restore
  • qvm-check
  • qvm-firewall
  • qvm-service
  • qvm-sync-appmenus
  • qvm-appmenus *
  • qvm-copy-to-vm
  • qvm-move-to-vm
  • qvm-copy
  • qvm-move
  • qvm-start-gui
  • qvm-start-daemon
  • qvm-xkill
  • qvm-sync-clock
  • qvm-get-image
  • qvm-get-tinted-image
  • qvm-console-dispvm
  • qubes-dom0-update *
  • qubes-prefs
  • qubes-guid
  • qubes-hcl-report
  • qubes-bug-report
  • qubes-policy
  • qubes-vm-settings
  • qubes-vm-clone
  • qubes-vm-boot-from-device
  • qubes-input-trigger
  • qubes-guivm-session
  • qubesctl *
  • qubesd-query *

Will it be a part of the Qubes OS out of the box?

I hope so. Currently the project was published for a Qubes OS Team review, but the process is not easy and is not a highest priority. Also R4.2 already in the release candidate stage, so the possible release to have it out of the box may be R4.3 which can be in a year or longer. If you do not want to wait, you can try the project as it is according to this Guide.

Contributors

The list of contributors is available on github page.
Currently the most help I got was from @neoniobium and @gonzalo-bulnes, thank them.
Community work over the project is very much appreciated. You can provide pull requests, too, if interested.

Links

7 Likes
2

Typo? It should indeed be more than zero, shouldn’t it?

1 Like
3

Thank you, 2 typos fixed.

1 Like