Review help strings

src/cli.mjs

@@ -116,54 +116,54 @@ function buildYargs(argvInput) {
     .options({
       color: {
         description:
-          "whether or not to emit escape codes for multi-color terminal output.",
+          "Enable color formatting for the output. Uses ANSI escape codes.",
         type: "boolean",
         // https://github.com/chalk/chalk?tab=readme-ov-file#chalklevel
         default: chalk.level > 0,
       },
       config: {
         type: "string",
-        description: "a config file to use",
+        description: "Path to a CLI config file to use. Use `--profile` to select a profile from the file.",
         default: ".",
       },
       profile: {
         alias: "p",
         type: "string",
         description:
-          "the profile in your config file to fetch CLI settings from",
+          "Profile from the CLI config file to use. Each profile specifies a set of CLI settings.",
         default: "default",
       },
       user: {
         alias: "u",
         type: "string",
-        description: "a user profile",
+        description: "User profile used to run the command. Create user profiles using `fauna login`.",
         default: "default",
       },
       json: {
         type: "boolean",
-        description: "output the result as JSON",
+        description: "Output the results as JSON.",
         default: false,
       },
       quiet: {
         type: "boolean",
-        description: "only emit output",
+        description: "Only output the results of the command.",
         default: false,
       },
       verboseComponent: {
         description:
-          "components to emit diagnostic logs for; this takes precedence over the 'verbosity' flag",
+          "Comma-separated list of components to emit diagnostic logs for. Takes precedence over the `--verbosity` flag.",
         type: "array",
         default: [],
         choices: ["fetch", "error", "config", "argv", "creds"],
       },
       verbosity: {
-        description: "the lowest level diagnostic logs to emit",
+        description: "Maximum verbosity level for log messages. Accepts 1 (fatal) to 5 (debug). Lower values represent more critical logs.",
         type: "number",
         default: 0,
       },
     })
     .wrap(yargsInstance.terminalWidth())
-    .help("help", "show help")
+    .help("help", "Show help.")
     .fail(false)
     .exitProcess(false)
     .version(false)

src/commands/database/create.mjs

@@ -39,28 +39,28 @@ function buildCreateCommand(yargs) {
       name: {
         type: "string",
         required: true,
-        description: "the name of the database to create",
+        description: "Name of the database to create.",
       },
       typechecked: {
         type: "string",
-        description: "enable typechecking for the database",
+        description: "Enable typechecking. Defaults to the typechecking setting of the parent database.",
       },
       protected: {
         type: "boolean",
-        description: "allow destructive schema changes",
+        description: "Enable protected mode for the database. Protected mode disallows destructive schema changes.",
       },
       priority: {
         type: "number",
-        description: "user-defined priority assigned to the child database",
+        description: "User-defined priority for the database.",
       },
     })
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "create",
-  description: "Creates a database",
+  description: "Create a child database.",
   builder: buildCreateCommand,
   handler: createDatabase,
 };

src/commands/database/database.mjs

@@ -12,13 +12,13 @@ function buildDatabase(yargs) {
     .command(deleteCommand)
     .demandCommand()
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "database",
   aliases: ["db"],
-  describe: "Interact with your databases",
+  describe: "Create and manage databases.",
   builder: buildDatabase,
   // eslint-disable-next-line no-empty-function
   handler: () => {},

src/commands/database/delete.mjs

@@ -34,16 +34,16 @@ function buildDeleteCommand(yargs) {
       name: {
         type: "string",
         required: true,
-        description: "the name of the database to delete",
+        description: "Name of the database to delete.",
       },
     })
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "delete",
-  description: "Deletes a database",
+  description: "Delete a child database.",
   builder: buildDeleteCommand,
   handler: deleteDatabase,
 };

src/commands/database/list.mjs

@@ -77,28 +77,29 @@ function buildListCommand(yargs) {
     .options({
       pageSize: {
         type: "number",
+        description: "Maximum number of databases to return.",
         default: 1000,
       },
     })
-    .help("help", "show help")
+    .help("help", "Show help.")
     .example([
-      ["$0 database list", "list all databases"],
+      ["$0 database list", "List all top-level databases."],
       [
         "$0 database list --database 'us-std/example'",
-        "list all databases under us-std/example",
+        "list all child databases under `us-std/example`.",
       ],
       [
         "$0 database list --secret 'my-secret'",
-        "list all databases using the provided database secret",
+        "List all child databases for the database scoped to a secret.",
       ],
-      ["$0 database list --json", "list all databases and output as JSON"],
-      ["$0 database list --pageSize 10", "list the first 10 databases"],
+      ["$0 database list --json", "List all top-level databases and output as JSON."],
+      ["$0 database list --pageSize 10", "List the first 10 top-level databases"],
     ]);
 }
 
 export default {
   command: "list",
-  description: "Lists your databases",
+  description: "List databases.",
   builder: buildListCommand,
   handler: listDatabases,
 };

src/commands/query.mjs

@@ -84,7 +84,7 @@ async function queryCommand(argv) {
 
     return results;
   } catch (err) {
-    err.message = formatError(err, { apiVersion: argv.apiVersion, extra: argv.extra }); 
+    err.message = formatError(err, { apiVersion: argv.apiVersion, extra: argv.extra });
     throw err;
   }
 }
