Using a command line tool, like CommandBox, you look for those feature comforts, that can make or break the UI. With CommandBox, one of the big wins, is HELP. Most command line tools allow you to type help and get some general help, but CommandBox goes a step further, you can get Help the Global Level, Namespace Help, and even help at the Command Level.
Global Help
To get an overall list of all the commands you have available to run, simply type help at the shell.
Namespace Help
Next, drill down and get help on a specific namespace like server.
Command Help
And finally, get help on a single command such as server stop. We can see the command is also aliased as just stop as well as all the possible parameters and their types along with a few sample ways to call the command.
Thats great, all the built in commands have solid help, but being a community tool, what about when someone else makes a command, I’m sure they won’t have great help too.
That is where you are wrong… CommandBox uses JavaDoc comments to help generate the help for the CLI and even Tab Completion and Hints. There is no excuse for not including help in your Commands, because you can just annotate your functions and arguments/params and you have Help available for all your users.
Let's look at the stop.cfc inside CommandBox itself to see how this is generated.
A simple comment above the component is output.
- Text outputs normally.
- A period represents a blank line.
- {code:bash} and {code} surround the code to make it stand out.
The comments above the run function define a hint, or description for the parameter. Tab completion is another great help when using the CLI, and CommandBox makes that easy by prompting boolean values with true/false, and parameters that include directory, destination, file or path in their names will get file system suggestions for tab complete. Of course can also give custom options, static options where you provide a list in the comment itself, or in this case, the options for Name are dynamically created from a optionsUDF called serverNameComplete that returns the list of running servers.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
/** * Stop an embedded CFML server. Run command from the web root of the server, or use the short name. * . * {code:bash} * server stop * server stop serverName * server stop serverName --forget * server stop --all * {code} **/component extends="commandbox.system.BaseCommand" aliases="stop" excludeFromHelp=false { /** * @name.hint the short name of the server to stop * @name.optionsUDF serverNameComplete * @directory.hint web root for the server * @forget.hint if passed, this will also remove the directory information from disk * @all.hint If true, stop ALL running servers **/ function run( string name="", string directory="", boolean forget=false, boolean all=false ){ //Lots of code in here } function serverNameComplete() { return serverService.getServerNames(); }} |
Help and Tab Completion is great for any CLI User, and even the commands you build can be as professional and helpful as anything else out there.
What command are you going to build?
More information on how to use the help when running the CLI
More information on how to build help into the commands you build.
Add Your Comment