4. Settings and Configuration

Both pywbemtools (pywbemcli and pywbemlistener) execute after installation without any configuration except for the use of tab-completion (using <TAB> on the shell command line) to attempt to complete parameters. The tab-completion is not active after installation and must be activated separately.

4.1. Activating shell tab-completion

Shell tab-completion, when activated, allows the terminal user to:

  • Complete the static elements of the command line including:

    • command group names (ex. pywbemcli subscription),

    • command names (ex. pywbemcli class enumerate, list, etc.),

    • command option names (pywbemcli connection --name, -n, etc.).

  • Complete the value of arguments and options that depend on local data to complete the commands (ex. where a WBEM server is not contacted). Thus, the pywbemcli option --name which defines the name of a connection in a connection file can be completed (pywbemcli searches the names in the file). But the value of the class in class get does not support tab-completion because that involves a connection to the WBEM server.

Tab-completion for the pywbemtool commands (pywbemlistener and pywbemcli) must be manually activated after pywbemtools installation.

Shell tab-completion is supported for pywbemlistener and pywbemcli in the Command mode, for the following shells:

  • bash shell - (bash version 4.4 or greater). Not all Linux implementations include the bash_complete addon so that the user may be required to install the add-on. A simple test with a utility like ls will indicate if tab-completion is available in bash(ex. enter ls <TAB> to test for the existence of the bash_complete addon).

  • zsh shell - Tab-completion is available for all versions of zsh but may need to be activated in the zsh config file. Furthermore there are two different completion systems for zsh.

  • fish shell - Available for all versions of this shell.

To activate shell tab-completion, the shell magic variable (_<PROG-NAME>_COMPLETE) must be defined in the shell initialization for the shell, defining the shell name and the pywbemtools name as follows:

* _<PROG-NAME>_COMPLETE=<SHELL-NAME>_source  <prog-name>

where:

  • <PROG-NAME> - pywbemtools command name in uppercase(i.e. PYWBEMCLI or PYWBEMLISTENER).

  • <SHELL-NAME> - shell name (i.e. bash, zsh, or fish).

  • <prog-name> - pywbemtools command name in lower case (pywbemcli or pywbemlistener). pywbemcli and pywbemlistener must be publicly available.

The existence of this shell variable (_<PROG-NAME>_COMPLETE) when the shell is started indicates that this is a shell tab-completion variable and the shell calls back to <prog-name> oon terminal startup with arguments containing _<PROG-NAME>_COMPLETE, _<SHELL-NAME>_source and other tab-completion information in environment variables. The pywbemtools command prog-name returns the correct completion script text specific for that shell as the call return value.

The eval statement defined in the table below contains the eval statement in the shell startup script for supported shells that activates the tab-completion initialization by making the script returned from the shell call to the pywbemtools command available within the current shell instantiation.

The pywbemtools commands must be public for this initialization to work. The tab-completion script is created each time the shell is initialized and is placed in the user root directory.

