If you’re a recently minted web application developer, using Command Line Interfaces is just a de facto way of life for you. You might use it to spin up a new application, you might run a web pack workflow from it. You use it to push, pull, commit and fetch in Git.

But what about ColdFusion? You might have heard that ColdFusion has a command line interface (well… actually we have a couple!), but what can it do? Turns out, quite a lot! Let’s get you introduced to the CF CLI!

To use the CF CLI you’ll need access to an installed version of CF. If you don’t currently have a copy running locally, you can head over to https://www.adobe.com/products/coldfusion/download-trial/try.html and download a copy. You can choose either the full version or the 147mb “light” version.

Once you’ve installed ColdFusion and it is running successfully (hit the admin at http://localhost:8500/CFIDE/administrator/index.cfm or whatever port you’re running at to be sure) you’ll want to spin up one of your built in command interfaces. On Windows that could be Command (open search and type “cmd”) or Powershell (open search and type powershell) or on Mac it could be the terminal.

Navigate to the folder you installed ColdFusion in. For me that was C:ColdFusion. Then navigate to cfusionbin. Execute CF.bat.

You should now have a cursor that looks like this:

cf-cli>

Fantastic! You’re now running ColdFusion in interactive mode under the CLI. Now what?

Well, let’s try setting a variable. Type in:

numericValue = 4;

You’ll see that the CLI will echo that value back to you. By the way, semicolons are optional, I just use them out of habit.

Let’s read that variable back. That’s as easy as just typing:

writeOutput(numericValue);

The CLI will output 4 to the console. OK so there’s your “Hello World”. Let’s go a little deeper. What about writing a function? Sure! No problem. But before you do that, here’s a little tip on the CF CLI. When the CLI detects that you are going to be writing something that will be multi-line (like, for example, a function), when you hit the enter key, instead of executing the line, it will enter multi-line mode. Now, if you want to do multi-line without some kind of logical block indicator (such as { ) you can add a space followed by a caret (^). When you wish to exit multiline, simply type multilineexit.

Now that’s out of the way, let’s write a function:

function addThreeThings(arg1,arg2,arg3){
   var totalValue = arg1 + arg2 + arg3;
   writeOutput(totalValue);
}

OK! Neat. Nothing really seems to have happened though, right? Yep. The function has been added to the CLI, but now we need to call it. So type:

addThreeThings(1,2,3);

The CLI will return 6 to the console. Which is 1 + 2 + 3. Perfect. What else can we do? Well, if the function is active in the CLI, can we call it with another function? Absolutely.

function passThreeThings(arg1,arg2,arg3){
addThreeThings(arg1,arg2,arg3);
}

Now call that function as follows:

passThreeThings(2,3,4);

The console will return 9. As it should, since 2 + 3 + 4 = 9.

There’s lots you can do directly in the console, but what about calling external files? You can do that by simply typing the name of the file in the console. Download the zip file attached to this blog and extract to your bin folder (or a different one but keep in mind you’ll need to adjust the code to target the files in the location you choose).

Go ahead and type:

test0.cfm

You should get the following output:

Hello World
Hello World using cli.writeLn

The code in that file looks like this:

<cfscript>
// writeOutput() works the same as it does normally.
writeOutput("Hello World");
// But you can also output using CLI.writeLn()
CLI.writeLn("");
CLI.writeLn("Hello World using cli.writeLn");
</cfscript>

All we’re showing is that you can output to the CLI using both writeOutput() and CLI.writeLn().

Next, go ahead and try hitting test1.cfm. You’ll note that it will error. That’s because it is expecting at least one argument value to be passed. Try it again by typing:

test1.cfm 1

Arguments are passed as space delimited values after the name of the file. You’ll notice also that it lists out “First Argument”. The way it gets that is by using the CLI.getArg() function and selecting the 1st value in the array (this is where the error occurs by the way in the earlier attempt to run this file, position 1 was out of index because the array had no length). As always, arrays in ColdFusion begin at position 1.

The code for this file is as follows:

<cfscript>
// Using the CLI.getArgs() function to dump passed arguments
writeDump(var=CLI.getArgs(), label="All arguments");
// You can use CLI.writeLn() to write directly to the CLI
CLI.writeLn("");
// Display the first argument here
CLI.writeLn("First argument: " & CLI.getArg(1));
</cfscript>

Let’s try the next file, test2.cfm. This time around, the file will be expecting named arguments. So type the following:

test2.cfm one=1 two=2

You’ll get back a struct with the two named args (returned via CLI.getNamedArgs()) and a single named argument (with the key “two”) that returns the value 2.

One thing to understand about the CLI is that it only supports a subset of all of the scopes when working in the CLI (and hitting files that load there), and a subset of methods when interacting with the application.cfc file in any folder you’re working in.

CLI Supported Scopes
Application
Argument
Request
This

Application.cfc supported methods
onApplicationStart()
onApplicationStop()
onError()
(there is no support for session or request methods in the CLI)

If you load up test3.cfm you can see an example of loading 2 request scope variables into the CLI and then dumping the scope to screen using writeDump().

The file contents are as follows:

<cfscript>
function writeRequestToScreen(){
REQUEST.arg1 = "Request variable 1";
REQUEST.arg2 = "Request variable 2";
writeDump(REQUEST);
}
writeRequestToScreen();
</cfscript>

Note: If you attempt to view this file twice, you will find that it errors. This is because by viewing the file, you are loading it into the CLI. Since this file includes a function, it will error, as the function has already been instantiated. However, if you just type writeRequestToScreen() in the CLI, you will see the request variables dumped to screen. This is because the file is no longer needed to run the function.

So that is just a brief introduction to the ColdFusion Command Line interface. This blog is based on a webinar I recently gave on both this CLI as well as the Package Manager CLI. That webinar will be available here soon: https://coldfusion.adobe.com/webinar/