Readme.md
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(' - pineapple');
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 pineapple
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```js
189program.prompt('Email: ', /^.+@.+\..+$/, function(email){
190 console.log('email: %j', email);
191});
192```
193
194## .password(msg[, mask], fn)
195
196Prompt for password without echoing:
197
198```js
199program.password('Password: ', function(pass){
200 console.log('got "%s"', pass);
201 process.stdin.destroy();
202});
203```
204
205Prompt for password with mask char "*":
206
207```js
208program.password('Password: ', '*', function(pass){
209 console.log('got "%s"', pass);
210 process.stdin.destroy();
211});
212```
213
214## .confirm(msg, fn)
215
216 Confirm with the given `msg`:
217
218```js
219program.confirm('continue? ', function(ok){
220 console.log(' got %j', ok);
221});
222```
223
224## .choose(list, fn)
225
226 Let the user choose from a `list`:
227
228```js
229var list = ['tobi', 'loki', 'jane', 'manny', 'luna'];
230
231console.log('Choose the coolest pet:');
232program.choose(list, function(i){
233 console.log('you chose %d "%s"', i, list[i]);
234});
235```
236
237## .outputHelp()
238
239 Output help information without exiting.
240
241## .help()
242
243 Output help information and exit immediately.
244
245## Links
246
247 - [API documentation](http://visionmedia.github.com/commander.js/)
248 - [ascii tables](https://github.com/LearnBoost/cli-table)
249 - [progress bars](https://github.com/visionmedia/node-progress)
250 - [more progress bars](https://github.com/substack/node-multimeter)
251 - [examples](https://github.com/visionmedia/commander.js/tree/master/examples)
252
253## License
254
255(The MIT License)
256
257Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
258
259Permission is hereby granted, free of charge, to any person obtaining
260a copy of this software and associated documentation files (the
261'Software'), to deal in the Software without restriction, including
262without limitation the rights to use, copy, modify, merge, publish,
263distribute, sublicense, and/or sell copies of the Software, and to
264permit persons to whom the Software is furnished to do so, subject to
265the following conditions:
266
267The above copyright notice and this permission notice shall be
268included in all copies or substantial portions of the Software.
269
270THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
271EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
272MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
273IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
274CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
275TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
276SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
277