A command can go by more than one name. For instance, the dir command can also be called as ls, ll, or directory. Set a comma-delimited list of aliases in your component declaration like so:

component aliases="ls,ll,directory" {
}

Command aliases don't even have to be in the same namespace. For instance, the server start command has an alias of just start. This can be very powerful as you can install a command that "overwrites" a built-in command by aliasing itself as that command.

With power comes responsibility though. Make sure you don't distribute a command that accidentally stomps all over another command. Unless your command name is decidedly unique, it's probably best for most custom commands to use a namespace to avoid conflicts.

CommandBox is extensible via CFML by creating modules that contain command CFCs. This is a very easy and powerful way to create custom, reusable CFML scripts that interact with the user, automate hard tasks, and can be shared with other developers. Let's create a "Hello World" command.

Your First Command

To create our first command, we'll need a new module. A module can contain as many commands as you like. You can create a module by placing a folder in ~/.CommandBox/cfml/modules/ that contains a ModuleConfig.cfc file. The minimum contents of your module config is:

modules/test/ModuleConfig.cfc

component {
    function configure(){}
}

Now, create a commands folder inside your module for your command to live in. Each CFC in this folder will be registered as a command. The only requirement for a command CFC is that is has a run() method.

modules/test/commands/Hello.cfc

component {
    function run(){
        return 'Hello World!'; 
    }
}

That's it! After creating your module, run the reload command from the shell, and then the name of the new command is the same as the name of the CFC. In this case, you would run the command above like so:

hello

It would output Hello World! to the console. Anything after hello will be passed to your run() function as parameters.

Create Namespaces

To create a two-part command like say hello create CFCs that are nested in subfolders, for example: ~/.CommandBox/cfml/modules/test/commands/say/Hello.cfc The contents of the Hello.cfc would not change, but the namespace will match the folder name by convention. The namespaced command would be called like so:

say hello

There is no limit to how deeply you can nest your namespace folders. CommandBox's built in help and tab-completion will always work via conventions.

Note: The box.json file can have a key called "ignore" that allows you stipulate folders or files which should not be installed but can be kept in reserve for testing or private purposes. Any folder in your namespace that matches that pattern will not be copied during installation.

Making Changes

Commands are created and stored once for the duration that CommandBox is running. CFProperty injections are also aggressively cached on disk across restarts. If testing changes to a command in the interactive shell, use the reload command (aliased as r) to reload the shell. Your changes will immediately be available. Using the up arrow to access the shell's history can also be useful here.

WireBox DI

All CFCs including commands are created and wired via WireBox, so dependency injection and AOP are available to them. This can be handy for commands to wrap services provided by models, or to access utilities and services inside CommandBox.

This command would inject CommandBox's ArtifactService to list out all the packages being stored.

component {

    property name='artifactService' inject='artifactService'; 

    function run(){
        var results = artifactService.listArtifacts();
        for( var package in results ) {
            print.boldCyanLine( package );
        }
    }

}

Commands also have a variables.wirebox variable as well as their own getInstance() method which proxies to WireBox to get objects.

var results = getInstance( 'artifactService' ).listArtifacts();

Regardless of whether your command is called with named parameters, positional parameters or boolean flags, you'll access them the same way: via the standard CFML arguments scope. The user will be prompted for required parameters if they haven't provided them, and the defaults you configured will also work just like you expect.

If the parameters were escaped when typed into the command line, you will receive the final unescaped version in your command.

Dynamic Parameters

Users can pass named or positional parameters that aren't declared, and they will come through the arguments scope. Named parameters will be accessible as arguments.name, and positional parameters as arguments[ 1 ], arguments.[ 2 ], etc.

This can allow for powerful commands like package set that allows users to set any box.json property they want.

package set foo=bar

File System Paths As Parameters

If your command accepts a file or folder path from the user, you'll want to resolve that path before you use it. To do this, use the resolvePath() method that is available to all commands via the BaseCommand class. (This method wraps the resolvePath() method of the fileSystemUtil object that is injected into all commands.) The method resolvePath() will make the file system path canonical and absolute. This ensures you have a fully qualified path to work with even if a user might passed a folder relative to their current working directory passed something like ../../.

component extends="commandbox.system.BaseCommand" {

    function run( String directory )  {
        // This will make each directory canonical and absolute
        arguments.directory = resolvePath( arguments.directory );
        return arguments.directory;
    }
}

