CommandBox : CLI, Package Manager, REPL & More
5.4.0
5.4.0
  • Introduction
  • About This Book
  • Authors
  • Overview
  • Release History
    • 5.x Versions
      • What's New in 5.4.2
      • What's New in 5.4.1
      • What's New in 5.4.0
      • What's New in 5.3.1
      • What's New in 5.3.0
      • What's New in 5.2.1
      • What's New in 5.2.0
      • What's New in 5.1.1
      • What's New in 5.1.0
      • What's New in 5.0.0
    • 4.x Versions
      • What's new in 4.8.0
      • What's New in 4.7.0
      • What's New in 4.6.0
      • What's New in 4.5.0
      • What's New in 4.4.0
      • What's New in 4.3.0
      • What's New in 4.2.0
      • What's New in 4.1.0
      • What's New in 4.0.0
    • 3.x Versions
      • What's New in 3.9.0
      • What's New in 3.8.0
      • What's New in 3.7.0
      • What's New in 3.6.0
      • What's New in 3.5.0
      • What's New in 3.4.0
      • What's New in 3.3.0
      • What's New in 3.2.0
      • What's New in 3.1.1
      • What's New in 3.0.1
      • What's New in 3.0.0
    • 2.x Versions
      • What's New in 2.2.0
      • What's New in 2.1.1
      • What's New in 2.1.0
      • What's New in 2.0.0
    • 1.x Versions
      • What's in 1.0.0
  • Getting Started Guide
  • Setup
    • Requirements
    • Download
    • Installation
    • Light and Thin Binaries
    • Non-Oracle JREs
    • Upgrading
    • Common Errors
  • Usage
    • Execution
      • Recipes
      • CFML Files
        • Using a DB in CFML scripts
      • OS Binaries
      • CFML Functions
      • Exit Codes
    • Commands
    • Parameters
      • Escaping Special Characters
      • File Paths
      • Globbing Patterns
      • Piping into Commands
      • Expressions
    • Command Help
    • Environment Variables
    • System Settings
    • System Setting Expansion Namespaces
    • Ad-hoc Command Aliases
    • Default Command Parameters
    • REPL
    • Tab Completion
    • Interactive Shell Features
    • forEach Command
    • watch Command
    • jq Command
    • printTable Command
    • sql Command
    • Auto Update Checks
    • Bullet Train Prompt
    • 256 Color Support
    • A Little Fun
  • IDE Integrations
    • Sublime Text
    • Visual Studio Code
  • Config Settings
    • Module Settings
    • Proxy Settings
    • Endpoint Settings
    • Server Settings
    • JSON Settings
    • Misc Settings
    • Task Runner Settings
    • Env Var Overrides
  • Embedded Server
    • Multi-Engine Support
    • Server Versions
    • Start HTML Server
    • Offline Server Starts
    • Debugging Server Starts
    • Server Processes
    • Manage Servers
    • FusionReactor
    • Server Logs
    • Configuring Your Server
      • Server Profiles
      • Server Rules
        • Baked in Rules
        • Allowed Static Files
        • Rule Language
        • Custom Predicates/Handlers
        • Rule Examples
        • Debugging Server Rules
      • JVM Args
      • Server Port and Host
      • SSL Certs
      • HTTPS Redirect/HSTS
      • URL Rewrites
      • Aliases
      • Custom Error Pages
      • Welcome Files
      • Basic Authentication
      • Custom Java Version
      • Adding Custom Libs
      • GZip Compression
      • REST Servlet
      • Performance Tuning
      • Undertow Options
      • Custom Tray Menus
      • Ad-hoc Env Vars
      • server.json Env Var overrides
      • Server Home
      • web.xml Overrides
      • Experimental Features
    • External Web Server
    • Starting as a Service
    • Single Server Mode
    • Server.json
      • Working with server.json
      • Packaging Your Server
      • Using Multiple server.json Files
  • Package Management
    • Installing Packages
      • Installation Path
      • Installation Options
      • Advanced Installation
    • Private Packages
    • System Modules
    • Code Endpoints
      • ForgeBox
      • HTTP(S)
      • File
      • Folder
      • Git
      • Java
      • S3
      • CFLib
      • Jar (via HTTP)
      • Lex (via HTTP or File)
      • Gist
    • Package Scripts
    • Dependencies
    • Semantic Versioning
    • Updating Packages
    • Creating Packages
      • Editing Package Properties
      • Publishing Lucee Extensions to ForgeBox
    • Artifacts
    • Box.json
      • Basic Package Data
      • Extended Package Data
      • Package URLs
      • Installation
      • Embedded Server
      • Dependencies
      • TestBox
    • Managing Version
  • Task Runners
    • Task Anatomy
    • BaseTask Super Class
    • Task Target Dependencies
    • Passing Parameters
    • Using Parameters
    • Task Output
      • Printing tables
    • Lifecycle Events
    • Threading/Async
    • Task Interactivity
    • Shell Integration
    • Downloading Files
    • Running Other Commands
    • Error Handling
    • Hitting Your Database
    • Sending E-mail
    • Interactive Jobs
    • Watchers
    • Property Files
    • Running other Tasks
    • Loading Ad hoc Jars
    • Loading Ad-hoc Modules
    • Cancel Long Tasks
    • Progress Bar
    • Caching Task Runners
  • Helpful Commands
    • Token Replacements
    • Checksums
    • Code Quality Tools
    • ask and confirm
  • Deploying CommandBox
    • Github Actions
    • Docker
    • Heroku
    • Amazon Lightsail
  • TestBox Integration
    • Test Runner
    • Test Watcher
  • Developing For CommandBox
    • Modules
      • Installation and Locations
      • Configuration
        • Public Properties
        • Configure() Method
        • Lifecycle Methods
      • Conventions
      • User Settings
      • Linking Modules
    • Commands
      • Aliases
      • Using Parameters
        • Using File Globs
        • Dynamic Parameters
      • Command Output
      • Tab Completion & Help
      • Interactivity
      • Watchers
      • Shell integration
      • Running Other Commands
      • Error handling
      • Watchers
      • Loading Ad hoc Jars
    • Interceptors
      • Core Interception Points
        • CLI Lifecycle
        • Command Execution Lifecycle
        • Module Lifecycle
        • Server Lifecycle
        • Error Handling
        • Package Lifecycle
      • Custom Interception Points
    • Injection DSL
    • Example Project
    • FusionReactor for the CLI
  • ForgeBox Enterprise
    • Introduction
    • Storage
    • Commands
      • List
      • Register
      • Login
      • Set Default
      • Remove
    • Usage
