What are the best-practices for implementing a CLI

Question

I am implementing a CLI tool using Perl. What are the best-practices we can follow here?

Answer 1

Some lessons I've learned:

1) Always use Getopt::Long

2) Provide help on usage via --help, ideally with examples of common scenarios. It helps people don't know or have forgotten how to use the tool. (I.e., you in six months).

3) Unless it's pretty obvious to the user as why, don't go for long period (>5s) without output to the user. Something like 'print "Row $row...\n" unless ($row % 1000)' goes a long way.

4) For long running operations, allow the user to recover if possible. It really sucks to get through 500k of a million, die, and start over again.

5) Separate the logic of what you're doing into modules and leave the actual .pl script as barebones as possible; parsing options, display help, invoking basic methods, etc. You're inevitably going to find something you want to reuse, and this makes it a heck of a lot easier.

Answer 2

The most important thing is to have standard options.

Don't try to be clever, be simply consistent with already existing tools.

How to achieve this is also important, but only comes second.

Actually, this is quite generic to all CLI interfaces.

Answer 3

As a preface, I spent 3 years engineering and implementing a pretty complicated command line toolset in Perl for a major financial company. The ideas below are basically part of our team's design guidelines.

User Interface

1. Command line option: allow as many as possible have default values.

2. NO positional parameters for any command that has more than 2 options.

3. Have readable options names. If length of command line is a concern for non-interactive calling (e.g. some un-named legacy shells have short limits on command lines), provide short aliases - GetOpt::Long allows that easily.

4. At the very least, print all options' default values in '-help' message.

   Better yet, print all the options' "current" values (e.g. if a parameter and a value are supplied along with "-help", the help message will print parameter's value from command line). That way, people can assemble command line string for complicated command and verify it by appending "-help", before actually running.

5. Follow Unix standard convention of exiting with non-zero return code iff program terminated with errors.

6. If your program may produce useful (e.g. worth capturing/grepping/whatnot) output, make sure any error/diagnostic messages go to STDERR so they are easily separable.

7. Ideally, allow the user to specify input/output files via command line parameter, instead of forcing "<" / ">" redirects - this allows MUCH simpler life to people who need to build complicated pipes using your command. Ditto for error messages - have logfile option.

8. If a command has side effect, having a "whatif/no_post" option is usually a Very Good Idea.

Implementation

1. As noted previously, don't re-invent the wheel. Use standard command line parameter handling modules - MooseX::Getopt, or Getopt::Long

2. For Getopt::Long, assign all the parameters to a single hash as opposed to individual variables. Many useful patterns include passing that CLI args hash to object constructors.

3. Make sure your error messages are clear and informative... E.g. include "$!" in any IO-related error messages. It's worth expending extra 1 minute and 2 lines in your code to have a separate "file not found" vs. "file not readable" errors, as opposed to spending 30 minutes in production emergency because a non-readable file error was misdiagnosed by Production Operations as "No input file" - this is a real life example.

4. Not really CLI-specific, but validate all parameters, ideally right after getting them. CLI doesn't allow for a "front-end" validation like webapps do, so be super extra vigilant.

5. As discussed above, modularize business logic. Among other reasons already listed, the amount of times I had to re-implement an existing CLI tool as a web app is vast - and not that difficult if the logic is already a properly designed perm module.

Interesting links

CLI Design Patterns - I think this is ESR's

I will try to add more bullets as I recall them.

Answer 4

You should use Perl modules to make your code reusable and easy to understand.
should have a look at Perl best practices

Answer 5

There are a couple of modules on CPAN that will make writing CLI programs a lot easier:

• App::CLI
• App::Cmd

If you app is Moose based also have a look at MooseX::Getopt and MooseX::Runnable

Answer 6

The following points aren't specific to Perl but I've found many Perl CL scripts to be deficient in these areas:

1. Use common command line options. To show the version number implement -v or --version not --ver. For recursive processing -r (or perhaps -R although in my Gnu/Linux experience -r is more common) not --rec. People will use your script if they can remember the parameters. It's easy to learn a new command if you can remember "it works like grep" or some other familiar utility.

2. Many command line tools process "things" (files or directories) within the "current directory". While this can be convenient make sure you also add command line options for explicitly identifying the files or directories to process. This makes it easier to put your utility in a pipeline without developers having to issue a bunch of cd commands and remember which directory they're in.