CommandBox : CLI, Package Manager, REPL & More
4.6.0
4.6.0
  • Introduction
  • About This Book
  • Authors
  • Overview
  • Getting Started Guide
  • Setup
    • Requirements
    • Download
    • Installation
    • 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
    • Ad-hoc Command Aliases
    • Default Command Parameters
    • REPL
    • Tab Completion
    • Interactive Shell Features
    • forEach 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
    • Misc Settings
  • Embedded Server
    • Multi-Engine Support
    • Offline Server Starts
    • Debugging Server Starts
    • Server Processes
    • Manage Servers
    • FusionReactor
    • Server Logs
    • Configuring Your Server
      • JVM Args
      • Server Port and Host
      • URL Rewrites
      • Aliases
      • Custom Error Pages
      • Welcome Files
      • Basic Authentication
      • Custom Java Version
      • Adding Custom Libs
      • GZip Compression
      • REST Servlet
    • External Web Server
    • Starting as a Service
    • 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
      • RIAForge
      • Jar (via HTTP)
      • Gist
    • Package Scripts
    • Dependencies
    • 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
    • Task Target Dependencies
    • Passing Parameters
    • Using Parameters
    • Task Output
    • Task Interactivity
    • Shell Integration
    • Downloading Files
    • Running Other Commands
    • Error Handling
    • Hitting Your Database
    • Interactive Jobs
    • Watchers
    • Property Files
    • Running other Tasks
    • Loading Ad hoc Jars
    • Loading Ad-hoc Modules
    • Cancel Long Tasks
    • Progress Bar
  • Helpful Commands
    • Token Replacements
    • Checksums
    • Code Quality Tools
  • Deploying CommandBox
    • Docker
    • Heroku
  • 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
  • ForgeBox Enterprise
    • Introduction
    • Storage
    • Commands
      • List
      • Register
      • Login
      • Set Default
      • Remove
    • Usage
Powered by GitBook
On this page
  • The DSL
  • command()
  • params()
  • Named parameters
  • Positional parameters
  • flags()
  • append() and overwrite()
  • inWorkingDirectory()
  • pipe()
  • run()

Was this helpful?

Edit on Git
Export as PDF
  1. Developing For CommandBox
  2. Commands

Running Other Commands

Many times when developing a command, you find the need to run another, existing command. To do this, we have provided you with a DSL you can use to call any command, pass parameters, and even pipe commands together.

The DSL

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

command( 'version' )
    .run();

This runs the version command and the output will be flushed to the console.

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

command( ... )
    .params( ... )
    .flags( ... )
    .append( ... )
    .overwrite( ... )
    .run( ... );

command()

This is required to be the first method you call. It creates an instance of the CommandDSL class and returns it. It accepts a single parameter called name which is the name of the command you wish to run. Type the name exactly as you would in the shell including the namespace, if applicable.

command( 'info' )
    .run();

command( 'server start' )
    .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

command( 'cp' )
    .params( path='/my/path', newPath='/my/new/path' )
    .run();

Positional parameters

command( 'cp' )
    .params( '/my/path', '/my/new/path' )
    .run();

flags()

Just like when running a command 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.

command( "install" )
    .params( 'coldbox' )
    .flags( 'force', '!save' )
    .run();

append() and overwrite()

You may redirect the output of a command to a file (normally accomplished by > and >>) by chaining the append() or overwrite() methods. These are mutually exclusive.

command( "cat" )
    .params( "myFile.txt" )
    .append( "myOtherFile.txt" )
    .run();

command( "echo" )
    .params( "Your new file contents" )
    .overwrite( "myFile.txt" )
    .run();

inWorkingDirectory()

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

command( "ls" )
    .inWorkingDirectory( 'C:/' )
    .run();

pipe()

Piping is a very powerful way to combine multiple commands and is accomplished via the pipe method. This method expects to receive another CommandDSL instance. You do not need to call run() on the nested command. This example is the equivalent to echo "hello\nworld" | grep lo.

command( "echo" )
    .params( "hello#chr( 10) #world" )
    .pipe( 
        command( "grep" )
        .params( "lo" )
    )
    .run();

You can have more than one pipe() method. Each piped command will be called in order, receiving the output from the previous one.

command( "cat" )
    .params( "myFile.txt" )
    .pipe( 
        command( "grep" )
        .params( "searchString" )
    )
    .pipe( 
        command( "sed" )
        .params( "s/find/replace/g" )
    )
    .pipe( 
        command( "more" )
    )
    .run();

The above is the equivalent of

cat myFile.txt | grep searchString | sed s/find/replace/g | more

run()

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

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

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

command( "version" )
    .run( echo=true );

You may want to manually pipe data into the command (which is the same as passing it as the first parameter. Do so with the piped parameter to the run method.

command( "touch" )
    .run( piped='myFile' );

If you try to pass a shell expansion into a command, it won't work since the CommandDSL escapes all your special characters. This example doesn't work because the special characters are escaped. So the exact text is printed out and it's not possible to have it evaluated.

command( 'echo' )
  .params( '${ os.name }' )
  .run();
------------------------------------------
Output: ${ os.name }

You can ask the CommandDSL to treat your parameters as 'raw' so they are just passed along. This allows them to include system setting expansions and CommandBox backtick expressions. Make sure that you escape any special chars yourself in this mode just like you would if typing the parameters from the shell.

command( 'echo' )
  .params( '${ os.name }' )
  .run( rawParams=true );
------------------------------------------
Output: Windows 7
PreviousShell integrationNextError handling

Last updated 7 years ago

Was this helpful?