Powered by GitBook
On this page
  • The DSL
  • task()
  • target()
  • params()
  • Named parameters
  • Positional parameters
  • Using argumentCollection
  • flags()
  • inWorkingDirectory()
  • run()
  • Handling Exceptions

Was this helpful?

Edit on Git
Export as PDF
  1. Task Runners

Running other Tasks

When developing a task, you may find the need to run another task. To do this, we have provided you with a DSL you can use to call any task. The Task DSL is very similar to the Command DSL, but designed to delegate to the task run command for you.

The DSL

The DSL is a sequence of chained methods that will always start with task() and end with .run(). The run method tells the DSL that you are finished chaining methods and that the task should be executed. Here is the simplest possible example:

task().run();

This would run a task.cfc in the current working directory and the output would be flushed to the console.

Here are all the possible DSL methods that we'll unpack below:

task( ... )
    .target( ... )
    .params( ... )
    .flags( ... )
    .inWorkingDirectory( ... )
    .run( ... );

task()

This is required to be the first method you call. It creates an instance of the TaskDSL class and returns it. It accepts a single parameter called taskFile which is the path of the task CFC you wish to run. Just like the task run command, you can supply a full path or a relative path. The .cfc extension is also optional. If you don't pass in a task CFC name, it defaults to task.

task( 'build' )
    .run();

 task( 'C:/path/to/task.cfc' )
    .run();

target()

Use this method to override the default task target of run.

task()
    .target( '' )
    .run();

 task( 'C:/path/to/task.cfc' )
    .run();

params()

This method is used to pass parameters to your command. You can pass named or positional parameters to this method, and they will be pass along to the command in the same fashion. There is no need to escape parameter values like you would when running a command manually from the shell.

Named parameters

task( 'mytask' )
    .params( path='/my/path', newPath='/my/new/path' )
    .run();

Positional parameters

 task( 'mytask' )
    .params( '/my/path', '/my/new/path' )
    .run();

Using argumentCollection

args = {
   "arg1": true,
   "arg2": "something else"
};
task( 'mytask' )
    .params( argumentCollection=args )
    .run();

flags()

Just like when running a task manually, flags are an optional shortcut for specifying boolean parameters. Pass in each flag as a separate argument. It is not necessary to include the -- prior to the value, but it will still work.

 task( "mytask" )
    .params( 'coldbox' )
    .flags( 'force', '!save' )
    .run();

inWorkingDirectory()

Control the working directory that the task runs in if you don't want it to be the current working directory of the shell.

task()
.inWorkingDirectory( 'C:/' )
.run();

run()

Your DSL should always end with a run method. This executes the task. By default, the output will be sent to the console, however you can capture it by specifying returnOutput as true.

var output =  task()
      .params( "My name is Brad" )
      .run( returnOutput=true );

// You can optinally strip any ANSi formatting too
output = print.unANSI( output );

If you want to help debug the exact task that is being passed along to the shell for executing, set the echo parameter to true and the task will be echoed out prior to execution. The echoed text is not part of what gets returned.

task()
    .run( echo=true );

Handling Exceptions

If a task encounters an error or returns a non-zero exit code, the Task DSL will throw an exception. if you want to ignore failing tasks or rethrow an exception of your own design, you may place the task in a try/catch. The exit code of the task may be accessed via:

  • The ${exitCode} environment variable

  • The errorcode property of the exception if the error() method was used

  • Calling getExitCode() on the Task DSL object

try { 
  var t = task( 'myTask' )
  t.run();
}  catch( any var e ) {
  print.line( 'myTask errored with #t.getExitCode()#, but we ignoring it.' );
}
PreviousProperty FilesNextLoading Ad hoc Jars

Last updated 4 years ago

Was this helpful?