Thoughts on command line interfaces and discovery

A while back, I posted about how IBM i has some lessons to teach about command line interfaces and how to make them discoverable, over on my former mastodon.social account. However, that thread has been rotting, and I wanted to get my posts into a blog post for posterity. Unfortunately, posts from other people in the thread are missing, and they did add some context. At a later point, I’ll do some editing on this post to restructure it for my blog, rather than for social media.

A related thing I think is a problem with most modern shells is discovery.

That’ll always be a problem with CLIs – you have to know some things to get started. I think it could be better, though.

If I type ls on a *nix box, I’ll get a directory listing. But, what if I want to customize that listing?

I try ls -? to get help, and get an error, but also a mostly useless usage message.

I then do man ls, and get this monstrosity that pulls me away from my task.

Here’s where I annoy the Fediverse by talking about IBM i.

On that platform, the equivalent command to ls is WRKOBJ (note that IBM i tends to use a very rigid three letter word vocabulary in its commands, which ALSO helps discovery some – odds are good that WRK, CHG, CRT, DSP, or STR are going to be the first three letters of your command).

If I issue WRKOBJ, I get this.

I didn’t give it enough arguments, because it needs to know what objects I want to work with, unlike ls (where it assumes I want all files in my current directory).

So, it popped up a form, populated with default values for the things that have defaults.

I can even drill down further, let’s say that I’m not sure what my options are for Library. I can hit F4 on that field, and get this. Now I have some more examples to choose from.

So, I’ve decided I want all objects in the current library (the closest equivalent to just firing a ls). This is what my prompt looks like right before issuing the command.

Let’s say I want to run that command again, though. Now that I know a bit more about the system, I don’t want to go through the form all over again, and I want the values I had before. At my main menu, on the command line, I hit F9, and get this.

Now I know that I can just enter this, and get all objects in my current library. Or, I can change that to, say, WRKOBJ OBJ(QGPL/*ALL), to get all objects in the IBM-provided general purpose library.

FWIW, the point in this case wasn’t really to talk about objects vs. files, or libraries vs. directories.

Really, I was going for the user interface of popping up a prompt to provide arguments to commands where you don’t necessarily know the syntax or all of the arguments.

I’ll use PWRDWNSYS as another example, as it shows another part of this. I can choose how I want to power down, the delay, whether to restart, and where to start from next time – the common options.

Note the “F10=Additional parameters”, though.

If I hit that, I get some lesser-used options, that some people will care about – in this case, how the subsystems (which hold the equivalent of daemons) shut down, what happens if it takes too long to shut down, and whether to confirm the shutdown.

A UI like this could be used by a designer to simplify discovery of the more important options, rather than overload a new user with less-relevant options like a man page does.

And, also, part of the point here is the contrast with man pages as the main method of discovery on a *nix system.

They’re a good thing to have around, but I’d like also like a form I can fill out with the options I want – it doesn’t pull me entirely away from my task, but rather allows me to continue entering my arguments in a more guided fashion. (Also note that in IBM i, if I’ve already entered some arguments and hit F4, it pre-fills the form with those arguments.)


Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.