commandbox-task-runners

name	commandbox-task-runners
description	Use this skill for CommandBox task runners: creating task CFCs, targets, passing parameters, lifecycle events (preTask/postTask/onError), interactive jobs with job DSL, progress bars, async/threading with AsyncManager, watching files, running commands from tasks, shell integration, property files, downloading files, sending email from tasks, and task target dependencies.

CommandBox Task Runners

Overview

Task Runners are CFML/BoxLang CFCs that automate build processes, migrations, and workflows. They are analogous to Ant/Gradle tasks but written in CFML. Tasks live in your project folder and are not globally registered — they are context-aware based on your current working directory.

# Create a default task.cfc
task create

# Create and open in editor
task create --open

# Run the default task
task run

# Run a specific task file
task run path/to/myTask

# Run a specific target
task run path/to/myTask myTarget

---

Task Anatomy

/**
 * My build task
 */
component {

    // WireBox DI available
    property name="artifactService" inject="artifactService";

    /**
     * Default target — runs when no target specified
     */
    function run() {
        print.greenLine( "Build complete!" );
    }

    /**
     * Named target
     */
    function build() {
        print.line( "Building..." );
        command( "package version patch" ).run();
        print.greenLine( "Built!" );
    }

    /**
     * Target with parameters
     */
    function deploy( required string environment, boolean verbose=false ) {
        print.line( "Deploying to #environment#" );
        if ( verbose ) {
            print.yellowLine( "Verbose mode on" );
        }
    }

}

Default conventions:

• Default task file: task.cfc in current directory
• Default target method: run()

task run                              # runs task.cfc::run()
task run build                        # runs task.cfc::build()
task run workbench/build              # runs workbench/build.cfc::run()
task run workbench/build createZips   # runs workbench/build.cfc::createZips()

---

Passing Parameters

Named parameters (recommended)

task run fun greet :name=Brad :verbose=true

Positional parameters

task run fun greet Brad true

Boolean flags

task run --:verbose
task run --no:verbose
task run --!:verbose

Dynamic values

task run :message=`cat message.txt`
task run taskFile=deploy :env=${DEPLOY_ENV:staging}

---

Lifecycle Events

Special methods that fire automatically around target execution:

component {

    // Before ANY target
    function preTask( string target, struct taskArgs ) {
        print.line( "Starting task: #target#" );
    }

    // After ANY target
    function postTask( string target, struct taskArgs ) {
        print.line( "Finished task: #target#" );
    }

    // Wrap ANY target (must call invokeUDF to run the target)
    function aroundTask( string target, struct taskArgs, any invokeUDF ) {
        var startTime = getTickCount();
        local.result = invokeUDF();
        print.line( "Elapsed: #(getTickCount()-startTime)#ms" );
        return local.result;  // IMPORTANT: return result to preserve exit codes
    }

    // Before specific target
    function preRun() {
        print.line( "Before run" );
    }

    // After specific target
    function postRun() {
        print.line( "After run" );
    }

    // Fires regardless of success/failure
    function onComplete( string target, struct taskArgs ) {
        print.line( "Always fires" );
    }

    // Fires on success only
    function onSuccess( string target, struct taskArgs ) {
        print.greenLine( "Task succeeded!" );
    }

    // Fires on any failure (no exception object)
    function onFail( string target, struct taskArgs ) {
        print.redLine( "Task failed!" );
    }

    // Fires only on unhandled exceptions — has exception object
    function onError( string target, struct taskArgs, any exception ) {
        print.redLine( "Exception: #exception.message#" );
    }

    // Fires when Ctrl+C is pressed
    function onCancel( string target, struct taskArgs ) {
        print.yellowLine( "Task cancelled by user" );
    }

    function run() {
        print.line( "Hello!" );
    }

}

Limit lifecycle events to specific targets:

this.preTask_only = "run,build";       // only fire for run and build
this.postTask_except = "cleanUp";      // fire for all except cleanUp

---

Task Target Dependencies

component {

    // Define dependencies
    this.depends_build = "clean,compile";

    function clean() {
        directoryDelete( "dist", true );
    }

    function compile() {
        // compile step
    }

    // build will run clean, then compile, then itself
    function build() {
        zip( action="zip", file="dist/app.zip", source="src" );
    }

}

---

Interactive Jobs (Progress Display)

function run() {
    // Start a named job
    job.start( "Deploying application" );

    job.addLog( "Connecting to server..." );
    // ... work ...

    job.addSuccessLog( "Connected!" );
    job.addWarnLog( "Using staging credentials" );
    job.addErrorLog( "Warning: old config detected" );
    job.addLog( "Uploading files..." );

    if ( success ) {
        job.complete();        // green success line
    } else {
        job.error( "Deploy failed: connection refused" );  // red error
    }

    // Nested jobs
    job.start( "Running migrations", lineSize=10 );
    job.addLog( "Migration 001..." );
    job.addLog( "Migration 002..." );
    job.complete();
}