If you run that command and pass a full file path such as C:\sandbox\testSite, you would get that exact same path back as the output.

However, if you changed the interactive shell to the C:\sandbox directory and then ran the command with testsite as the input, the relative path would now still resolve to C:\sandbox\testSite.

If, from the same directory, you passed testsite/foo/bar/../../, you would still get C:\sandbox\testSite as the path.

Commands aren't required to output anything, but if you do, the simplest way is to simply return a string from your run() method.

function run() {
    return 'Hi Mom!';
}

The recommended method is via a print object. You can output ANSI-formatted text this way. All the text you output will be stored in a "buffer" and at the end of the command it will be output to the console, or piped into the next command if necessary;

Print Helper

The print object has an unlimited number of methods you can call on it since it uses onMissingMethod. Here are the rules.

Line Break

If the method has the word "line" in it, a new line will be added to the end of the string. If the string is empty or not provided, you'll just output a blank line.

print.line( 'I like Spam.' );
print.line();

Text Color

CommandBox supports 256 colors, but some terminals only support 16 or even 8. If you use a color that the terminal doesn't support, it will be adjusted to the next closest color. If the method has one of the names of a supported color in it, the text will be colored. Here are the basic 16 color names:

• Black

• Maroon

• Green

• Olive

• Navy

• Magenta

• Cyan

• Silver

• Grey

• Red

• Lime

• Yellow

• Blue

• Fuchsia

• Aqua

• White

print.magenta( 'I sound like a toner cartridge' );
print.greenText( "You wouldn't like me when I'm angry" );
print.somethingBlue( 'UHF ' );

To view all the color names run the system-colors command.

print.MistyRose3( 'Fancy colors' );

Background Color

If the method has a valid color name preceded by the word "on", the background of the text will be that color.

• onBlack

• onRed

• onGreen

• onYellow

• onBlue

• onMagenta

• onCyan

• onWhite

• etc...

print.blackOnWhiteText( 'Inverse!' );
print.greenOnRedLine( "Christmas?" );

Color by Numbers

When you run the system-colors command, you'll see that each of the 256 colors have a number. You can reference a color like so:

print.color221( 'I will print PaleVioletRed1' );

Text Decoration

If any of the following words appear in the method, their decoration will be added. Note, not all of these work on all ANSI consoles. Blink, for instance, doesn't seem to work in Windows.

• bold

• underscored

• blinking

• reversed - Inverse of the default terminal colors

• concealed

• indented

print.boldText( "Don't make me turn this car around!" );
print.underscoredLine( "Have I made my point?" );

indented isn't part of the ANSI standard but rather a nice way to indent each line of output with two spaces to help clean up nested lines of output. If the string being passed in has carriage returns, each of them will be preceded by two spaces.

print.boldText( "Header" )
    .indentedLine( "Detail 1" )
    .indentedLine( "Detail 2" )
    .indentedLine( "Detail 3" );

Mix It Up

Any combination of the above is possible. Filler words like "text" will simply be ignored so you can make your method nice and readable. Get creative, but just don't overdo it. No one wants their console to look like a rainbow puked on it.

print.redOnWhiteLine( 'Ready the cannons!' );
print.boldRedOnBlueText( "Test dirt, don't wash." );
print.boldBlinkingUnderscoredBlueTextOnRedBackground( "That's just cruel" );

Dynamic Formatting

Some times you want to apply formatting at run time. For instance, show a status green if it's good and red if it's bad. You can pass a second string to the print helper with additional formatting that will be appended to the method name.

print.text( status, ( status == 'running' ? 'green' : 'red' ) );

Depending on the value of the status variable, that line would be the same as one of the following two lines:

print.greenText( status );
print.redText( status );

Flush

If you have a command that takes a while to complete and you want to update the user right away, you can flush out everything in the buffer to the console with the .toConsole() method. Note, any text flushed to the console cannot be piped to another command.

print.Line( 'Step 1 complete' ).toConsole();
print.Line( 'Step 2 complete' ).toConsole();
print.Line( 'Step 3 complete' ).toConsole();

Chaining

All the methods in the print object can be chained together to clean up your code.

print.whiteOnRedLine( 'ERROR' )
    .line()
    .redLine( message )
    .line();

If you want users to be able to pass file globbing patterns to your command, set a type of Globber for the argument.

