README.md
1 <p align="center"> 2 <img width="250" src="https://raw.githubusercontent.com/yargs/yargs/master/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  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 ### Complex Example 82 83 ```javascript 84 #!/usr/bin/env node 85 const yargs = require('yargs/yargs') 86 const { hideBin } = require('yargs/helpers') 87 88 yargs(hideBin(process.argv)) 89 .command('serve [port]', 'start the server', (yargs) => { 90 yargs 91 .positional('port', { 92 describe: 'port to bind on', 93 default: 5000 94 }) 95 }, (argv) => { 96 if (argv.verbose) console.info(`start server on :${argv.port}`) 97 serve(argv.port) 98 }) 99 .option('verbose', { 100 alias: 'v', 101 type: 'boolean', 102 description: 'Run with verbose logging' 103 }) 104 .argv 105 ``` 106 107 Run the example above with `--help` to see the help for the application. 108 109 ## Supported Platforms 110 111 ### TypeScript 112 113 yargs has type definitions at [@types/yargs][type-definitions]. 114 115 ``` 116 npm i @types/yargs --save-dev 117 ``` 118 119 See usage examples in [docs](/docs/typescript.md). 120 121 ### Deno 122 123 As of `v16`, `yargs` supports [Deno](https://github.com/denoland/deno): 124 125 ```typescript 126 import yargs from 'https://deno.land/x/yargs/deno.ts' 127 import { Arguments } from 'https://deno.land/x/yargs/deno-types.ts' 128 129 yargs(Deno.args) 130 .command('download <files...>', 'download a list of files', (yargs: any) => { 131 return yargs.positional('files', { 132 describe: 'a list of files to do something with' 133 }) 134 }, (argv: Arguments) => { 135 console.info(argv) 136 }) 137 .strictCommands() 138 .demandCommand(1) 139 .argv 140 ``` 141 142 ### ESM 143 144 As of `v16`,`yargs` supports ESM imports: 145 146 ```js 147 import yargs from 'yargs' 148 import { hideBin } from 'yargs/helpers' 149 150 yargs(hideBin(process.argv)) 151 .command('curl <url>', 'fetch the contents of the URL', () => {}, (argv) => { 152 console.info(argv) 153 }) 154 .demandCommand(1) 155 .argv 156 ``` 157 158 ### Usage in Browser 159 160 See examples of using yargs in the browser in [docs](/docs/browser.md). 161 162 ## Community 163 164 Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com). 165 166 ## Documentation 167 168 ### Table of Contents 169 170 * [Yargs' API](/docs/api.md) 171 * [Examples](/docs/examples.md) 172 * [Parsing Tricks](/docs/tricks.md) 173 * [Stop the Parser](/docs/tricks.md#stop) 174 * [Negating Boolean Arguments](/docs/tricks.md#negate) 175 * [Numbers](/docs/tricks.md#numbers) 176 * [Arrays](/docs/tricks.md#arrays) 177 * [Objects](/docs/tricks.md#objects) 178 * [Quotes](/docs/tricks.md#quotes) 179 * [Advanced Topics](/docs/advanced.md) 180 * [Composing Your App Using Commands](/docs/advanced.md#commands) 181 * [Building Configurable CLI Apps](/docs/advanced.md#configuration) 182 * [Customizing Yargs' Parser](/docs/advanced.md#customizing) 183 * [Bundling yargs](/docs/bundling.md) 184 * [Contributing](/contributing.md) 185 186 ## Supported Node.js Versions 187 188 Libraries in this ecosystem make a best effort to track 189 [Node.js' release schedule](https://nodejs.org/en/about/releases/). Here's [a 190 post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a). 191 192 [npm-url]: https://www.npmjs.com/package/yargs 193 [npm-image]: https://img.shields.io/npm/v/yargs.svg 194 [standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg 195 [standard-url]: http://standardjs.com/ 196 [conventional-commits-image]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg 197 [conventional-commits-url]: https://conventionalcommits.org/ 198 [slack-image]: http://devtoolscommunity.herokuapp.com/badge.svg 199 [slack-url]: http://devtoolscommunity.herokuapp.com 200 [type-definitions]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs 201 [coverage-image]: https://img.shields.io/nycrc/yargs/yargs 202 [coverage-url]: https://github.com/yargs/yargs/blob/master/.nycrc