1# Commander.js
  2
  3  The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/visionmedia/commander).
  4
  5 [![Build Status](https://secure.travis-ci.org/visionmedia/commander.js.png)](http://travis-ci.org/visionmedia/commander.js)
  6
  7## Installation
  8
  9    $ npm install commander
 10
 11## Option parsing
 12
 13 Options with commander are defined with the `.option()` method, also serving as documentation for the options. The example below parses args and options from `process.argv`, leaving remaining args as the `program.args` array which were not consumed by options.
 14
 15```js
 16#!/usr/bin/env node
 17
 18/**
 19 * Module dependencies.
 20 */
 21
 22var program = require('commander');
 23
 24program
 25  .version('0.0.1')
 26  .option('-p, --peppers', 'Add peppers')
 27  .option('-P, --pineapple', 'Add pineapple')
 28  .option('-b, --bbq', 'Add bbq sauce')
 29  .option('-c, --cheese [type]', 'Add the specified type of cheese [marble]', 'marble')
 30  .parse(process.argv);
 31
 32console.log('you ordered a pizza with:');
 33if (program.peppers) console.log('  - peppers');
 34if (program.pineapple) console.log('  - pineappe');
 35if (program.bbq) console.log('  - bbq');
 36console.log('  - %s cheese', program.cheese);
 37```
 38
 39 Short flags may be passed as a single arg, for example `-abc` is equivalent to `-a -b -c`. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc.
 40
 41## Automated --help
 42
 43 The help information is auto-generated based on the information commander already knows about your program, so the following `--help` info is for free:
 44
 45```  
 46 $ ./examples/pizza --help
 47
 48   Usage: pizza [options]
 49
 50   Options:
 51
 52     -V, --version        output the version number
 53     -p, --peppers        Add peppers
 54     -P, --pineapple      Add pineappe
 55     -b, --bbq            Add bbq sauce
 56     -c, --cheese <type>  Add the specified type of cheese [marble]
 57     -h, --help           output usage information
 58
 59```
 60
 61## Coercion
 62
 63```js
 64function range(val) {
 65  return val.split('..').map(Number);
 66}
 67
 68function list(val) {
 69  return val.split(',');
 70}
 71
 72program
 73  .version('0.0.1')
 74  .usage('[options] <file ...>')
 75  .option('-i, --integer <n>', 'An integer argument', parseInt)
 76  .option('-f, --float <n>', 'A float argument', parseFloat)
 77  .option('-r, --range <a>..<b>', 'A range', range)
 78  .option('-l, --list <items>', 'A list', list)
 79  .option('-o, --optional [value]', 'An optional value')
 80  .parse(process.argv);
 81
 82console.log(' int: %j', program.integer);
 83console.log(' float: %j', program.float);
 84console.log(' optional: %j', program.optional);
 85program.range = program.range || [];
 86console.log(' range: %j..%j', program.range[0], program.range[1]);
 87console.log(' list: %j', program.list);
 88console.log(' args: %j', program.args);
 89```
 90
 91## Custom help
 92
 93 You can display arbitrary `-h, --help` information
 94 by listening for "--help". Commander will automatically
 95 exit once you are done so that the remainder of your program
 96 does not execute causing undesired behaviours, for example
 97 in the following executable "stuff" will not output when
 98 `--help` is used.
 99
100```js
101#!/usr/bin/env node
102
103/**
104 * Module dependencies.
105 */
106
107var program = require('../');
108
109function list(val) {
110  return val.split(',').map(Number);
111}
112
113program
114  .version('0.0.1')
115  .option('-f, --foo', 'enable some foo')
116  .option('-b, --bar', 'enable some bar')
117  .option('-B, --baz', 'enable some baz');
118
119// must be before .parse() since
120// node's emit() is immediate
121
122program.on('--help', function(){
123  console.log('  Examples:');
124  console.log('');
125  console.log('    $ custom-help --help');
126  console.log('    $ custom-help -h');
127  console.log('');
128});
129
130program.parse(process.argv);
131
132console.log('stuff');
133```
134
135yielding the following help output:
136
137```
138
139Usage: custom-help [options]
140
141Options:
142
143  -h, --help     output usage information
144  -V, --version  output the version number
145  -f, --foo      enable some foo
146  -b, --bar      enable some bar
147  -B, --baz      enable some baz
148
149Examples:
150
151  $ custom-help --help
152  $ custom-help -h
153
154```
155
156## .prompt(msg, fn)
157
158 Single-line prompt:
159
160```js
161program.prompt('name: ', function(name){
162  console.log('hi %s', name);
163});
164```
165
166 Multi-line prompt:
167
168```js
169program.prompt('description:', function(name){
170  console.log('hi %s', name);
171});
172```
173
174 Coercion:
175
176```js
177program.prompt('Age: ', Number, function(age){
178  console.log('age: %j', age);
179});
180```
181
182```js
183program.prompt('Birthdate: ', Date, function(date){
184  console.log('date: %s', date);
185});
186```
187
188## .password(msg[, mask], fn)
189
190Prompt for password without echoing:
191
192```js
193program.password('Password: ', function(pass){
194  console.log('got "%s"', pass);
195  process.stdin.destroy();
196});
197```
198
199Prompt for password with mask char "*":
200
201```js
202program.password('Password: ', '*', function(pass){
203  console.log('got "%s"', pass);
204  process.stdin.destroy();
205});
206```
207
208## .confirm(msg, fn)
209
210 Confirm with the given `msg`:
211
212```js
213program.confirm('continue? ', function(ok){
214  console.log(' got %j', ok);
215});
216```
217
218## .choose(list, fn)
219
220 Let the user choose from a `list`:
221
222```js
223var list = ['tobi', 'loki', 'jane', 'manny', 'luna'];
224
225console.log('Choose the coolest pet:');
226program.choose(list, function(i){
227  console.log('you chose %d "%s"', i, list[i]);
228});
229```
230
231## Links
232
233 - [API documentation](http://visionmedia.github.com/commander.js/)
234 - [ascii tables](https://github.com/LearnBoost/cli-table)
235 - [progress bars](https://github.com/visionmedia/node-progress)
236 - [more progress bars](https://github.com/substack/node-multimeter)
237 - [examples](https://github.com/visionmedia/commander.js/tree/master/examples)
238
239## License 
240
241(The MIT License)
242
243Copyright (c) 2011 TJ Holowaychuk &lt;tj@vision-media.ca&gt;
244
245Permission is hereby granted, free of charge, to any person obtaining
246a copy of this software and associated documentation files (the
247'Software'), to deal in the Software without restriction, including
248without limitation the rights to use, copy, modify, merge, publish,
249distribute, sublicense, and/or sell copies of the Software, and to
250permit persons to whom the Software is furnished to do so, subject to
251the following conditions:
252
253The above copyright notice and this permission notice shall be
254included in all copies or substantial portions of the Software.
255
256THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
257EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
258MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
259IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
260CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
261TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
262SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.