Even though the user types a string, CommandBox will hand you a CFC instance that's preloaded with the matching paths and has some nice methods to help you interact with the matching paths. The Globber object lazy loads the matches, which gives you time to affect the pattern or even the sort if you wish prior to the file system actually being hit.

Globber.count()

Use the count() method to get the total number of paths matched on the file system.

Globber.apply( ... )

The easiest way to apply some processing to each of the file paths found is by passing a closure to the apply() method. The closure will be executed once for each result.

Globber.matches()

To get the raw results back, use the matches() method.

Globber.asQuery()

If you want to get the results back as a query object, use the asQuery() method and then you can loop over them yourself. The query contents match what comes back from directoryList().

Globber.asArray()

If you want to get the results back as an array, use the asArray() method and then you can loop over them yourself.

Globber.withSort( ... )

Affect the order that the results come back by setting a sort. The sort follows the same pattern as the directoryList() function, which means it can be a comma-delimited list of columns to sort on.

Globber.getPattern()

To get the original globbing pattern that the user typed, use the getPattern() method on the Globber CFC.

Create your own Globber

You can create your own File Gobber object from any pattern using the globber() method. You can pass a comma delimited list or an array of globber patterns to the constructor.

You can also add additional glob patterns to an existing Globber object.

Exclude Patterns

Sometimes when using a Globbing pattern, it's desirable to exclude a small number of patterns and it's cumbersome to manually include every pattern you want. You can set more than one excludes pattern to be passed to filter the matches. Excludes follow the same format as include patterns. If a pattern is both excluded and included, the exclude wins.

Excludes, like includes, allow for a comma-delimited list or an array to be passed.

The setExcludePattern() method will override any existing methods, but the addExcludePattern() method will add to the existing list.

Tab completion and help are powered by metadata on your command CFCs. For basic command and parameter tab completion to work you don't need to do anything. CommandBox will look at the metadata of your command and just use it.

Command Help

When a user types yourCommand help, the text they see is the hint attribute on the component. The easiest way to add this is via a Javadoc-style comment at the top of your component. Feel free to include sample executions which can be wrapped in {code:bash}{code} blocks.

Parameter Help

You'll also want to provide hints for each of the parameters to the run() method. This will also be visible in the help command as well as the Command API docs.

Parameter Value Completion

When a user hits tab while typing a parameter value, booleans will prompt with true/false. Parameters with directory, destination, file, or path in their names will automatically give file system suggestions.

You can provide additional hints though for your parameters to make them super user friendly.

If you have a parameter that doesn't contain one of the keywords above but you still want it to provide the user with path, directory, or file tab completion, you can add annotations to the arguments to enable this.

• optionsFileComplete

• optionsDirectoryComplete

Ex:

A parameter can have both the annotations for file and directory completion as well as an optionsUDF or options list specified and they will all be used. The user will be presented with the combined list of tab completion candidates.

Static Options

If a parameter has a set number of exact options, you can specify an options attribute for that parameter that is a comma-delimited list of options for tab completion to give.

Options UDF

If a parameter's values are dynamic, you can specify a optionsUDF attribute for that parameters that points to a function name in the command CFC that will be called. This function needs to return an array of all possible values. CommandBox will do the work of filtering down partial matches if they're in the middle of typing.

An example of this in action is the install command. It will auto-complete the ForgeBox slug for you. Try typing install cold and hitting tab to see what happens.

Instead of just passing back an array of strings from your options UDF, you can pass an array of structs to provide the following for each option:

• name (required)

• group

• description

Smart Tab Complete

Your tab complete UDF is called every time the user hits tab, but sometimes the options you want to present are based on some context. There are two parameters to your UDF which give you some context.

• paramSoFar - A string containing the text the user has typed thus far. CommandBox will automatically filter the candidates you send back, if if you're doing something complicated like making an API call to get the candidates, this allows you to do some pre-filtering of your own. This string may be empty if they haven't typed anything yet.

• passedNamedParameters - A struct containing the parameters the user has typed already. You get name/value pairs even if the user is typing positional params. This is handy if the possible options for one parameter are based on what is being passed for another parameter. The struct may be empty, or may only contain some params. Always check existence!

Namespace help

If you have a namespace (folder) of commands, you can control what the user sees when they type namespace help by creating a command CFC called help.cfc in the root of that folder. The help command should print out whatever information you want. CommandBox will automatically call it when the users needs help for that namespace.