---

Progress Bar

function run() {
    var total = 100;
    progressBar.update( percent=0, currentCount=0, totalCount=total );

    for ( var i = 1; i <= total; i++ ) {
        // do work
        progressBar.update( percent=int((i/total)*100), currentCount=i, totalCount=total );
    }

    print.line();  // newline after bar
}

---

Print Helper (ANSI Output)

function run() {
    print.line( "Normal text" );
    print.greenLine( "Success message" );
    print.redLine( "Error message" );
    print.yellowLine( "Warning" );
    print.cyanLine( "Info" );
    print.boldLine( "Bold text" );
    print.boldGreenLine( "Bold green" );

    // Inline (no newline)
    print.green( "Processing..." );
    print.line();

    // Table output
    print.table(
        headers = [ "Name", "Version", "Status" ],
        data = [
            [ "coldbox", "7.0.0", "active" ],
            [ "testbox", "5.0.0", "active" ]
        ]
    );
}

---

Running Commands from Tasks

function run() {
    // Run a CommandBox command
    command( "install coldbox" ).run();

    // Capture output
    var result = command( "package show version" ).run( returnOutput=true );
    print.line( "Version: #result#" );

    // Chain commands
    command( "server stop" )
        .params( name="myApp" )
        .run();

    // Run OS commands with !
    command( "!git pull origin main" ).run();

    // Check exit code
    var exitCode = command( "testbox run" ).run( returnExitCode=true );
    if ( exitCode != 0 ) {
        error( "Tests failed!" );
    }
}

---

Shell Integration

function run() {
    // Run OS shell commands
    var result = shell( "ls -la" );

    // On Windows
    var result = shell( "dir" );

    // Run with specific working directory
    shell( command="npm install", dir="/my/app" );
}

---

Async / Threading

function run() {
    // Use cfthread with unique names
    var threadName = createGUID();
    cfthread( action="run" name=threadName ) {
        // thread body
    }
    cfthread( action="join" name=threadName );

    // Async with AsyncManager
    var results = async().all(
        () => command( "install module1" ).run( returnOutput=true ),
        () => command( "install module2" ).run( returnOutput=true )
    ).get();
}

---

Watching Files

function run() {
    // Watch and re-run task on changes
    watch()
        .paths( "**.cfc,**.cfm" )
        .inDirectory( getCWD() )
        .withDelay( 500 )
        .onChange( function() {
            command( "testbox run" ).run();
        } )
        .start();
}

---

Property Files

function run() {
    // Read .properties file
    var props = propertyFile( getCWD() & "/config.properties" );
    var dbHost = props[ "db.host" ];

    // Write properties
    props[ "build.version" ] = "2.0.0";
    props.store();
}

---

Downloading Files

function run() {
    // Download a file with progress
    var filePath = getCWD() & "/downloads/package.zip";
    progressable
        .download( "https://example.com/package.zip", filePath )
        .withProgressBar()
        .start();
}

---

Sending Email from Tasks

function run() {
    // Send email using bx-mail module (if installed)
    bx:mail
        from="[e-mail]"
        to="[e-mail]"
        subject="Build #packageVersion# complete"
        server="#mailServer#"
        port=587
    {
        writeOutput( "The build finished successfully." );
    }
}

---

Cancelling Long Tasks

function run() {
    // Check if user has pressed Ctrl+C
    for ( var i = 1; i <= 1000; i++ ) {
        // Check for cancellation
        if ( isCancelled() ) {
            print.yellowLine( "Cancelled at step #i#" );
            return;
        }
        // do work
    }
}

function onCancel() {
    // cleanup on Ctrl+C
    print.redLine( "Cleaning up temporary files..." );
    directoryDelete( "/tmp/build", true );
}

---

Hitting a Database

component {

    // Inject a datasource via WireBox
    property name="datasource" inject="coldbox:datasource:myDS";

    function run() {
        var q = queryExecute(
            "SELECT * FROM users WHERE active = :active",
            { active: { value: 1, cfsqltype: "integer" } },
            { datasource: "myDS" }
        );
        q.each( function( row ) {
            print.line( "#row.name# - #row.email#" );
        } );
    }

}

---

Loading Ad-Hoc JARs

component {

    function run() {
        // Load a JAR into the class path
        classLoad( getCWD() & "/lib/mylib.jar" );
        var obj = createObject( "java", "com.example.MyClass" );
    }

}

---

Loading Ad-Hoc Modules

component {

    function run() {
        // Temporarily load a module
        modulesConfig = { "myTempModule": { "path": getCWD() & "/myModule" } };
        moduleService.registerAndActivateModule( "myTempModule", getCWD() & "/myModule" );

        // Use module functionality
        var svc = getInstance( "myService@myTempModule" );
        svc.doWork();
    }

}