From d6388618876a4a3f978633dd2d71b5454ea37d57 Mon Sep 17 00:00:00 2001
From: Landon Yarrington <jly.dev.36963@gmail.com>
Date: Sun, 18 Jul 2021 21:30:32 -0600
Subject: [PATCH 1/2] docs: only use parse and argv at top level

---
 docs/api.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/api.md b/docs/api.md
index 0ec6c932e..cf0673644 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -87,6 +87,8 @@ If `yargs` is executed in an environment that embeds node and there's no script
 expects it to be the script name. In order to override this behavior, use `.parse(process.argv.slice(1))`
 instead of `.argv` and the first parameter won't be ignored.
 
+***Note:*** `.argv` should only be used at the top level, not inside a command's builder function.
+
 <a name="array"></a>.array(key)
 ----------
 
@@ -336,6 +338,8 @@ yargs
   .argv
 ```
 
+***Note:*** `.parse()` and `.argv` should only be used at the top level, not inside a command's builder function.
+
 Please see [Advanced Topics: Commands](https://github.com/yargs/yargs/blob/master/docs/advanced.md#commands) for a thorough
 discussion of the advanced features exposed in the Command API.
 
@@ -1344,6 +1348,8 @@ the resulting error and output will not be passed to the `parse()` callback (the
 returning a promise. If your use case requires `parse()` to be called several times, any asynchronous
 operation performed in a command handler should not result in the handler returning a promise.
 
+***Note:*** `.parse()` should only be used at the top level, not inside a command's builder function.
+
 .parseAsync([args], [context], [parseCallback])
 ------------
 

From 78f04db547950bb241fe16807ec6e04018b21a24 Mon Sep 17 00:00:00 2001
From: Landon Yarrington <jly.dev.36963@gmail.com>
Date: Mon, 19 Jul 2021 08:07:49 -0600
Subject: [PATCH 2/2] nested example

---
 example/nested.js | 54 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 example/nested.js

diff --git a/example/nested.js b/example/nested.js
new file mode 100644
index 000000000..39e856c26
--- /dev/null
+++ b/example/nested.js
@@ -0,0 +1,54 @@
+const argv = require('yargs/yargs')(process.argv.slice(2)).command(
+  'math',
+  'math description',
+  yargs =>
+    yargs
+      .command(
+        'add <a> <b>',
+        'add description',
+        yargs =>
+          yargs
+            .positional('a', {
+              describe: 'addend "a"',
+              type: 'number',
+              default: 0,
+            })
+            .positional('b', {
+              describe: 'addend "b"',
+              type: 'number',
+              default: 0,
+            }),
+        argv => {
+          const {a, b} = argv;
+          console.log(`${a} + ${b} = ${a + b}`);
+        }
+      )
+      .command(
+        'sum <numbers..>',
+        'sum description',
+        yargs =>
+          yargs
+            .positional('numbers', {
+              describe: 'numbers to sum',
+              type: 'array',
+              default: [],
+            })
+            .check(argv =>
+              isArrayOfNumbers(argv.numbers)
+                ? true
+                : 'Positional argument "numbers" must only contain numbers'
+            ),
+        argv => {
+          const sum = argv.numbers.reduce((a, b) => a + b, 0);
+          console.log(`The sum of numbers is ${sum}`);
+        }
+      )
+).argv;
+
+console.log(argv);
+
+function isArrayOfNumbers(arr) {
+  return Array.isArray(arr) && arr.every(n => typeof n === 'number');
+}
+
+// NOTE: ".argv" and ".parse()" should only be used at top level, not inside builder functions.