If you install some features like this, the number of commands available in the Karaf shell console is really impressive. And it’s not always easy to find the one that we need.

That’s why subshell support has been introduced.

Subshell

Karaf now uses commands scope to create “on the fly” a subshell: the commands are grouped by subshell. As you will see later, depending of the completion mode that you will use, you will be able to see the commands only in the current subshell, and change from one subshell to another.

Let take an exemple. In Karaf itself, we have commands to manipulate bundle and commands to manipulate feature, for instance:

bundle:list list the bundles

bundle:start start bundles

bundle:stop stop bundles

feature:list list the Karaf features

feature:repo-list list the Karaf features repositories

…

In previous Karaf version, to list bundles and features, you did something like this:

karaf@root> osgi:list
...
karaf@root> features:list
...

In Karaf 3.0.0, you can still do the same (just using the new name of the commands):

You have commands to go into a subshell. These commands are created on the fly by Karaf using the scope of the commands. Here, we use the bundle and feature commands to go into the bundle and feature subshell.

You can see your current subshell location directly in the prompt:
karaf@root(bundle)>

We can see here that we are in the bundle subshell.

We can switch directly from one subhsell to another using the subshell command:
karaf@root(bundle)> feature
karaf@root(feature)>

You have a new exit command to get out from the current subhsell and return to the root level.

You have the choice between different completion mode, depending the behaviour that you prefer.

Completion Mode

The completion mode defines the behaviour of the TAB key to complete commands.

You have three different modes available:

GLOBAL

FIRST

SUBSHELL

You can define your default completion mode using the completionMode property in etc/org.apache.karaf.shell.cfg file. By default, you have:

completionMode = GLOBAL

But, you can also change the completion mode “on the fly” (while using the Karaf shell console) using a new command: shell:completion:

FIRST completion mode

FIRST completion mode is an alternative to the GLOBAL completion mode.

If you type the TAB key on the root level subshell, the completion will display the commands and the aliases from all subshells (as in GLOBAL mode). However, if you type the TAB key when you are in a subshell, the completion will display only the commands of the current subshell:

SUBSHELL completion mode

If you type the TAB key on the root level, the completion displays the subshell commands (to go into a subshell), and the global aliases. Once you are in a subshell, if you type the TAB key, the completion displays the commands of the current subshell:

Tips

The “old” full qualified command names are still valid. So, you don’t have to change anything in your scripts, you can use:

karaf@root()> feature:install
karaf@root()> ssh:ssh
...

You have the choice: use the completion mode that you prefer, you can always change the mode when you want using the shell:completion command.

My preference is for the SUBSHELL completion mode. Using this mode, you don’t see a bunch of commands on the root level, just the subshell switch commands. I think it’s clear and straight forward. When you “extend” your Karaf runtime with a lot of additional features, it’s interesting to have commands grouped by subshell.