[6a3a178] | 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
|
---|