group options

right now, we present all the options in one blob. this change groups the config options into these groups: - Output (format, quiet, color) - Config (config, profile) - API (user, role, database, secret) - Debug (verbosity, verboseComponent) - Options (help and all command-specific options) these groups can/should be renamed and rearranged, but this grouping should be a readability improvement over the current soup of flags.
fauna · Dec 4, 2024 · c5c1cb6 · c5c1cb6
1 parent 798c39c
commit c5c1cb6
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 23 deletions.
diff --git a/src/cli.mjs b/src/cli.mjs
@@ -120,46 +120,58 @@ function buildYargs(argvInput) {
         type: "boolean",
         // https://github.com/chalk/chalk?tab=readme-ov-file#chalklevel
         default: chalk.level > 0,
+        group: "Output:",
       },
       config: {
         type: "string",
-        description: "Path to a CLI config file to use. Use `--profile` to select a profile from the file.",
+        description:
+          "Path to a CLI config file to use. Use `--profile` to select a profile from the file.",
         default: ".",
+        group: "Config:",
       },
       profile: {
         alias: "p",
         type: "string",
         description:
           "Profile from the CLI config file to use. Each profile specifies a set of CLI settings.",
         default: "default",
+        group: "Config:",
       },
       user: {
         alias: "u",
         type: "string",
-        description: "User account used to run the command. Register a user account in the CLI using `fauna login`.",
+        description:
+          "User account used to run the command. Register a user account in the CLI using `fauna login`.",
         default: "default",
+        group: "API:",
       },
       json: {
         type: "boolean",
         description: "Output the results as JSON.",
         default: false,
+        group: "Output:",
       },
       quiet: {
         type: "boolean",
-        description: "Only output the results of the command. Useful for scripts, CI/CD, and automation workflows.",
+        description:
+          "Only output the results of the command. Useful for scripts, CI/CD, and automation workflows.",
         default: false,
+        group: "Output:",
       },
       verboseComponent: {
         description:
-          "Components to emit diagnostic logs for. Takes precedence over the `--verbosity` flag. Pass components as a comma-separate list, such as `--verboseComponent fetch, error`, or as separate flags, such as `--verboseComponent fetch --verboseComponent error`.",
+          "Components to emit diagnostic logs for. Takes precedence over the `--verbosity` flag. Pass components as a space-separated list, such as `--verboseComponent fetch error`, or as separate flags, such as `--verboseComponent fetch --verboseComponent error`.",
         type: "array",
         default: [],
         choices: ["fetch", "error", "config", "argv", "creds"],
+        group: "Debug:",
       },
       verbosity: {
-        description: "Maximum verbosity level for log messages. Accepts 1 (fatal) to 5 (debug). Lower values represent more critical logs.",
+        description:
+          "Maximum verbosity level for log messages. Accepts 1 (fatal) to 5 (debug). Lower values represent more critical logs.",
         type: "number",
         default: 0,
+        group: "Debug:",
       },
     })
     .wrap(yargsInstance.terminalWidth())

diff --git a/src/lib/command-helpers.mjs b/src/lib/command-helpers.mjs
@@ -3,19 +3,40 @@
 // used for queries customers can't configure that are made on their behalf
 const COMMON_QUERY_OPTIONS = {
   local: {
-    type: 'boolean',
-    describe: 'Use a local Fauna container. If not otherwise specified, sets `--url` to http://localhost:8443 and `--secret` to "secret".',
+    type: "boolean",
+    describe:
+      'Use a local Fauna container. If not otherwise specified, sets `--url` to http://localhost:8443 and `--secret` to "secret".',
     default: false,
+    group: "API:",
   },
   url: {
     type: "string",
-    description: "URL for Fauna Core HTTP API requests made by the command. Defaults to https://db.fauna.com.",
+    description:
+      "URL for Fauna Core HTTP API requests made by the command. Defaults to https://db.fauna.com.",
+    group: "API:",
   },
   secret: {
     type: "string",
-    description: "Authentication secret for Fauna Core HTTP API requests made by the command. Mutually exclusive with `--database` and `--role`.",
+    description:
+      "Authentication secret for Fauna Core HTTP API requests made by the command. Mutually exclusive with `--database` and `--role`.",
     required: false,
+    group: "API:",
+  },
+  database: {
+    alias: "d",
+    type: "string",
+    description:
+      "Path, including Region Group identifier and hierarchy, for the database to run the command in. Mutually exclusive with `--secret`.",
+    group: "API:",
   },
+  role: {
+    alias: "r",
+    type: "string",
+    description:
+      "Role used to run the command. Mutually exclusive with `--secret`.",
+    group: "API:",
+  },
+  // hidden
   accountUrl: {
     type: "string",
     description: "the Fauna account URL to query",
@@ -34,19 +55,8 @@ const COMMON_QUERY_OPTIONS = {
     required: false,
     hidden: true,
   },
-  database: {
-    alias: "d",
-    type: "string",
-    description: "Path, including Region Group identifier and hierarchy, for the database to run the command in. Mutually exclusive with `--secret`.",
-  },
-  role: {
-    alias: "r",
-    type: "string",
-    description: "Role used to run the command. Mutually exclusive with `--secret`."
-  },
 };
 
-
 /**
  * Validate that the user has specified either a database or a secret.
  * This check is not required for commands that can operate at a
@@ -70,18 +80,23 @@ const COMMON_CONFIGURABLE_QUERY_OPTIONS = {
     alias: "v",
     default: "10",
     choices: ["4", "10"],
+    group: "API:",
   },
   // v10 specific options
   typecheck: {
     type: "boolean",
-    description: "Enable typechecking. Defaults to the typechecking setting of the database.",
+    description:
+      "Enable typechecking. Defaults to the typechecking setting of the database.",
     default: undefined,
+    group: "API:",
   },
   timeout: {
     type: "number",
-    description: "Maximum runtime, in milliseconds, for Fauna Core HTTP API requests made by the command.",
+    description:
+      "Maximum runtime, in milliseconds, for Fauna Core HTTP API requests made by the command.",
     default: 5000,
-  }
+    group: "API:",
+  },
 };
 
 export function yargsWithCommonQueryOptions(yargs) {