This is useful for (1) exposing administrative commands to admins, so that they can script some of the Jenkins babysitting work, and (2) exposing data and operations to builds executing inside Jenkins, so that they can interact with Jenkins in a richer way.
Writing commands can be done in two ways.
By putting CLIMethod on methods of your model objects
If you are exposing behaviors of your model objects as CLI commands, the easiest way to achieve it is to put @CLIMethod on a method of your model object. See Queue.clear() as an example. In addition to the command name as specified in the annotation, you also need to define "CLI.command-name.shortDescription" as a message resource, which captures one line human-readable explanation of the command (see
Notice that the method is an instance method. So when the
delete-job command is executed, which job is deleted? To resolve this, you also need to define a "CLI resolver", which uses a portion of arguments and options to determine the instance object that receives a method call.
Of all the resolver methods that are discovered, Jenkins picks the one that returns the best return type. It doesn't matter where the resolver method is defined, or how it's named.
Both resolver methods and CLI methods can have any number of args4j annotations, which causes the parameters and arguments to be injected upon a method invocation. All the other unannotated parameters receive null. Combined with the stapler method binding, this enables you to make your method invokable from both CLI and HTTP.
By extending CLICommand
You can also implement a CLI commmand as a subtype of CLICommand, and put @Extension. You can use existing implementations in the core, such as GroovyCommand, as a starting point. CLICommand exposes a lower-level control of the CLI set up (such as a Channel.)
This approach is suitable for the commands that require more serious terminal interaction and remote code execution.
See the javadoc of CLICommand for more details.