Shell brings a Connect inspired API, Express inspired routing, and other similar functionality to console based applications.
var shell = require('shell');
// Initialization
var app = new shell();
// Middleware registration
app.configure(function() {
app.use(shell.history({
shell: app
}));
app.use(shell.completer({
shell: app
}));
app.use(shell.router({
shell: app
}));
app.use(shell.redis({
shell: app,
config: 'redis.conf',
pidfile: 'redis.pid'
}));
app.use(shell.help({
shell: app,
introduction: true
}));
});
// Command registration
app.cmd('redis keys :pattern', 'Find keys', function(req, res, next){
if(!app.client){
app.client = require('redis').createClient();
}
app.client.keys(req.params.pattern, function(err, keys){
if(err){ return res.styles.red(err.message), next(); }
res.cyan(keys.join('\n')||'no keys');
res.prompt();
});
});
// Event notification
app.on('redis quit', function(){
if(app.client){
app.client.quit();
}
});
npm install shell
var app = new shell();
app.configure(function() {
app.use(shell.history({shell: app}));
app.use(shell.completer({shell: app}));
app.use(shell.help({shell: app, introduction: true}));
});
app.configure('prod', function() {
app.set('title', 'Production Mode');
});
The constructor shell
takes an optional object. Options are:
chdir
, Changes the current working directory of the process, a string of the directory, boolean true will default to theworkspace
(in which caseworkspace
must be provided or discoverable)prompt
, Character for command prompt, Defaults to ">>"stdin
, Source to read fromstdout
, Destination to write toenv
, Running environment, Defaults to theenv
setting (orNODE_ENV
if defined, eg:production
,develepment
).isShell
, Detect whether the command is runned inside a shell are as a single command.noPrompt
, Do not prompt the user for a command, usefull to plug your own starting mechanisme (eg: starting with a question).workspace
, Project root directory or null if none was found. The discovery strategy start from the current working directory and traverse each parent dir looking for anode_module
directory or apackage.json
file.
Shell settings may be set by calling app.set('key', value)
. They can be retrieved by calling the same function without a second argument.
var app = new shell({
chdir: true
});
app.set('env', 'prod');
app.configure('prod', function() {
console.log(app.set('env'));
});
As with Express, app.configure
allows the customization of plugins for all or specific environments, while app.use
registers plugins.
If app.configure
is called without specifying the environment as the first argument, the provided callback is always called. Otherwise, the environment must match the env
setting or the global variable NODE_ENV
.
The following events may be emitted:
"command"
, listen to all executed commands, provide the command name as first argument#{command}
, listen to a particular event"quit"
, called when the application is about to quit"exit"
, called when the process exit
The functionality provided by the 'routes' module is very similar to that of express. Options passed during creation are:
shell
, (required) A reference to your shell application.sensitive
, (optional) Defaults tofalse
, set totrue
if the match should be case sensitive.
New routes are defined with the cmd
method. A route is made of pattern against which the user command is matched, an optional description and one or more route specific middlewares to handle the command. The pattern is either a string or a regular expression. Middlewares receive three parameters: a request object, a response object, and a function. Command parameters are substituted and made available in the params
object of the request parameter.
Parameters can have restrictions in parenthesis immediately following the
keyword, as in express: :id([0-9]+)
. See the list
route in the example:
var app = new shell();
app.configure(function(){
app.use(shell.router({
shell: app
}));
});
// Route middleware
var auth = function(req, res, next){
if(req.params.uid == process.getuid()){
next()
}else{
throw new Error('Not me');
}
}
// Global parameter substitution
app.param('uid', function(req, res, next){
exec('whoami', function(err, stdout, sdterr){
req.params.username = stdout;
next();
});
});
// Simple command
app.cmd('help', function(req, res){
res.cyan('Run this command `./ami user ' + process.getuid() + '`');
res.prompt()
});
// Command with parameter and two route middlewares
app.cmd('user :uid', auth, function(req, res){
res.cyan('Yes, you are ' + req.params.username);
});
app.cmd('list :id([0-9]+)', function(req, res) {
res.cyan('List: foo bar');
res.prompt();
});
The request object contains the following properties:
shell
, (required) A reference to your shell application.command
, Command entered by the userparams
, Parameters object extracted from the command, defined by theshell.router
middleware
The response object inherits from styles containing methods for printing, coloring and bolding:
Colors:
black
white
yellow
blue
cyan
green
magenta
red
bgcolor
color
nocolor
Style:
regular
weight
bold
Display:
prompt
, Exits the current command and return user to the prompt.ln
print
println
constructor
reset
pad
raw
Persistent command history over multiple sessions. Options passed during creation are:
shell
, (required) A reference to your shell application.name
, Identify your project history file, default to the hash of the exectuted filedir
, Location of the history files, defaults to"#{process.env['HOME']}/.node_shell"
Provides tab completion. Options passed during creation are:
shell
, (required) A reference to your shell application.
Display help when the user types "help" or runs commands without arguments. Command help is only displayed if a description was provided during the command registration.
Additionnaly, a new shell.help()
function is made available. Options passed during creation are:
shell
, (required) A reference to your shell application.introduction
, Print message 'Type "help" or press enter for a list of commands' if booleantrue
, or a custom message if astring
Register two commands, http start
and http stop
. The start command will search for "./server.js" and "./app.js" (and additionnaly their CoffeeScript alternatives) to run by node
.The following properties may be provided as settings:
config
, Path to the configuration file. Required to launch redis.detach
, Wether the HTTP process should be attached to the current process. If not defined, default totrue
in shell mode andfalse
in command mode.pidfile
, Path to the file storing the detached process id. Defaults to"/.node_shell/#{md5}.pid"
stdout
, Writable stream or file path to redirect the server stdout.stderr
, Writable stream or file path to redirect the server stderr.workspace
, Project directory used to resolve relative paths and search for "server" and "app" scripts.
Example:
var app = new shell();
app.configure(function() {
app.use(shell.router({
shell: app
}));
app.use(shell.http({
shell: app
}));
app.use(shell.help({
shell: app,
introduction: true
}));
});
Register two commands, redis start
and redis stop
. The following properties may be provided as settings:
config
Path to the configuration file. Required to launch redis.detach
Wether the Redis process should be attached to the current process. If not defined, default totrue
in shell mode andfalse
in command mode.pidfile
Path to the file storing the detached process id. Defaults to"/.node_shell/#{md5}.pid"
stdout
Writable stream or file path to redirect cloud9 stdout.stderr
Writable stream or file path to redirect cloud9 stderr.
Example:
var app = new shell();
app.configure(function() {
app.use(shell.router({
shell: app
}));
app.use(shell.redis({
shell: app,
config: __dirname+'/redis.conf')
}));
app.use(shell.help({
shell: app,
introduction: true
}));
});
Register two commands, cloud9 start
and cloud9 stop
. Unless provided, the Cloud9 workspace will be automatically discovered if your project root directory contains a "package.json" file or a "node_module" directory.
Options:
config
Load the configuration from a config file. Overrides command-line options. Defaults tonull
.group
Run child processes with a specific group.user
Run child processes as a specific user.action
Define an action to execute after the Cloud9 server is started. Defaults tonull
.ip
IP address where Cloud9 will serve from. Defaults to"127.0.0.1"
.port
Port number where Cloud9 will serve from. Defaults to3000
.workspace
Path to the workspace that will be loaded in Cloud9, Defaults toShell.set('workspace')
.detach
Wether the Cloud9 process should be attached to the current process. If not defined, default totrue
in shell mode andfalse
in command mode.pidfile
Path to the file storing the detached process id. Defaults to"/.node_shell/#{md5}.pid"
stdout
Writable stream or file path to redirect cloud9 stdout.stderr
Writable stream or file path to redirect cloud9 stderr.
Example:
var app = new shell();
app.configure(function() {
app.use(shell.router({
shell: app
}));
app.use(shell.cloud9({
shell: app,
ip: '0.0.0.0'
}));
app.use(shell.help({
shell: app,
introduction: true
}));
});
Important: If you encounter issue while installing cloud9, it might be because the npm module expect an older version of Node.
Here's the procedure to use the newer version on the devel branch:
git clone https://github.com/ajaxorg/cloud9.git
cd cloud9
git checkout -b devel origin/devel
git submodule update --init --recursive
npm link
Start Coffee in --watch
mode, so scripts are instantly compiled into Javascript.
Options:
src
Directory where ".coffee" are stored. Each ".coffee" script will be compiled into a .js JavaScript file of the same name.output
Directory where compiled JavaScript files are written. Used in conjunction with "compile".lint
If thejsl
(JavaScript Lint) command is installed, use it to check the compilation of a CoffeeScript file.require
Load a library before compiling or executing your script. Can be used to hook in to the compiler (to add Growl notifications, for example).detach
Wether the Coffee process should be attached to the current process. If not defined, default totrue
in shell mode andfalse
in command mode.pidfile
Path to the file storing the detached process id. Defaults to"/.node_shell/#{md5}.pid"
stdout
Writable stream or file path to redirect cloud9 stdout.stderr
Writable stream or file path to redirect cloud9 stderr.workspace
Project directory used to resolve relative paths.
Example:
var app = new shell();
app.configure(function() {
app.use(shell.router({
shell: app
}));
app.use(shell.coffee({
shell: app
}));
app.use(shell.help({
shell: app,
introduction: true
}));
});
The prompt
route is a convenient function to stop command once a few routes are executed. You can simply pass the the shell.routes.prompt
function or call it with a message argument.
var app = new shell();
app.configure(function() {
app.use(shell.router({
shell: app
}));
});
app.cmd('install', [
my_app.routes.download,
my_app.routes.configure,
shell.routes.prompt('Installation is finished')
]);
The confirm
route ask the user if he want to continue the process. If the answer is true
, the following routes are executed. Otherwise, the process is stoped.
var app = new shell();
app.configure(function() {
app.use(shell.router({
shell: app
}));
});
app.cmd('install', [
shell.routes.confirm('Do you confirm?'),
my_app.routes.download,
my_app.routes.configure
]);
The timeout
route will wait for the provided period (in millisenconds) before executing the following route.
var app = new shell();
app.configure(function() {
app.use(shell.router({
shell: app
}));
});
app.cmd('restart', [
my_app.routes.stop,
shell.routes.timeout(1000),
my_app.routes.start
]);