@@ -93,42 +93,42 @@ function buildQueryCommand(yargs) {
   return yargsWithCommonConfigurableQueryOptions(yargs)
     .positional("fql", {
       type: "string",
-      description: "the query to run; use - to read from stdin",
+      description: "FQL query to run. Use `-` to read from stdin.",
     })
     .nargs('fql', 1)
     .options({
       input: {
         alias: "i",
         type: "string",
         description:
-          "file path to read the query (or queries) from",
+          "Path to a file containing an FQL query to run.",
       },
       output: {
         alias: "o",
         type: "string",
-        description: "file path to write output to; defaults to stdout",
+        description: "Path to a file where query results are written. Defaults to stdout.",
       },
       extra: {
         type: "boolean",
-        description: "include additional information in the output, including stats",
+        description: "Output the full API response, including summary and query stats.",
         default: false,
       },
     })
     .example([
-      ['$0 query "Collection.all()" --database us-std/example --role admin', "run the query and write to stdout "],
-      ["$0 query -i /path/to/queries.fql --database us-std/example --role admin", "run the query from a file"],
-      ['echo "1 + 1" | $0 query - --database us-std/example --role admin', "run the query from stdin"],
-      ['$0 query -i /path/to/queries.fql -o /tmp/result.json --database us-std/example --role admin', "run the query and write to a file"],
-      ['$0 query -i /path/to/queries.fql -o /tmp/result.json --extra --database us-std/example --role admin', "run the query and write full API response to a file"],
+      ['$0 query "Collection.all()" --database us-std/example', "Run the query and write the results to stdout "],
+      ["$0 query -i /path/to/query.fql --database us-std/example", "Run the query from a file"],
+      ['echo "1 + 1" | $0 query - --database us-std/example', "Run the query from stdin"],
+      ['$0 query -i /path/to/queries.fql --output /tmp/result.json --database us-std/example', "Run the query and write the results to a file"],
+      ['$0 query -i /path/to/queries.fql --extra --output /tmp/result.json --database us-std/example', "Run the query and write the full API response to a file"],
     ])
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "query [fql]",
   aliases: ["eval"],
-  describe: "execute a query",
+  describe: "Run an FQL query.",
   builder: buildQueryCommand,
   handler: queryCommand,
 };

src/commands/schema/abandon.mjs

@@ -69,12 +69,12 @@ function buildAbandonCommand(yargs) {
     })
     .example([["$0 schema abandon"]])
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "abandon",
-  description: "Abandons the currently staged schema.",
+  description: "Abandon the current staged schema.",
   builder: buildAbandonCommand,
   handler: doAbandon,
 };

src/commands/schema/commit.mjs

@@ -73,12 +73,12 @@ function buildCommitCommand(yargs) {
     })
     .example([["$0 schema commit"]])
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "commit",
-  description: "Push the current project's .fsl files to Fauna.",
+  description: "Apply staged schema files to a database.",
   builder: buildCommitCommand,
   handler: doCommit,
 };

src/commands/schema/diff.mjs

@@ -132,7 +132,7 @@ function buildDiffCommand(yargs) {
       ["$0 schema diff --active --text"],
     ])
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {

src/commands/schema/pull.mjs

@@ -141,12 +141,12 @@ function buildPullCommand(yargs) {
       ["$0 schema pull --delete"],
     ])
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "pull",
-  describe: "Pull a database schema's .fsl files into the current project",
+  describe: "Pull a database schema's .fsl files to a local directory.",
   builder: buildPullCommand,
   handler: doPull,
 };

src/commands/schema/push.mjs

@@ -100,12 +100,12 @@ function buildPushCommand(yargs) {
       ["$0 schema push --active"],
     ])
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "push",
-  description: "Push the current project's .fsl files to Fauna.",
+  description: "Push local .fsl schema files to Fauna.",
   builder: buildPushCommand,
   handler: doPush,
 };

src/commands/schema/schema.mjs

@@ -26,12 +26,12 @@ function buildSchema(yargs) {
     .command(statusCommand)
     .demandCommand()
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "schema",
-  describe: "Manipulate Fauna schema state",
+  describe: "Manage a database's schema.",
   builder: buildSchema,
   // eslint-disable-next-line no-empty-function
   handler: () => {},

src/commands/schema/status.mjs

@@ -60,12 +60,12 @@ function buildStatusCommand(yargs) {
   return yargsWithCommonQueryOptions(yargs)
     .example([["$0 schema status"]])
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {
   command: "status",
-  description: "Print the staged schema status.",
+  description: "Print the staged schema's status.",
   builder: buildStatusCommand,
   handler: doStatus,
 };

src/commands/shell.mjs

@@ -119,7 +119,7 @@ function buildShellCommand(yargs) {
   return yargsWithCommonConfigurableQueryOptions(yargs)
     .example([["$0 shell"], ["$0 shell --database us-std/example --role admin"]])
     .version(false)
-    .help("help", "show help");
+    .help("help", "Show help.");
 }
 
 export default {