group options (#463)

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.

src/cli.mjs

@@ -158,46 +158,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())

src/lib/command-helpers.mjs

@@ -7,18 +7,36 @@ const COMMON_QUERY_OPTIONS = {
     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.",
+    group: "API:",
   },
   secret: {
     type: "string",
     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",
@@ -37,18 +55,6 @@ 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`.",
-  },
 };
 
 /**
@@ -147,19 +153,22 @@ 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.",
     default: undefined,
+    group: "API:",
   },
   timeout: {
     type: "number",
     description:
       "Maximum runtime, in milliseconds, for Fauna Core HTTP API requests made by the command.",
     default: 5000,
+    group: "API:",
   },
 };