1 | <p align="center">
|
---|
2 | <img width="250" src="https://raw.githubusercontent.com/yargs/yargs/main/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 | ![ci](https://github.com/yargs/yargs/workflows/ci/badge.svg)
|
---|
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 | ```
|
---|
27 | mocha [spec..]
|
---|
28 |
|
---|
29 | Run tests with Mocha
|
---|
30 |
|
---|
31 | Commands
|
---|
32 | mocha inspect [spec..] Run tests with Mocha [default]
|
---|
33 | mocha init <path> create a client-side Mocha setup at <path>
|
---|
34 |
|
---|
35 | Rules & Behavior
|
---|
36 | --allow-uncaught Allow uncaught errors to propagate [boolean]
|
---|
37 | --async-only, -A Require all tests to use a callback (async) or
|
---|
38 | return a Promise [boolean]
|
---|
39 | ```
|
---|
40 |
|
---|
41 | * bash-completion shortcuts for commands and options.
|
---|
42 | * and [tons more](/docs/api.md).
|
---|
43 |
|
---|
44 | ## Installation
|
---|
45 |
|
---|
46 | Stable version:
|
---|
47 | ```bash
|
---|
48 | npm i yargs
|
---|
49 | ```
|
---|
50 |
|
---|
51 | Bleeding edge version with the most recent features:
|
---|
52 | ```bash
|
---|
53 | npm i yargs@next
|
---|
54 | ```
|
---|
55 |
|
---|
56 | ## Usage
|
---|
57 |
|
---|
58 | ### Simple Example
|
---|
59 |
|
---|
60 | ```javascript
|
---|
61 | #!/usr/bin/env node
|
---|
62 | const yargs = require('yargs/yargs')
|
---|
63 | const { hideBin } = require('yargs/helpers')
|
---|
64 | const argv = yargs(hideBin(process.argv)).argv
|
---|
65 |
|
---|
66 | if (argv.ships > 3 && argv.distance < 53.5) {
|
---|
67 | console.log('Plunder more riffiwobbles!')
|
---|
68 | } else {
|
---|
69 | console.log('Retreat from the xupptumblers!')
|
---|
70 | }
|
---|
71 | ```
|
---|
72 |
|
---|
73 | ```bash
|
---|
74 | $ ./plunder.js --ships=4 --distance=22
|
---|
75 | Plunder more riffiwobbles!
|
---|
76 |
|
---|
77 | $ ./plunder.js --ships 12 --distance 98.7
|
---|
78 | Retreat from the xupptumblers!
|
---|
79 | ```
|
---|
80 |
|
---|
81 | > Note: `hideBin` is a shorthand for [`process.argv.slice(2)`](https://nodejs.org/en/knowledge/command-line/how-to-parse-command-line-arguments/). It has the benefit that it takes into account variations in some environments, e.g., [Electron](https://github.com/electron/electron/issues/4690).
|
---|
82 |
|
---|
83 | ### Complex Example
|
---|
84 |
|
---|
85 | ```javascript
|
---|
86 | #!/usr/bin/env node
|
---|
87 | const yargs = require('yargs/yargs')
|
---|
88 | const { hideBin } = require('yargs/helpers')
|
---|
89 |
|
---|
90 | yargs(hideBin(process.argv))
|
---|
91 | .command('serve [port]', 'start the server', (yargs) => {
|
---|
92 | return yargs
|
---|
93 | .positional('port', {
|
---|
94 | describe: 'port to bind on',
|
---|
95 | default: 5000
|
---|
96 | })
|
---|
97 | }, (argv) => {
|
---|
98 | if (argv.verbose) console.info(`start server on :${argv.port}`)
|
---|
99 | serve(argv.port)
|
---|
100 | })
|
---|
101 | .option('verbose', {
|
---|
102 | alias: 'v',
|
---|
103 | type: 'boolean',
|
---|
104 | description: 'Run with verbose logging'
|
---|
105 | })
|
---|
106 | .parse()
|
---|
107 | ```
|
---|
108 |
|
---|
109 | Run the example above with `--help` to see the help for the application.
|
---|
110 |
|
---|
111 | ## Supported Platforms
|
---|
112 |
|
---|
113 | ### TypeScript
|
---|
114 |
|
---|
115 | yargs has type definitions at [@types/yargs][type-definitions].
|
---|
116 |
|
---|
117 | ```
|
---|
118 | npm i @types/yargs --save-dev
|
---|
119 | ```
|
---|
120 |
|
---|
121 | See usage examples in [docs](/docs/typescript.md).
|
---|
122 |
|
---|
123 | ### Deno
|
---|
124 |
|
---|
125 | As of `v16`, `yargs` supports [Deno](https://github.com/denoland/deno):
|
---|
126 |
|
---|
127 | ```typescript
|
---|
128 | import yargs from 'https://deno.land/x/yargs/deno.ts'
|
---|
129 | import { Arguments } from 'https://deno.land/x/yargs/deno-types.ts'
|
---|
130 |
|
---|
131 | yargs(Deno.args)
|
---|
132 | .command('download <files...>', 'download a list of files', (yargs: any) => {
|
---|
133 | return yargs.positional('files', {
|
---|
134 | describe: 'a list of files to do something with'
|
---|
135 | })
|
---|
136 | }, (argv: Arguments) => {
|
---|
137 | console.info(argv)
|
---|
138 | })
|
---|
139 | .strictCommands()
|
---|
140 | .demandCommand(1)
|
---|
141 | .parse()
|
---|
142 | ```
|
---|
143 |
|
---|
144 | ### ESM
|
---|
145 |
|
---|
146 | As of `v16`,`yargs` supports ESM imports:
|
---|
147 |
|
---|
148 | ```js
|
---|
149 | import yargs from 'yargs'
|
---|
150 | import { hideBin } from 'yargs/helpers'
|
---|
151 |
|
---|
152 | yargs(hideBin(process.argv))
|
---|
153 | .command('curl <url>', 'fetch the contents of the URL', () => {}, (argv) => {
|
---|
154 | console.info(argv)
|
---|
155 | })
|
---|
156 | .demandCommand(1)
|
---|
157 | .parse()
|
---|
158 | ```
|
---|
159 |
|
---|
160 | ### Usage in Browser
|
---|
161 |
|
---|
162 | See examples of using yargs in the browser in [docs](/docs/browser.md).
|
---|
163 |
|
---|
164 | ## Community
|
---|
165 |
|
---|
166 | Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com).
|
---|
167 |
|
---|
168 | ## Documentation
|
---|
169 |
|
---|
170 | ### Table of Contents
|
---|
171 |
|
---|
172 | * [Yargs' API](/docs/api.md)
|
---|
173 | * [Examples](/docs/examples.md)
|
---|
174 | * [Parsing Tricks](/docs/tricks.md)
|
---|
175 | * [Stop the Parser](/docs/tricks.md#stop)
|
---|
176 | * [Negating Boolean Arguments](/docs/tricks.md#negate)
|
---|
177 | * [Numbers](/docs/tricks.md#numbers)
|
---|
178 | * [Arrays](/docs/tricks.md#arrays)
|
---|
179 | * [Objects](/docs/tricks.md#objects)
|
---|
180 | * [Quotes](/docs/tricks.md#quotes)
|
---|
181 | * [Advanced Topics](/docs/advanced.md)
|
---|
182 | * [Composing Your App Using Commands](/docs/advanced.md#commands)
|
---|
183 | * [Building Configurable CLI Apps](/docs/advanced.md#configuration)
|
---|
184 | * [Customizing Yargs' Parser](/docs/advanced.md#customizing)
|
---|
185 | * [Bundling yargs](/docs/bundling.md)
|
---|
186 | * [Contributing](/contributing.md)
|
---|
187 |
|
---|
188 | ## Supported Node.js Versions
|
---|
189 |
|
---|
190 | Libraries in this ecosystem make a best effort to track
|
---|
191 | [Node.js' release schedule](https://nodejs.org/en/about/releases/). Here's [a
|
---|
192 | post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
|
---|
193 |
|
---|
194 | [npm-url]: https://www.npmjs.com/package/yargs
|
---|
195 | [npm-image]: https://img.shields.io/npm/v/yargs.svg
|
---|
196 | [standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
|
---|
197 | [standard-url]: http://standardjs.com/
|
---|
198 | [conventional-commits-image]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg
|
---|
199 | [conventional-commits-url]: https://conventionalcommits.org/
|
---|
200 | [slack-image]: http://devtoolscommunity.herokuapp.com/badge.svg
|
---|
201 | [slack-url]: http://devtoolscommunity.herokuapp.com
|
---|
202 | [type-definitions]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/main/types/yargs
|
---|
203 | [coverage-image]: https://img.shields.io/nycrc/yargs/yargs
|
---|
204 | [coverage-url]: https://github.com/yargs/yargs/blob/main/.nycrc
|
---|