An ``eval` command specific for each supported shell should be added to the shell started up file for that shell type to activate shell tab-completion of that particular shell, and each of the pywbemtools commands. For example the following example activates the bash shell tab-completion for pywbemcli each time a bash terminal shell is started. :

eval "$(_PYWBEMCLI_COMPLETE=bash_source pywbemcli)"
eval "$(_PYWBEMLISTENER_COMPLETE=bash_source pywbemlistener)"

The following table defines the shell tab-activation eval command for each of the shell types supported by pywbemtools.

Shell

File to insert eval statement

Eval command

bash

~/.bashrc

eval “$(_<PROG-NAME>_COMPLETE=bash_source <prog-name>)”

zsh

~/.zshrc

eval “$(_<PROG-NAME>_COMPLETE=zsh_source <prog-name>_COMPLETE=zsh_source <prog-name>)”

fish

~/.config/fish/completions/foo-bar.fish

eval (env _<PROG-NAME>_COMPLETE=fish_source <prog-name>_COMPLETE=fish_source <prog-name>)

This eval statement defines the shell variable and the pywbemtool tool in a shell variable(_<prog_name>_COMPLETE) and notifies the the defined shell that the pywbemtool is to be activated. The shell both the pywbemtool to create the required script.

4.1.1. Testing that tab-completion is activated

The tab-completion activation of pywbemcli and pywbemlistener can be tested in a terminal by entering part of a known command and using the <TAB> to request completion. The example below shows testing:

$ pywbemcli clas<TAB>

This should complete the class statement (i.e. expand cmd line to
``pywbemcli class``).

$ pywbemlistener star<TAB>

This should complete the start command name (i.e. expand command line to
``pywbemlistener start``)

Each shell type has one or more commands to determine the state of tab-completion for a particular application. In bash it is the builtin command complete used both to define the tab-completion for a particular command and to list which commands have been activated.

Executing the bash builtin complete -p pywbemcli command should return the a line that defines the completion for pywbemcli as follows:

$ complete -p pywbemcli       < ------------ This returns the following
                                             if tab-completion is active

complete -o nosort -F _pywbemcli_completion pywbemcli

Zsh has corresponding commands depending on the version of completion and the use of the bashcompinit plugin.

4.1.2. Removing shell tab-completion activation

Bash: The command complete -r pywbemcli removes the tab-completion for pywbemcli.

Zsh: Depends on zsh configuration

4.1.3. Alternate activation by directly creating the tab-completion script file

This activation technique is useful if you have multiple implementations of pywbemtools installed or for some reason pywbemtools is not in a public directory.

Create a complete tab-completion script file using the statement (ex. _<PROG-NAME>_COMPLETE=<shell-type>_source <prog-name>) but save the resulting complete script in a file (ex: ~/.pywbemcli-complete.bash). This file contains the shell-specific logic to activate tab-completion and process tab-completion calls. Then activate tab-completion by sourcing that script file (ex. source ~/.pywbemcli-complete.bash) which is independent of whether pywbemcli and pywbemlistener are public.

The following table defines the shell command for supported shells to create the complete script file. The naming and exact location of the file is arbitrary and the locations shown in the table are examples. However, the script file created is different for each shell. The following table defines the line to be executed to create the COMPLETE shell script for each supported shell type. This can be executed one time after pywbemtools is installed since that script is fixed by the code in the pywbemtool.

Shell

Script creation command

bash

_<PROG-NAME>_COMPLETE=bash_source <prog-name> > ~/.<prog-name>-complete.bash

zsh

_<PROG-NAME>_COMPLETE=zsh_source <prog-name> > ~/.<prog-name>-complete.zsh

fish

_<PROG-NAME>_COMPLETE=fish_source <prog-name> > ~/.config/fish/completions/<prog-name>.fish

The activation is completed by sourcing the script before the pywbemtool is executed in an active shell. For example to complete activation for bash where the script is in ~/blah execute :

$ source ~/blah/pywbemcli-complete.bash

The pywbemtool should now have shell tab completion active for bash

For example the following creates the shell tab-completion script for bash and pywbemcli in directory ./blah and can be executed once after pywbemcli installation:

# example for bash and pywbemcli where the script is placed in  directory ./blah
$ _PYWBEMCLI_COMPLETE=bash_source pywbemcli > ./blah/pywbemcli-complete.bash

The second step can be executed any time before pywbemcli is executed and activates shell tab-completion for the current shell execution by sourcing the COMPLETE script created in the first step:

$ source  ~/blah.pywbemcli-complete.bash

This step can be executed automatically:

  • by including sourcing statement as part of a virtual environment startup

  • or executing the sourcing statement when a terminal is opened by executing the script itself (ex. source  ~/.pywbemcli-complete.bash).

  • or executing in the shell before using pywbemcli in a single terminal session.