diff --git a/docs/api.md b/docs/api.md
index eaff3395f..c06f73985 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -766,12 +766,23 @@ var argv = require('yargs')
.example(cmd, desc)
-------------------
+.example([[cmd1, desc1], [cmd2, desc2], ...])
+-------------------
Give some example invocations of your program. Inside `cmd`, the string
`$0` will get interpolated to the current script name or node command for the
present script similar to how `$0` works in bash or perl.
Examples will be printed out as part of the help message.
+If you want to add multiple examples at once, just pass an array of examples, e.g
+```js
+require('yargs')
+ .example([
+ ['$0 --config "~/config.json"', 'Use custom config'],
+ ['$0 --safe', 'Start in safe mode']
+ ]);
+```
+
.exitProcess(enable)
----------------------------------
diff --git a/lib/yargs.ts b/lib/yargs.ts
index 9080fa91e..ae6da41ba 100644
--- a/lib/yargs.ts
+++ b/lib/yargs.ts
@@ -451,9 +451,15 @@ export function Yargs (processArgs: string | string[] = [], cwd = process.cwd(),
return self
}
- self.example = function (cmd, description) {
- argsert(' [string]', [cmd, description], arguments.length)
- usage.example(cmd, description)
+ self.example = function (cmd: string | [string, string?][], description?: string) {
+ argsert(' [string]', [cmd, description], arguments.length)
+
+ if (Array.isArray(cmd)) {
+ cmd.forEach((exampleParams) => self.example(...exampleParams))
+ } else {
+ usage.example(cmd, description)
+ }
+
return self
}
@@ -1490,7 +1496,7 @@ export interface YargsInstance {
env (prefix?: string | false): YargsInstance
epilog: YargsInstance['epilogue']
epilogue (msg: string): YargsInstance
- example (cmd: string, description?: string): YargsInstance
+ example (cmd: string | [string, string?][], description?: string): YargsInstance
exit (code: number, err?: YError | string): void
exitProcess (enabled: boolean): YargsInstance
fail (f: FailureFunction): YargsInstance
diff --git a/test/usage.js b/test/usage.js
index ee2aa25d1..cc84d5b63 100644
--- a/test/usage.js
+++ b/test/usage.js
@@ -1084,6 +1084,33 @@ describe('usage tests', () => {
])
})
+ it('should display examples on fail when passing multiple examples at once', () => {
+ const r = checkUsage(() => yargs('')
+ .example([
+ ['$0 something', 'description'],
+ ['$0 something else', 'other description']
+ ])
+ .demand(['y'])
+ .wrap(null)
+ .parse()
+ )
+ r.should.have.property('result')
+ r.result.should.have.property('_').with.length(0)
+ r.should.have.property('errors')
+ r.should.have.property('logs').with.length(0)
+ r.should.have.property('exit').and.equal(true)
+ r.errors.join('\n').split(/\n+/).should.deep.equal([
+ 'Options:',
+ ' --help Show help [boolean]',
+ ' --version Show version number [boolean]',
+ ' -y [required]',
+ 'Examples:',
+ ' usage something description',
+ ' usage something else other description',
+ 'Missing required argument: y'
+ ])
+ })
+
describe('demand option with boolean flag', () => {
describe('with demand option', () => {
it('should report missing required arguments', () => {