October 07, 2009
Many times when we are working on our ColdFusion apps there are situations in which we want to quickly evaluate something or try some one or two-liner snippets to do something quick. The typical process then is that we have to create a .cfm page, put in on the server, go to the browser and execute it. And that's pretty much the only way we have for interacting with the CFML engine. This contrasts with other languages like Ruby, Python, or even PHP in which you can quickly interact with the language directly from a command line or terminal window. Wouldn't it be nicer to have the inmmediate satisfaction of evaluating our CFML/cfscript statements interactively? Well, that's where CFShell comes in.
CFShell is an attempt to provide that level of interaction with the CFML engine. ColdFusion is pretty intertwined with the web/http environment, so a pure command line interface is a bit tricky (at least without serious Java hacking), so the next best thing is to provide a front end for interacting with the CF server through HTTP requests, but running it from the command line. CFShell is composed of two elements: a client and a server.
The CFShell client is written in Python, and acts as a front end for sending/receiving HTTP requests to the CF server. The server part is just a simple script (cfshell.cfm) that receives and executes the statements sent by the client. The client can send anything that can be put on a CFM template, for example:
All statements executed have an implicit cfoutput around.
For security the server part would only accept commands sent from the localhost, however this is NOT A TOY FOR PRODUCTION SERVERS!!!
Also, there wouldn't be any point of being interactive if we couldn't maintain some state between our commands; for that reason, cfshell uses the session scope to sync its local state between calls. Each time you start the cfshell client, it starts a new session. This allows us to do thins like:
To use CFShell you need of course to have Python installed on your computer. The client was built using python 2.6. Also you need to be running the CF server locally. I developed this on Railo 3, but I don't see any reason why it shouldn't work with any of the other engines.
By default, the cfshell client will try to connect to http://localhost/cfshell/cfshell.cfm but you can override this by passing an argument to the cfshell.py script. The script will always connect to a template named cfshell.cfm, however you can place this template on any application that you wish to interact with.
For example if you want to interact with an application in http://localhost:8080/someapp/ you need to copy cfshell.cfm to somapp/ and then do:
Also, you can use any alias, subdomain or port as long as it resolves to the localhost (127.0.0.1). This restriction is enforced on cfshell.cfm, and you can take it out at YOUR OWN RISK if you want to use cfshell on a different server.
Once the prompt appears, you can type .help for a list of commands. Here are the available commands that you can use:
.help : displays the list of available commands
.cfscript < staments > : executes the rest of the line as cfscript code
.get < template_path > : does a GET request to the given page (output supressed)
.sget < template_path > : same as .get without supressing output
.post < template_path > < arguments > : does a POST request to the given template (output supressed)
.spost < template_path > < arguments > : same as .post without supressing output
.call < template_path > : does a cfcinclude of the given template
.exit : exits cfshell
Any other string that you sent will be evaluated as a CFML statement, and any output generated will be displayed on the next line.
Additionally cfshell client lets you do POST and GET requests to any page within the directory that you connected. Use the .get and .post commands for this.
For a GET request you only need to pass the page that you want to call, for example:
This will send a GET http request to http://localhost/cfshell/index.cfm?a=1&b=2 (assuming that you connected to localhost/cfshell)
When doing a POST request you will most likely want to pass data on the body of the request. The format for doing this is like this:
Both .post and .get will only show you the status code of the request. If you want to actually see the HTML that is returned, use .spost and .sget
Here is the output of a cfshell session:
You can download CFShell from RIAForge here