1 | [![Build Status](https://travis-ci.org/philcockfield/command-interface.svg?branch=master)](https://travis-ci.org/philcockfield/command-interface)
|
2 | ![Title](https://cloud.githubusercontent.com/assets/185555/25560798/7c630472-2db1-11e7-861f-8e3ceaca216b.png)
|
3 |
|
4 | Build powerful command-line interfaces from simple ES6 modules.
|
5 |
|
6 |
|
7 | ## Usage
|
8 | Each command is defined within an ES module like so:
|
9 |
|
10 | ```js
|
11 | // commands/foo.cmd.js
|
12 |
|
13 | export const name = 'foo';
|
14 | export const description = 'A thing that does something.';
|
15 | export const alias = 'f'; // String or Array.
|
16 | export const group = 'Utilities';
|
17 |
|
18 | export const args = {
|
19 | 'param1': 'the first parameter',
|
20 | 'param2': 'the second param',
|
21 | '--foo': 'a boolean flag',
|
22 | };
|
23 |
|
24 | export const validate = (args) => args;
|
25 |
|
26 | export default (args) {
|
27 | // Run the command.
|
28 | };
|
29 | ```
|
30 |
|
31 | All exports are optional. If a `name` is omitted the name of the module is assumed. The only thing you really need is the `default export` function to invoke when the command is run.
|
32 |
|
33 | If you don't wish to export the command as a default export, your can export a function named `cmd`, eg:
|
34 |
|
35 | ```js
|
36 | export async function cmd(args) {
|
37 | // Run the command.
|
38 | }
|
39 | ```
|
40 |
|
41 |
|
42 | To initialize the CLI, from the entry point of your module pass a [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) representing your JS modules that are commands. Typically these have a `.cmd.js` suffix:
|
43 |
|
44 | ```js
|
45 | import command from 'command-interface';
|
46 | command('./**/*.cmd.js');
|
47 | ```
|
48 |
|
49 | This will load all modules with the `.cmd.js` suffix anywhere within the project and produce the following index list when run with no command argument:
|
50 |
|
51 | ![Index](https://cloud.githubusercontent.com/assets/185555/16539433/6c7ec6d4-4097-11e6-9cf2-55ff675839f8.png)
|
52 |
|
53 |
|
54 |
|
55 |
|
56 |
|
57 | #### Command Help
|
58 | To get details on a specific command:
|
59 |
|
60 | node . foo -h
|
61 |
|
62 | ![Command Help](https://cloud.githubusercontent.com/assets/185555/16544978/6d9f6b2c-416e-11e6-8574-0ec42bc04e64.png)
|
63 |
|
64 |
|
65 | #### Run a Command
|
66 |
|
67 | node . foo param1 flag=123 -f
|
68 |
|
69 | The parameter and option arguments are passed to the command function as the `args` parameter.
|
70 |
|
71 | ```js
|
72 | {
|
73 | args: ['param1'],
|
74 | options: { flag: 123, f: true },
|
75 | }
|
76 | ```
|
77 |
|
78 | See [minimist](https://github.com/substack/minimist) for more.
|
79 |
|
80 | ## Example
|
81 |
|
82 | cd lib/examples
|
83 | node .
|
84 |
|
85 |
|
86 |
|
87 | ## Tests
|
88 |
|
89 | npm test
|
90 |
|
91 | ## Usages
|
92 |
|
93 | - [msync](https://github.com/philcockfield/msync) - A powerful toolkit for building and syncing multiple node-modules in a flexibly defined workspace.
|
94 |
|
95 | - [new-file](https://github.com/philcockfield/new-file) - Simple file templates.
|
96 |
|
97 |
|
98 | ## Next
|
99 | - Update checker
|