1 | # meow
|
2 |
|
3 | > CLI app helper
|
4 |
|
5 | ![](meow.gif)
|
6 |
|
7 | *I would recommend reading this [guide](https://clig.dev) on how to make user-friendly command-line tools.*
|
8 |
|
9 | ## Features
|
10 |
|
11 | - Parses arguments
|
12 | - Converts flags to [camelCase](https://github.com/sindresorhus/camelcase)
|
13 | - Negates flags when using the `--no-` prefix
|
14 | - Outputs version when `--version`
|
15 | - Outputs description and supplied help text when `--help`
|
16 | - Makes unhandled rejected promises [fail hard](https://github.com/sindresorhus/hard-rejection) instead of the default silent fail
|
17 | - Sets the process title to the binary name defined in package.json
|
18 |
|
19 | ## Install
|
20 |
|
21 | ```
|
22 | $ npm install meow
|
23 | ```
|
24 |
|
25 | ## Usage
|
26 |
|
27 | ```
|
28 | $ ./foo-app.js unicorns --rainbow
|
29 | ```
|
30 |
|
31 | ```js
|
32 | #!/usr/bin/env node
|
33 | import meow from 'meow';
|
34 | import foo from './lib/index.js';
|
35 |
|
36 | const cli = meow(`
|
37 | Usage
|
38 | $ foo <input>
|
39 |
|
40 | Options
|
41 | --rainbow, -r Include a rainbow
|
42 |
|
43 | Examples
|
44 | $ foo unicorns --rainbow
|
45 | 🌈 unicorns 🌈
|
46 | `, {
|
47 | importMeta: import.meta,
|
48 | flags: {
|
49 | rainbow: {
|
50 | type: 'boolean',
|
51 | alias: 'r'
|
52 | }
|
53 | }
|
54 | });
|
55 | /*
|
56 | {
|
57 | input: ['unicorns'],
|
58 | flags: {rainbow: true},
|
59 | ...
|
60 | }
|
61 | */
|
62 |
|
63 | foo(cli.input[0], cli.flags);
|
64 | ```
|
65 |
|
66 | ## API
|
67 |
|
68 | ### meow(helpText, options?)
|
69 | ### meow(options)
|
70 |
|
71 | Returns an `object` with:
|
72 |
|
73 | - `input` *(Array)* - Non-flag arguments
|
74 | - `flags` *(Object)* - Flags converted to camelCase excluding aliases
|
75 | - `unnormalizedFlags` *(Object)* - Flags converted to camelCase including aliases
|
76 | - `pkg` *(Object)* - The `package.json` object
|
77 | - `help` *(string)* - The help text used with `--help`
|
78 | - `showHelp([exitCode=2])` *(Function)* - Show the help text and exit with `exitCode`
|
79 | - `showVersion()` *(Function)* - Show the version text and exit
|
80 |
|
81 | #### helpText
|
82 |
|
83 | Type: `string`
|
84 |
|
85 | Shortcut for the `help` option.
|
86 |
|
87 | #### options
|
88 |
|
89 | Type: `object`
|
90 |
|
91 | ##### importMeta
|
92 |
|
93 | Type: `object`
|
94 |
|
95 | Pass in [`import.meta`](https://nodejs.org/dist/latest/docs/api/esm.html#esm_import_meta). This is used to find the correct package.json file.
|
96 |
|
97 | ##### flags
|
98 |
|
99 | Type: `object`
|
100 |
|
101 | Define argument flags.
|
102 |
|
103 | The key is the flag name in camel-case and the value is an object with any of:
|
104 |
|
105 | - `type`: Type of value. (Possible values: `string` `boolean` `number`)
|
106 | - `alias`: Usually used to define a short flag alias.
|
107 | - `default`: Default value when the flag is not specified.
|
108 | - `isRequired`: Determine if the flag is required. (Default: false)
|
109 | - If it's only known at runtime whether the flag is required or not, you can pass a `Function` instead of a `boolean`, which based on the given flags and other non-flag arguments, should decide if the flag is required. Two arguments are passed to the function:
|
110 | - The first argument is the **flags** object, which contains the flags converted to camel-case excluding aliases.
|
111 | - The second argument is the **input** string array, which contains the non-flag arguments.
|
112 | - The function should return a `boolean`, true if the flag is required, otherwise false.
|
113 | - `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
|
114 | - Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values are [currently *not* supported](https://github.com/sindresorhus/meow/issues/164).
|
115 |
|
116 | Note that flags are always defined using a camel-case key (`myKey`), but will match arguments in kebab-case (`--my-key`).
|
117 |
|
118 | Example:
|
119 |
|
120 | ```js
|
121 | flags: {
|
122 | unicorn: {
|
123 | type: 'string',
|
124 | alias: 'u',
|
125 | default: ['rainbow', 'cat'],
|
126 | isMultiple: true,
|
127 | isRequired: (flags, input) => {
|
128 | if (flags.otherFlag) {
|
129 | return true;
|
130 | }
|
131 |
|
132 | return false;
|
133 | }
|
134 | }
|
135 | }
|
136 | ```
|
137 |
|
138 | ##### description
|
139 |
|
140 | Type: `string | boolean`\
|
141 | Default: The package.json `"description"` property
|
142 |
|
143 | Description to show above the help text.
|
144 |
|
145 | Set it to `false` to disable it altogether.
|
146 |
|
147 | ##### help
|
148 |
|
149 | Type: `string | boolean`
|
150 |
|
151 | The help text you want shown.
|
152 |
|
153 | The input is reindented and starting/ending newlines are trimmed which means you can use a [template literal](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/template_strings) without having to care about using the correct amount of indent.
|
154 |
|
155 | The description will be shown above your help text automatically.
|
156 |
|
157 | ##### version
|
158 |
|
159 | Type: `string | boolean`\
|
160 | Default: The package.json `"version"` property
|
161 |
|
162 | Set a custom version output.
|
163 |
|
164 | ##### autoHelp
|
165 |
|
166 | Type: `boolean`\
|
167 | Default: `true`
|
168 |
|
169 | Automatically show the help text when the `--help` flag is present. Useful to set this value to `false` when a CLI manages child CLIs with their own help text.
|
170 |
|
171 | This option is only considered when there is only one argument in `process.argv`.
|
172 |
|
173 | ##### autoVersion
|
174 |
|
175 | Type: `boolean`\
|
176 | Default: `true`
|
177 |
|
178 | Automatically show the version text when the `--version` flag is present. Useful to set this value to `false` when a CLI manages child CLIs with their own version text.
|
179 |
|
180 | This option is only considered when there is only one argument in `process.argv`.
|
181 |
|
182 | ##### pkg
|
183 |
|
184 | Type: `object`\
|
185 | Default: Closest package.json upwards
|
186 |
|
187 | package.json as an `object`.
|
188 |
|
189 | *You most likely don't need this option.*
|
190 |
|
191 | ##### argv
|
192 |
|
193 | Type: `string[]`\
|
194 | Default: `process.argv.slice(2)`
|
195 |
|
196 | Custom arguments object.
|
197 |
|
198 | ##### inferType
|
199 |
|
200 | Type: `boolean`\
|
201 | Default: `false`
|
202 |
|
203 | Infer the argument type.
|
204 |
|
205 | By default, the argument `5` in `$ foo 5` becomes a string. Enabling this would infer it as a number.
|
206 |
|
207 | ##### booleanDefault
|
208 |
|
209 | Type: `boolean | null | undefined`\
|
210 | Default: `false`
|
211 |
|
212 | Value of `boolean` flags not defined in `argv`.
|
213 |
|
214 | If set to `undefined`, the flags not defined in `argv` will be excluded from the result.
|
215 | The `default` value set in `boolean` flags take precedence over `booleanDefault`.
|
216 |
|
217 | _Note: If used in conjunction with `isMultiple`, the default flag value is set to `[]`._
|
218 |
|
219 | __Caution: Explicitly specifying `undefined` for `booleanDefault` has different meaning from omitting key itself.__
|
220 |
|
221 | Example:
|
222 |
|
223 | ```js
|
224 | import meow from 'meow';
|
225 |
|
226 | const cli = meow(`
|
227 | Usage
|
228 | $ foo
|
229 |
|
230 | Options
|
231 | --rainbow, -r Include a rainbow
|
232 | --unicorn, -u Include a unicorn
|
233 | --no-sparkles Exclude sparkles
|
234 |
|
235 | Examples
|
236 | $ foo
|
237 | 🌈 unicorns✨🌈
|
238 | `, {
|
239 | importMeta: import.meta,
|
240 | booleanDefault: undefined,
|
241 | flags: {
|
242 | rainbow: {
|
243 | type: 'boolean',
|
244 | default: true,
|
245 | alias: 'r'
|
246 | },
|
247 | unicorn: {
|
248 | type: 'boolean',
|
249 | default: false,
|
250 | alias: 'u'
|
251 | },
|
252 | cake: {
|
253 | type: 'boolean',
|
254 | alias: 'c'
|
255 | },
|
256 | sparkles: {
|
257 | type: 'boolean',
|
258 | default: true
|
259 | }
|
260 | }
|
261 | });
|
262 | /*
|
263 | {
|
264 | flags: {
|
265 | rainbow: true,
|
266 | unicorn: false,
|
267 | sparkles: true
|
268 | },
|
269 | unnormalizedFlags: {
|
270 | rainbow: true,
|
271 | r: true,
|
272 | unicorn: false,
|
273 | u: false,
|
274 | sparkles: true
|
275 | },
|
276 | …
|
277 | }
|
278 | */
|
279 | ```
|
280 |
|
281 | ##### hardRejection
|
282 |
|
283 | Type: `boolean`\
|
284 | Default: `true`
|
285 |
|
286 | Whether to use [`hard-rejection`](https://github.com/sindresorhus/hard-rejection) or not. Disabling this can be useful if you need to handle `process.on('unhandledRejection')` yourself.
|
287 |
|
288 | ##### allowUnknownFlags
|
289 |
|
290 | Type `boolean`\
|
291 | Default: `true`
|
292 |
|
293 | Whether to allow unknown flags or not.
|
294 |
|
295 | ## Promises
|
296 |
|
297 | Meow will make unhandled rejected promises [fail hard](https://github.com/sindresorhus/hard-rejection) instead of the default silent fail. Meaning you don't have to manually `.catch()` promises used in your CLI.
|
298 |
|
299 | ## Tips
|
300 |
|
301 | See [`chalk`](https://github.com/chalk/chalk) if you want to colorize the terminal output.
|
302 |
|
303 | See [`get-stdin`](https://github.com/sindresorhus/get-stdin) if you want to accept input from stdin.
|
304 |
|
305 | See [`conf`](https://github.com/sindresorhus/conf) if you need to persist some data.
|
306 |
|
307 | See [`update-notifier`](https://github.com/yeoman/update-notifier) if you want update notifications.
|
308 |
|
309 | [More useful CLI utilities…](https://github.com/sindresorhus/awesome-nodejs#command-line-utilities)
|
310 |
|
311 | ---
|
312 |
|
313 | <div align="center">
|
314 | <b>
|
315 | <a href="https://tidelift.com/subscription/pkg/npm-meow?utm_source=npm-meow&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
|
316 | </b>
|
317 | <br>
|
318 | <sub>
|
319 | Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
|
320 | </sub>
|
321 | </div>
|