Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100755 271 lines (166 sloc) 14.106 kb
bc08b07 @Hypercubed Updated readme
authored
1 autocmdr [![Build Status](https://secure.travis-ci.org/Hypercubed/autocmdr.png?branch=master)](https://travis-ci.org/Hypercubed/autocmdr) [![NPM version](https://badge.fury.io/js/autocmdr.png)](http://badge.fury.io/js/autocmdr) [![Code Climate](https://codeclimate.com/github/Hypercubed/autocmdr.png)](https://codeclimate.com/github/Hypercubed/autocmdr)
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
2 =============
3
bc08b07 @Hypercubed Updated readme
authored
4 [![NPM](https://nodei.co/npm/autocmdr.png?downloads=true)](https://nodei.co/npm/autocmdr/)
5
37efade @Hypercubed Updated readme
authored
6 autocmdr is a both a command line interface for running tasks and a set of components for building CLIs. autocmdr is designed to work with [generator-commander](https://github.com/Hypercubed/generator-commander) to enable easily building of commander.js command line apps.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
7
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
8 autocmdr itself was partially built using autocmdr/[generator-commander](https://github.com/Hypercubed/generator-commander). Please also see the obligatory todo app here [todo-md](https://github.com/Hypercubed/todo-md) (Works with GFM task lists!!).
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
9
10 Warning... The usage is changing rapidly. I'm working towards a [0.1.0](https://github.com/Hypercubed/autocmdr/issues?milestone=1) release soon. Feedback is welcome.
11
12 # Introduction
13
37efade @Hypercubed Updated readme
authored
14 The diverse ecosystem of modules available for node.js through npm make it a great tool for the rapid development of a variety of tools including useful command line interfaces. [Commander.js](https://github.com/visionmedia/commander.js) from [visionmedia](https://github.com/visionmedia) is an excellent node.js command line parser that, using a natural, clean and highly readable syntax, allows for easy development of versatile self-documenting command line interfaces (CLIs). However, a command line parser is just the beginning. Many CLIs will inevitably need to include additional components such as debug logging, configuration management, and other CLI type actions. autocmdr is a command line tool that implements these modules, so you don't have too. In fact using the autocmdr executable all you need to do is add commands to your local directory and autocmdr will load them automatically along with a reasonable set of additional support components. Using autocmdr along with [yo](https://github.com/yeoman/yo) and [generator-commander](https://github.com/Hypercubed/generator-commander) provides tools for easily building command components and full CLI applications. This includes converting a detached set of command components into a independent CLI application that uses autocmdr (along with all it's support modules) as a library.
9bc28f8 @Hypercubed Working on readme
authored
15
16 ## Philosophy ad Workflow
17
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
18 **Building excellent command tools using excellent tools. Using the right tool for the right task**
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
19
37efade @Hypercubed Updated readme
authored
20 [commander.js](https://github.com/visionmedia/commander.js) is an node.js command line parser from [visionmedia](https://github.com/visionmedia).
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
21
37efade @Hypercubed Updated readme
authored
22 autocmdr is a set of components that add interfaces and support to commander.js based applications built by Hypercubed (me).
9bc28f8 @Hypercubed Working on readme
authored
23
37efade @Hypercubed Updated readme
authored
24 [yo](https://github.com/yeoman/yo) is a scaffolding tool built by Google.
9bc28f8 @Hypercubed Working on readme
authored
25
37efade @Hypercubed Updated readme
authored
26 [generator-commander](https://github.com/Hypercubed/generator-commander) is a commander.js application generator for Yo also built by Hypercubed.
9bc28f8 @Hypercubed Working on readme
authored
27
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
28 Yo, together with the commander generator, makes it easy to scaffold complete command line tools that uses commander.js command line parser and autocmdr components to enable great command line interfaces.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
29
30 # Usage
31
32 ## Summary
33
9bc28f8 @Hypercubed Working on readme
authored
34 Essentially autocmdr, like most node.js modules, works in two modes; executable (command line) mode and library (require) mode. In executable mode autocmdr will load any commands located in the current working directory's (cwd's) `cmds/` folder. By convention each file in the `cmds/` directory corresponds to one commander.js command, although this is not necessary. In this mode it is not necessary to install autocmdr in the current working directory, you are using the global autocmdr executable with the local `cmds/` commands.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
35
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
36 In library mode a commander.js based CLI executable has access to autocmdr components extending its interface.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
37
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
38 ## Using autocmdr as a task runner
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
39
9bc28f8 @Hypercubed Working on readme
authored
40 Install autocmdr globally
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
41
42 npm install -g Hypercubed/autocmdr
43
9bc28f8 @Hypercubed Working on readme
authored
44 When running in executable mode all commands located in the `cmds/` folder of the current working directory are automatically loaded. These commands can be be run by invoking `autocmdr commandname`. `autocmdr --help` will list help on these local commands. By using the globally installed `autocmdr` executable the rest of your project remains untouched so you can add commands to augment existing projects.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
45
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
46 ## Using generator-commander to add command components
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
47
9bc28f8 @Hypercubed Working on readme
authored
48 Install yo and generator-commander
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
49
9bc28f8 @Hypercubed Working on readme
authored
50 npm install -g yo generator-commander
51
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
52 using yo and generator-commander you can add commands to the current working directory's `cmds/` folder. Referring to the example below `yo commander:command mycmd` will add the `mycmd` command to the cwd's `cmd/` directory. The `autocmdr mycmd` call executes the `mycmd` command. If you change to another directory these commands are no longer available.
9bc28f8 @Hypercubed Working on readme
authored
53
54 $ mkdir example && cd example
55 $ autocmdr --help
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
56
57 Usage: autocmdr [options] [command]
58
59 Commands:
60
61 config [key] [value] Get and set options
62 completion Print command completion script
63
64 Options:
65
66 -h, --help output usage information
67 -d, --debug enable debugger
68 -V, --version output the version number
69
70 Bug reports, suggestions, updates:
71 https://github.com/Hypercubed/autocmdr/issues
72
9bc28f8 @Hypercubed Working on readme
authored
73 $ yo commander:command mycmd
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
74
75 [?] Command name: mycmd
76 [?] version: 0.0.0
77 [?] description: A commander command
78 create cmds/mycmd.js
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
79
dd74ff4 @Hypercubed Readme and tests
authored
80 I'm all done. Add `require('../cmds/mycmd.js')(program);` to your app before program.parse.
81
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
82 $ autocmdr --help
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
83
84 Usage: autocmdr [options] [command]
85
86 Commands:
87
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
88 mycmd [options] A commander command
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
89 config [key] [value] Get and set options
90 completion Print command completion script
91
92 Options:
93
94 -h, --help output usage information
95 -d, --debug enable debugger
96 -V, --version output the version number
97
98 Bug reports, suggestions, updates:
99 https://github.com/Hypercubed/autocmdr/issues
100
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
101 $ autocmdr mycmd
102 $ cd ..
103 $ autocmdr mycmd
104 $ error: 'mycmd' is not a known command. See 'autocmdr --help'.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
105
9bc28f8 @Hypercubed Working on readme
authored
106 ## Using generator-commander
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
107
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
108 If a set of commands in a folder are useful globally you can convert a set of tasks to an self contained commander.js command line application. Notice after running `yo commander` the previously created command `mycmd` is available within the newly created `example` application.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
109
110 1. Create an independent commander.js based app with autocmdr default plug-ins.
111
37efade @Hypercubed Updated readme
authored
112 $ cd example
113 $ yo commander
114
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
115 [?] Name (must be only letters, spaces, or dashes) example
116 [?] Version: 0.0.0
117 [?] Description: A commander CLI app
118 [?] GitHub username:
119 [?] license: MIT
dd74ff4 @Hypercubed Readme and tests
authored
120 >[x] Logger (adds a Winston logger)
121 [x] Commander loader (automatically loads commands from cmds/ directory)
122 [x] Autocompletion (adds command line autocompletion)
123 [x] Package (load reasonable defaults from your application's package.json)
124 [x] Config (adds a config command)
125 [x] Help (adds a `did you mean` messege when an unknown command is given)
126
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
127 create package.json
128 create bin/example
129 create Readme.md
130 create test/example.js
131 create .editorconfig
132 create .jshintrc
133 create .gitignore
134 create .travis.yml
37efade @Hypercubed Updated readme
authored
135
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
136 I'm all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself.
37efade @Hypercubed Updated readme
authored
137
138 $ ./bin/example --help
139
140 Usage: example [options] [command]
141
142 Commands:
143 mycmd [options] A commander command
144 config [key] [value] Get and set options
145 completion Print command completion script
146
147 Options:
148 -h, --help output usage information
149 -d, --debug enable debugger
150 -V, --version output the version number
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
151
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
152 2. (Optional) Make it global
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
153
37efade @Hypercubed Updated readme
authored
154 $ npm link
155 $ cd ..
156 $ example --help
157
158 Usage: example [options] [command]
159
160 Commands:
161 mycmd [options] A commander command
162 config [key] [value] Get and set options
163 completion Print command completion script
164
165 Options:
166 -h, --help output usage information
167 -d, --debug enable debugger
168 -V, --version output the version number
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
169
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
170 The new executable you just created, when you include the autocmdr components, will have access to the autocmdr features as well as the commands in the `cmds/` folder. Edit `bin/example` to change what components are loaded.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
171
172 # Commander.js components
173
9bc28f8 @Hypercubed Working on readme
authored
174 autocmdr components are node.js modules that export a single initialization function. This function is called with a commander.js program and an optional options object. Components have a simple syntax that doesn't deviate far from the syntax established by commander.js itself. See autocmdr's [example commands](https://github.com/Hypercubed/autocmdr/tree/master/cmds) and [lib](https://github.com/Hypercubed/autocmdr/tree/master/lib) for examples.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
175
9bc28f8 @Hypercubed Working on readme
authored
176 ## Commands
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
177
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
178 The most basic form of a command component is shown below. Within the exported function a single command is added to the commander.js `program` as you would in any other commander.js program (see [commander.js api documentation](http://visionmedia.github.io/commander.js/)).
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
179
9bc28f8 @Hypercubed Working on readme
authored
180 module.exports = function(program) {
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
181
182 program
183 .command('name')
184 .version('version')
185 .description('description')
dd74ff4 @Hypercubed Readme and tests
authored
186 .action(function(args){
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
187 // Do something
188 });
189
190 };
191
9bc28f8 @Hypercubed Working on readme
authored
192 ## Components
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
193
00bc5ac @Hypercubed Removed template, dependencies, updated readme
authored
194 autocmdr component modules have the same structure as command modules. The only difference is that they are not designed to be automatically loaded. Plugins are loaded using node's require function again exporting a single initialization function; this time accepting an optional options object as the second parameter. Below are the built-in autocmdr plug-ins.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
195
9bc28f8 @Hypercubed Working on readme
authored
196 module.exports = function(program, options) {
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
197
198 // Do plug-in stuff here
199
200 };
201
37efade @Hypercubed Updated readme
authored
202 # autocmdr supplied components
203
204 ## loader
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
205
9bc28f8 @Hypercubed Working on readme
authored
206 This component is what loads the `cmds/` modules.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
207
208 Adding `require('autocmdr/lib/loader.js')(program)` will load all modules in the `cmds` folder just above the executable. This path can be overridden by setting the path option; for example `require('autocmdr/lib/loader.js')(program, { path: path.join(process.cwd(), 'cmds/') )` will load modules from the cwd's `/cmds` folder.
209
37efade @Hypercubed Updated readme
authored
210 ## logger
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
211
9bc28f8 @Hypercubed Working on readme
authored
212 The logger component uses [Winston](https://github.com/flatiron/winston) for logging.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
213
214 Adding `require('autocmdr/lib/logger')(program)` will add `program.log` to your application. The plug-in will enable output to the terminal depending on the log level. The plug-in will also add the `-d` option to your application to enable debug logging. Then logging can be done like this:
215
216 program.log('info', 'Hello!');
217 program.info('Hello again');
218 program.debug('Can you hear me now?');
219
220 While this component is optional other components expect to find and instant of Winston at `program.log`.
221
37efade @Hypercubed Updated readme
authored
222 ## config
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
223
9bc28f8 @Hypercubed Working on readme
authored
224 This component will load [nconf](https://github.com/flatiron/nconf) for handling of configuration. It will add program.config as an instance of nconf.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
225
226 Adding `require('autocmdr/lib/config')(program)` will enable this.
227
228 While this component is optional other components expect to find and instant of nconf at `program.config`.
229
37efade @Hypercubed Updated readme
authored
230 ## help
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
231
37efade @Hypercubed Updated readme
authored
232 This component will use [didyoumean](https://github.com/dcporter/didyoumean.js) to add a "Did you mean:" message to your application when an unknown command is given.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
233
234 Adding `require('autocmdr/lib/help')(program)` will enable this.
235
37efade @Hypercubed Updated readme
authored
236 ## package
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
237
37efade @Hypercubed Updated readme
authored
238 This component will use the will load reasonable defaults (such as description and bug reporting URL) from your application's package.json.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
239
240 Adding `require('autocmdr/lib/package')(program)` will load the package.json file located one directory above the executable. You can override this path using the options object.
241
37efade @Hypercubed Updated readme
authored
242 ## completion
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
243
37efade @Hypercubed Updated readme
authored
244 This component will use [node-tabtab](https://github.com/mklabs/node-tabtab) to add auto-completion support to your application.
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
245
246 Adding `require('autocmdr/lib/completion')(program)` just before `program.parse(argv);` will will enable auto-completion support. You will then need to do one of the following to enable auto-completion in your shell.
247
248 * Add completion helper to ~/.bashrc (or ~/.zshrc) `pkgname completion >> ~/.bashrc`
249 * Add completion to current shell `. <(pkgname completion)`
250
251 # Share
252
253 The modular nature of autocmdr command files makes it easy to share using gist, git or similar tool. Simply copying files into `cmds/` folder can work in many cases.
254
255 # Todo
256
257 See [todo.md](https://github.com/Hypercubed/autocmdr/blob/master/todo.md) \( managed using [todo-md](https://github.com/Hypercubed/todo-md) and it's self an [autocmdr](https://github.com/Hypercubed/autocmdr/tree/master/lib) app\)
258
259 # License
260
9bc28f8 @Hypercubed Working on readme
authored
261 [MIT License](http://en.wikipedia.org/wiki/MIT_License)
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
262
6027ef5 @Hypercubed Added travis.yml and nofified readme
authored
263 Copyright (c) 2013 J. Harshbarger
264 [![Gittip donate button](http://badgr.co/gittip/hypercubed.png)](https://www.gittip.com/hypercubed/ "Donate weekly to this project using Gittip")
265 [![Paypal donate button](http://badgr.co/paypal/donate.png?bg=%23feb13d)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=X7KYR6T9U2NHC "One time donation to this project using Paypal")
266
9dd5c49 @Hypercubed Improved tests. Add and init now emit exit codes. Improved readme.md.
authored
267 # Acknowledgments
268
269 autocmdr itself was (partially) built using [autocmdr](https://github.com/Hypercubed/autocmdr).
270
fb99e8c @Hypercubed Merge master and travis branch in readme
authored
271 autocmdr is build on top of [commander.js](https://github.com/visionmedia/commander.js) and inspired by other task managers \( [grunt](https://github.com/gruntjs/grunt), [automaton](https://github.com/IndigoUnited/automaton) \) and command line tools \( [docpad](https://github.com/bevry/docpad), [git](https://github.com/git/git) \).
Something went wrong with that request. Please try again.