1 | <p align="center">
|
2 | <img width="250" src="/yargs-logo.png">
|
3 | </p>
|
4 | <h1 align="center"> Yargs </h1>
|
5 | <p align="center">
|
6 | <b >Yargs be a node.js library fer hearties tryin' ter parse optstrings</b>
|
7 | </p>
|
8 |
|
9 | <br>
|
10 |
|
11 | [![Build Status][travis-image]][travis-url]
|
12 | [![NPM version][npm-image]][npm-url]
|
13 | [![js-standard-style][standard-image]][standard-url]
|
14 | [![Coverage][coverage-image]][coverage-url]
|
15 | [![Conventional Commits][conventional-commits-image]][conventional-commits-url]
|
16 | [![Slack][slack-image]][slack-url]
|
17 |
|
18 | ## Description :
|
19 | Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface.
|
20 |
|
21 | It gives you:
|
22 |
|
23 | * commands and (grouped) options (`my-program.js serve --port=5000`).
|
24 | * a dynamically generated help menu based on your arguments.
|
25 |
|
26 | > <img width="400" src="/screen.png">
|
27 |
|
28 | * bash-completion shortcuts for commands and options.
|
29 | * and [tons more](/docs/api.md).
|
30 |
|
31 | ## Installation
|
32 |
|
33 | Stable version:
|
34 | ```bash
|
35 | npm i yargs
|
36 | ```
|
37 |
|
38 | Bleeding edge version with the most recent features:
|
39 | ```bash
|
40 | npm i yargs@next
|
41 | ```
|
42 |
|
43 | ## Usage :
|
44 |
|
45 | ### Simple Example
|
46 |
|
47 | ````javascript
|
48 | #!/usr/bin/env node
|
49 | const argv = require('yargs').argv
|
50 |
|
51 | if (argv.ships > 3 && argv.distance < 53.5) {
|
52 | console.log('Plunder more riffiwobbles!')
|
53 | } else {
|
54 | console.log('Retreat from the xupptumblers!')
|
55 | }
|
56 | ````
|
57 |
|
58 | ```bash
|
59 | $ ./plunder.js --ships=4 --distance=22
|
60 | Plunder more riffiwobbles!
|
61 |
|
62 | $ ./plunder.js --ships 12 --distance 98.7
|
63 | Retreat from the xupptumblers!
|
64 | ```
|
65 |
|
66 | ### Complex Example
|
67 |
|
68 | ```javascript
|
69 | #!/usr/bin/env node
|
70 | require('yargs') // eslint-disable-line
|
71 | .command('serve [port]', 'start the server', (yargs) => {
|
72 | yargs
|
73 | .positional('port', {
|
74 | describe: 'port to bind on',
|
75 | default: 5000
|
76 | })
|
77 | }, (argv) => {
|
78 | if (argv.verbose) console.info(`start server on :${argv.port}`)
|
79 | serve(argv.port)
|
80 | })
|
81 | .option('verbose', {
|
82 | alias: 'v',
|
83 | type: 'boolean',
|
84 | description: 'Run with verbose logging'
|
85 | })
|
86 | .argv
|
87 | ```
|
88 |
|
89 | Run the example above with `--help` to see the help for the application.
|
90 |
|
91 | ## TypeScript
|
92 |
|
93 | yargs has type definitions at [@types/yargs][type-definitions].
|
94 |
|
95 | ```
|
96 | npm i @types/yargs --save-dev
|
97 | ```
|
98 |
|
99 | See usage examples in [docs](/docs/typescript.md).
|
100 |
|
101 | ## Webpack
|
102 |
|
103 | See usage examples of yargs with webpack in [docs](/docs/webpack.md).
|
104 |
|
105 | ## Community :
|
106 |
|
107 | Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com).
|
108 |
|
109 | ## Documentation :
|
110 |
|
111 | ### Table of Contents
|
112 |
|
113 | * [Yargs' API](/docs/api.md)
|
114 | * [Examples](/docs/examples.md)
|
115 | * [Parsing Tricks](/docs/tricks.md)
|
116 | * [Stop the Parser](/docs/tricks.md#stop)
|
117 | * [Negating Boolean Arguments](/docs/tricks.md#negate)
|
118 | * [Numbers](/docs/tricks.md#numbers)
|
119 | * [Arrays](/docs/tricks.md#arrays)
|
120 | * [Objects](/docs/tricks.md#objects)
|
121 | * [Quotes](/docs/tricks.md#quotes)
|
122 | * [Advanced Topics](/docs/advanced.md)
|
123 | * [Composing Your App Using Commands](/docs/advanced.md#commands)
|
124 | * [Building Configurable CLI Apps](/docs/advanced.md#configuration)
|
125 | * [Customizing Yargs' Parser](/docs/advanced.md#customizing)
|
126 | * [Contributing](/contributing.md)
|
127 |
|
128 | [travis-url]: https://travis-ci.org/yargs/yargs
|
129 | [travis-image]: https://img.shields.io/travis/yargs/yargs/master.svg
|
130 | [npm-url]: https://www.npmjs.com/package/yargs
|
131 | [npm-image]: https://img.shields.io/npm/v/yargs.svg
|
132 | [standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
|
133 | [standard-url]: http://standardjs.com/
|
134 | [conventional-commits-image]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg
|
135 | [conventional-commits-url]: https://conventionalcommits.org/
|
136 | [slack-image]: http://devtoolscommunity.herokuapp.com/badge.svg
|
137 | [slack-url]: http://devtoolscommunity.herokuapp.com
|
138 | [type-definitions]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs
|
139 | [coverage-image]: https://img.shields.io/badge/dynamic/json?color=brightgreen&label=coverage&query=branches&suffix=%25&url=https%3A%2F%2Fraw.githubusercontent.com%2Fyargs%2Fyargs%2Fmaster%2F.nycrc&cacheSeconds=3600
|
140 | [coverage-url]: https://github.com/yargs/yargs/blob/master/.nycrc |
\ | No newline at end of file |