by Harikrishna Kallae

Harikrishna Kallae

 

by Himavanth Rachamsetty

Harikrishna Kallae

Table of contents

Created

15 March 2016

Requirements    
Prerequisite knowledge
Required products
User level
This article does not require you to be an expert in ColdFusion. A general understanding of ColdFusion tags and other core language syntax is enough to get most out of this article.
Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)
All

 
Introduction

Adobe ColdFusion (2016 release) comes with a Command Line Interface (CLI) for developers to run cfm scripts without a running ColdFusion server.
CLI can be used to write CRON jobs with:
  • File operations for reporting, logging, archiving, and so on.
  • Database operations for monitoring, debugging, and so on.
  • Network operations like mailing an error log or thread dump to a system admin.
 
Note: The CLI utility is located in the cf_root/bin (server configuration) or cf_webapp_root/WEB-INF/cfusion/bin (J2EE configuration) directory. Before you can use the CLI utility in the J2EE configuration, set the CFUSION_HOME, J2EEJAR, and WEBINF variables in the cf.bat/cf.sh file.
Each time you call the CLI, a light-weight ColdFusion Server starts with minimal and default configuration settings. The server shuts down after CLI ends. You can make additonal changes to the CLI settings through Application.cfc and/or init parameters.
You can call CLI using cf.bat/cf.sh present in <cf_home>/bin folder. It is recommended that you add this path to the environment variables.
The cfm files can either be in wwwroot or in a different folder.
CLI help for usage : cf –help or cf --help
 
Syntax:
 
cf <path_to_cfm> <arguments>
Path to CFM
The path to the CFM can be either absolute or relative. An absolute path sets the directory of the cfm as wwwroot. A relative path sets the current working directory as wwwroot. This defines the level until which ColdFusion looks up for Application.cfc
Examples:
 
cf c:\cli\cliWriteOutput.cfm or cf cliWriteOutput.cfm
Arguments
From the command line, you can pass parameters to the cfm script. CLI supports both positional and named arguments to the executing cfm.
To read the arguments, CLI has the following methods:
cli.getArgs() - Gets all arguments.
cli.getNamedArgs()  - Gets all named arguments.
cli.getUnnamedArgs()  - Gets all unnamed args as a CFML array or an empty array if none are specified.
cli.getArg(int index) - Gets the argument at index location.
cli.getNamedArg(String argName) - Gets the value of the named argument with name argName.
Example
 
cf.bat test.cfm 10 20 foo=bar cli.getArg(1) returns 10 cli.getArg(3) returns foo=bar cli.getNamedArg("foo") returns bar
Custom directories
CLI takes custom output and log directories from command line. An output directory is used for ColdFusion compiled classes. Thelog directoryis used for logs. By default, both classes and logs go to temp folder.
Usage:
 
cf cliscript.cfm –outputdir=<path_to_classes_dir> –logdir=<path_to_log_dir>
Application.cfc
CLI supports the application life cycle of ColdFusion. The lookup for Application.cfc depends on the wwwroot, which is set according to the path of cfm (absolute or relative) during CLI invocation.
In Application.cfc, only onApplicationStart(), onApplicationStop(), and onError() methods are supported. There is no support for session and request methods in CLI.
Note: Application datasources are supported and are well suited for CLI.
Scopes
  • CLI supports the following scopes:
  • application
  • argument
  • request
  • this
Reading from and writing to command Line
CLI supports the following methods to read and write to stdin and stdout/stderr:
  • cli.read() - Reads one line from stdin.
  • cli.writeln(message) - Writes the message string to stdout.
  • cli.writeError(errorMessage) - Writes the error message string to stderr.
  • cli.exit(exitCode) - The exit function takes an optional status code and exits to the console with the specified exit code. By default, CLI returns an exitcode of 0 on successful execution and 1 when execution fails.
Note: Use CLI.Writeln() or WriteOutput() or WriteDump() methods for writing to console. Any content, HTML or otherwise, outside of these functions will not be dumped to console. In other words, CLI works as if enablecfoutputonly is set to true.
Example
readwrite.cfm
 
<cfset CLI.writeError("This is an error message from CLI writeError!")> <cfset CLI.writeln("This is CLI write method!")>
Usage
 
cf readwrite.cfm >> c:\logFile.txt 2>> c:\errFile.txt
Feature suport
CLI supports almost all the basic language features that are valid in a command line execution, including database, mail, webservice access, application life cycle and so on.
CLI does not support functionalities that:
  • require a running server  (like scheduled tasks, websocket, and so on)
  • require features that are usually implemented in a server product (like font loading that takes a lot of time, an http request, and so on)
In addition, CLI does not support:
  • Charting
  • Scheduled Tasks
  • PDF features
  • Document
  • REST
  • Solr
  • Flex Integration
  • DotNet Integration
  • WebSocket
  • Image Functions
  • API Manager