The New Pbench CLI

[webbnh]

Introduction

This is an initial stab at laying out some thoughts around the new Pbench CLI.

General Requirements

We expect to have at least two CLIs -- one for the server and one for the agent. (There is a possibility of having "client" commands, as well, which would be used to talk to the server over the network, without requiring either a server installation or an agent installation on the user's node.) The CLIs should have a common "feel", with similar (but not identical) options, but they will need to have largely separate implementations, since they will be packaged separately (and since they have separate missions).

The commands will be implemented in Python using the Click package. We expect that, with modest discipline on our part, this will yield a CLI similar to Git's, where we can invoke or refer to specific commands directly (like pbench-user-create) or via nested invocations (like pbench user create) where there is a main pbench command which invokes the CLI, and then object-verb sub-commands arranged into groups (such as a user subgroup which sports create, list, update, and delete sub-sub-commands).

Commands should be named in object-verb format. This allows the manipulation of different objects to be separated from each other while grouping together the available manipulations. This will likely require some changes (e.g., pbench-generate-token should be renamed to pbench-token-generate and pbench-move-results should become pbench-results-move or similar).

Where appropriate commands may take positional arguments. Otherwise, the operation of a command can be modified by specifying options or switches. Short options consist of a single hyphen and a single letter; long options consist of two hyphens and (typically) multiple letters; aliases are available. Commands and long options should be lower-case. Neither commands nor option names should contain underscores; hyphens can be used in option names if necessary; commands must be a single word.

There will be a set of options which are common to nearly all commands. These will have a common implementation which is shared by all the command implementations for a given part of Pbench. For instance, the -C option for specifying the configuration file is available and used by nearly every command; however, note that the -C when specified to an agent command looks at the agent configuration file, while the same option on a server command looks at the server configuration file.

Specific Commands

Eventually, we should describe all of the current and planned Pbench commands here. For the moment, we'll start with a single set as the concrete basis for discussion.

pbench user

There are four commands which we are in the process of implementing to manipulate users in the server database.

create

pbench user create --username <name> --password <pwd> --email <adr> --first-name <name> --last-name <name> --role <ADMIN>

No positional parameter; all information is specified via options.

update

pbench user update [--username <new-name>] [--password <new-pwd>] [--email <new-adr> [--first-name <new-name>] [--last-name <new-name>] [--role <ADMIN>] <user>

The user to be updated is specified as a positional parameter (whether this is a "username", an "email address", a "database identifier" is unspecified and the implementation may accept more than one) and updated values are specified via options.

delete

pbench user delete <name>

The user to be deleted is specified as a positional parameter (see comment under update).

list

pbench user list

No positional parameters (and, no options currently -- it is presumed that, since this is a shell command, the user can pipe the output to shell utilities for additional processing).

[portante]

Since you have written this up so well, can you do the same for the pbench agent? =)

[webbnh]

Whadayamean? This document covers both agent and server, and potentially client! (My job is done, here!)

[portante]

Ha!

Good, we just want to enumerate the command and a mapping from what we have today to what we want. Will also serve as a document for our users.

[dbutenhof]

I need to refactor my "state manager" and "dataset importer" tools into this framework, too. I didn't try it originally because I was afraid of being the first to "click" on the server side (even though pbench-server was actually already there), and then I delayed due to fear of the likely gold file changes (which capture all the output and log messages). I also need to decide longer term whether the dataset importer is useful; it serves a purpose during development deployments on populated servers since we only create Dataset objects now on PUT; but a containerized server won't start with any datasets and we'll probably want to PUT them in anyway. (That is, if I delay long enough I'll only need to refactor the state manager for unit testing, and drop the other entirely.)