Written by Lionel B. Dyck, Open Mainframe Project Ambassador and Contributor to CBT Tape

Preface

When was the last time you found you were working on a terminal and couldn’t recall the command that you needed to use to do something, but you could recall what you wanted to do? You had a few options. You could ask someone, you could do a web search, or you could try to recall the command name. If you remembered that the man command has a keyword search option then you could use that – assuming (and we know what assume means) that you knew about it.

Now there is a tool available from the open source community that can help, providing you are on a platform that supports the man command (sorry Windows users) and the installation of the gum package. You can find the gum package home at https://github.com/charmbracelet/gum and it is available with many Linux distributions. If you happen to be using the z/OS platform via a shell session, as this will not work under TSO OMVS, then you are in luck because the z/OS Open Tools project includes gum – just go to https://github.com/ZOSOpenTools to begin that journey.

The tool I will discuss in this article is named mantastic because it is fantastic (at least that is what those who alpha/beta tested it told me). You can find this, along with other tools that take advantage of the gum capabilities at https://github.com/lbdyck/prompters. 

Mantastic would not have been possible without the gum package, and the beauty is that gum provides the capabilities to create a wrapper around nearly all shell commands to make them easier to use by making them more user friendly.

The command syntax is similar to most unix style commands, and if you forget it also has a help option (no man page yet for it but that is planned in the future).

For this article I’m going to use screen captures on z/OS to demonstrate the tool, but again, you can use this on any system with a shell and man pages.

With the existing man command the user needs to know the command name to utilize the man command. Alternately, in order to search the man index and display a list of man pages that have the keyword, they need to know about man -k xxx command where xxx is a keyword that will be used. Then the user can use the man command effectively.

That is where mantastic helps, as it utilizes gum not just to prompt the user, but it also uses the gum pager which is a very nice alternative to less, as you will see shortly.

But before we get into mantastic there is one more tool that is needed if you’re using z/OS. That tool is mandb which the team at the z/OS Open Tools project has thankfully ported. It must be run after any package installation, upgrade, or removal. This happens automatically on my WSL installation of Ubuntu and will soon happen automagically after using the zopen installation tool that is the key to the z/OS Open Tools ecosystem.

Using Mantastic

There are four modes of operation for mantastic:

Help Mode

The help mode is when the command is entered with one of three parameters and will then display a short tutorial on the command syntax:

mantastic ?
mantastic -h
mantastic -help

Full Prompt Mode

The full prompt mode is when just the mantastic command is entered with no parameters:

At the prompt enter a shell command or word(s) to search the man database for the keywords.

In this case we entered git

The search of the man database resulted in a number of man pages with the word git mentioned.

From this list, using the up and down arrow keys, find the man page to display and press the enter key to display the man page:

The man page is displayed using the gum pager which provides the ability to navigate, search, and then easily quit the display.

Selection Mode

This mode is when the user enters the mantastic command with parameters which bypasses the initial prompt and immediately displays the selection list.

Some examples:

Sample Command	Explanation
mantastic git	Search for all man pages with the keyword of git
mantastic git diff	Search for all man pages with either of the keywords (probably not what you want to do)
mantastic git -a diff	Search for all man pages with both git and diff

Display Mode

This mode is when you know the man page to display and just want to use the gum pager to display it.

To use this mode, enter the command with a -d thus:

mantastic git -d

In Summary

What I’ve done was made easy by using the gum tool. I’d like to encourage everyone to consider looking into using gum to enhance the usability of shell commands. I’ve created a wiki at https://github.com/lbdyck/prompters/wiki with information from the various gum commands as there is no man page for them. I’ve also included some hints and tips using it. I’m far from an expert with it, having only used if for less than a month on a few relatively simple projects (which you can find in my repository at https://github.com/lbdyck/prompters) and this was also one of my first coding efforts doing anything with shell scripting – thus those with more experience may find the coding style a bit primitive but it does work.

Feel free to submit issues and pull requests and join in the fun. Imagine the joy of a text user interface for shell commands. Perhaps a menu of frequently used commands and then a text user interface helping with the various command options to guide the user.