Review help text and examples

README.md

@@ -53,8 +53,8 @@ To get started:
    fauna login
    ```
 
-4. Run CLI commands. Specify a `--database` path, including the [Region Group
-   identifier](https://docs.fauna.com/fauna/current/manage/region-groups/#id) and
+4. Run CLI commands. Specify a `--database`, including the [Region
+   Group](https://docs.fauna.com/fauna/current/manage/region-groups/#id) and
    hierarchy, to run the command in. For example:
 
    ```shell

src/cli.mjs

@@ -122,7 +122,7 @@
     .strictCommands(true)
     .completion(
       "completion",
-      "Output bash/zsh script to enable shell completions. See command output for installation instructions.",
+      "Output a bash/zsh script for CLI auto-completions. See command output for installation instructions.",
       async function (currentWord, argv, defaultCompletions, done) {
         // this is pretty hard to debug - if you need to, run
         // `fauna --get-yargs-completions <command> <flag> <string to match>`
@@ -141,7 +141,7 @@
           .filter((key) => previousWord === key)
           .pop();
 
         // TODO: this doesn't handle aliasing, and it needs to
         if (
           currentWord === "--profile" ||
           currentWordFlag === "profile" ||
@@ -163,8 +163,7 @@
     )
     .options({
       color: {
-        description:
-          "Enable color formatting for the output. Uses ANSI escape codes. Enabled by default if supported by the terminal. Use `--no-color` or `--color=false` to disable.",
+        description: "Enable color formatting. Use --no-color to disable.",
         type: "boolean",
         // https://github.com/chalk/chalk?tab=readme-ov-file#chalklevel
         default: chalk.level > 0,
@@ -173,15 +172,14 @@
       config: {
         type: "string",
         description:
-          "Path to a CLI config file to use. Use `--profile` to select a profile from the file.",
+          "Path to a CLI config file to use. If provided, you must specify a profile.",
         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. Defaults to the 'default' profile when a config file is provided.",
+        description: "Profile from the CLI config file to use.",
         group: "Config:",
       },
       json: {
@@ -193,21 +191,21 @@
       quiet: {
         type: "boolean",
         description:
-          "Only output the results of the command. Useful for scripts, CI/CD, and automation workflows.",
+          "Suppress all log messages except fatal errors. Overrides --verbosity and --verbose-component.",
         default: false,
         group: "Output:",
       },
       "verbose-component": {
         description:
-          "Components to emit diagnostic logs for. Takes precedence over the `--verbosity` flag. Pass components as a space-separated list, such as `--verbose-component fetch error`, or as separate flags, such as `--verbose-component fetch --verbose-component error`.",
+          "Components to emit logs for. Overrides the --verbosity flag. Pass values as a space-separated list. Ex: --verbose-component fetch error.",
         type: "array",
         default: [],
-        choices: ["fetch", "error", "config", "argv", "creds", "completion"],
+        choices: ["argv", "completion", "config", "creds", "error", "fetch"],
         group: "Debug:",
       },
       verbosity: {
         description:
-          "Maximum verbosity level for log messages. Accepts 1 (fatal) to 5 (debug). Lower values represent more critical logs.",
+          "Least critical log level to emit. Accepts 1 (fatal) to 5 (debug). Lower values represent more critical logs.",
         type: "number",
         default: 0,
         group: "Debug:",

src/commands/database/create.mjs

@@ -80,7 +80,7 @@ function buildCreateCommand(yargs) {
       name: {
         type: "string",
         required: true,
-        description: "Name of the child database to create.",
+        description: "Name of the database to create.",
       },
       typechecked: {
         type: "boolean",
@@ -100,27 +100,31 @@ function buildCreateCommand(yargs) {
     .check(validateDatabaseOrSecret)
     .example([
       [
-        "$0 database create --name my_database --database us/example",
-        "Create a database named 'my_database' directly under 'us/example'.",
+        "$0 database create --name example --database us",
+        "Create the top-level 'example' database in the 'us' Region Group.",
       ],
       [
-        "$0 database create --name my_database --secret my-secret",
-        "Create a database named 'my_database' directly under the database scoped to a secret.",
+        "$0 database create --name my_db --database us/example",
+        "Create the 'my_db' child database directly under 'us/example'.",
       ],
       [
-        "$0 database create --name my_database --database us/example --typechecked",
+        "$0 database create --name my_db --secret my-secret",
+        "Create the 'my_db' child database directly under the database scoped to a secret.",
+      ],
+      [
+        "$0 database create --name example --database us --typechecked",
         "Create a database with typechecking enabled.",
       ],
       [
-        "$0 database create --name my_database --database us/example --protected",
+        "$0 database create --name example --database us --protected",
         "Create a database with protected mode enabled.",
       ],
     ]);
 }
 
 export default {
   command: "create",
-  description: "Create a child database.",
+  description: "Create a database.",
   builder: buildCreateCommand,
   handler: createDatabase,
 };

src/commands/database/delete.mjs

@@ -56,19 +56,23 @@ function buildDeleteCommand(yargs) {
     .check(validateDatabaseOrSecret)
     .example([
       [
-        "$0 database delete --name my_database --database us/example",
-        "Delete a database named 'my_database' directly under 'us/example'.",
+        "$0 database delete --name example --database us",
+        "Delete the top-level 'example' database in the 'us' Region Group.",
       ],
       [
-        "$0 database delete --name my_database --secret my-secret",
-        "Delete a database named 'my_database' directly under the database scoped to a secret.",
+        "$0 database delete --name my_db --database us/example",
+        "Delete the 'my_db' child database directly under 'us/example'.",
+      ],
+      [
+        "$0 database delete --name my_db --secret my-secret",
+        "Delete the 'my_db' child database directly under the database scoped to a secret.",
       ],
     ]);
 }
 
 export default {
   command: "delete",
-  description: "Delete a child database.",
+  description: "Delete a database.",
   builder: buildDeleteCommand,
   handler: deleteDatabase,
 };

src/commands/local.mjs

@@ -124,35 +124,35 @@
   return yargs
     .options({
       "container-port": {
-        describe: "The port inside the container Fauna listens on.",
+        describe: "Port inside the container Fauna listens on.",
         type: "number",
         default: 8443,
       },
       "host-port": {
         describe:
-          "The port on the host machine mapped to the container's port. This is the port you'll connect to Fauna on.",
+          "Port on the host machine mapped to the container's port. Clients send requests to Fauna on this port.",
         type: "number",
         default: 8443,
       },
       "host-ip": {
-        describe: `The IP address to bind the container's exposed port on the host.`,
+        describe: `IP address to bind to the container's exposed port on the host.`,
         type: "string",
         default: "0.0.0.0",
       },
       interval: {
         describe:
-          "The interval (in milliseconds) between health check attempts. Determines how often the CLI checks if the Fauna container is ready.",
+          "Interval, in milliseconds, between health check attempts. How often the CLI checks if the container is ready.",
         type: "number",
         default: 10000,
       },
       "max-attempts": {
         describe:
-          "The maximum number of health check attempts before declaring the start Fauna continer process as failed.",
+          "Maximum number of health check attempts allowed before container startup fails.",
         type: "number",
         default: 100,
       },
       name: {
-        describe: "The name to give the container.",
+        describe: "Name for the container.",
         type: "string",
         default: "faunadb",
       },
@@ -162,8 +162,7 @@
         default: true,
       },
       database: {
-        describe:
-          "The name of a database to create in the container. Omit to create no database.",
+        describe: "Name of the database to create. Omit to create no database.",
         type: "string",
       },
       typechecked: {
@@ -185,22 +184,21 @@
         type: "string",
         alias: ["dir", "directory"],
         description:
-          "Path to a local directory containing `.fsl` files for the database. Valid only if --database is set.",
+          "Path to a local directory containing .fsl files for the database. Valid only if --database is set.",
       },
       active: {
         description:
-          "Immediately applies the local schema to the database's active schema, skipping staging the schema. To disable this, use `--no-active` or `--active=false`.",
+          "Apply the local schema to the database's active schema. Skips staging the schema. Use --no-active to disable.",
         type: "boolean",
         default: true,
       },
       input: {
-        description:
-          "Prompt for schema input, such as confirmation. To disable prompts, use `--no-input` or `--input=false`. Disabled prompts are useful for scripts, CI/CD, and automation workflows.",
+        description: "Prompt for input. Use --no-input to disable.",
         default: true,
         type: "boolean",
       },
     })
     .check((argv) => {
       if (argv.maxAttempts < 1) {
         throw new ValidationError("--max-attempts must be greater than 0.");
       }
@@ -230,7 +228,23 @@
         );
       }
       return true;
-    });
+    })
+    .example([
+      ["$0 local", "Start a Fauna container with default name and ports."],
+      ["$0 local --name local-fauna", "Start a container named 'local-fauna'."],
+      [
+        "$0 local --host-port 123 --container-port 6789",
+        "Map host port `1234` to container port `6789`.",
+      ],
+      [
+        "$0 local --database example",
+        "Start a local Fauna container with the 'example' database.",
+      ],
+      [
+        "$0 local --database example --dir /path/to/schema/dir",
+        "Start a local Fauna container with a database with specified schema.",
+      ],
+    ]);
 }
 
 export default {

src/commands/login.mjs

@@ -53,7 +53,7 @@ function buildLoginCommand(yargs) {
 
 export default {
   command: "login",
-  describe: "Log in to Fauna using a web-based browser flow.",
+  describe: "Log in to Fauna.",
   builder: buildLoginCommand,
   handler: doLogin,
 };

src/commands/query.mjs

@@ -152,7 +152,7 @@ function buildQueryCommand(yargs) {
   return yargsWithCommonConfigurableQueryOptions(yargs)
     .positional("fql", {
       type: "string",
-      description: "FQL query to run. Use `-` to read from stdin.",
+      description: "FQL query to run. Use - to read from stdin.",
     })
     .nargs("fql", 1)
     .options({

src/commands/schema/abandon.mjs

@@ -68,8 +68,7 @@ function buildAbandonCommand(yargs) {
   return yargsWithCommonQueryOptions(yargs)
     .options({
       input: {
-        description:
-          "Prompt for input, such as confirmation. To disable prompts, use `--no-input` or `--input=false`. Disabled prompts are useful for scripts, CI/CD, and automation workflows.",
+        description: "Prompt for input. Use --no-input to disable.",
         default: true,
         type: "boolean",
       },

src/commands/schema/commit.mjs

@@ -72,8 +72,7 @@ function buildCommitCommand(yargs) {
   return yargsWithCommonQueryOptions(yargs)
     .options({
       input: {
-        description:
-          "Prompt for input, such as confirmation. To disable prompts, use `--no-input` or `--input=false`. Disabled prompts are useful for scripts, CI/CD, and automation workflows.",
+        description: "Prompt for input. Use --no-input to disable.",
         default: true,
         type: "boolean",
       },

src/commands/schema/diff.mjs

@@ -132,23 +132,23 @@ function buildDiffCommand(yargs) {
     })
     .example([
       [
-        "$0 schema diff --database us/example --dir /path/to/schema",
+        "$0 schema diff --database us/example --dir /path/to/schema/dir",
         "Compare the 'us/example' database's staged schema to the local schema. If no schema is staged, compare the database's active schema to the local schema.",
       ],
       [
-        "$0 schema diff --database us/example --dir /path/to/schema --active",
+        "$0 schema diff --database us/example --dir /path/to/schema/dir --active",
         "Compare the 'us/example' database's active schema to the local schema.",
       ],
       [
-        "$0 schema diff --secret my-secret --dir /path/to/schema --active",
+        "$0 schema diff --secret my-secret --dir /path/to/schema/dir --active",
         "Compare the active schema of the database scoped to a secret to the local schema.",
       ],
       [
-        "$0 schema diff --database us/example --dir /path/to/schema --staged",
+        "$0 schema diff --database us/example --dir /path/to/schema/dir --staged",
         "Compare the 'us/example' database's active schema to its staged schema.",
       ],
       [
-        "$0 schema diff --database us/example --dir /path/to/schema --text",
+        "$0 schema diff --database us/example --dir /path/to/schema/dir --text",
         "Show a text diff instead of a semantic diff.",
       ],
     ]);

src/commands/schema/pull.mjs

@@ -152,20 +152,20 @@ function buildPullCommand(yargs) {
     })
     .example([
       [
-        "$0 schema pull --database us/example --dir /path/to/schema",
+        "$0 schema pull --database us/example --dir /path/to/schema/dir",
         "Pull the 'us/example' database's staged schema.",
       ],
       [
-        "$0 schema pull --secret my-secret --dir /path/to/schema",
+        "$0 schema pull --secret my-secret --dir /path/to/schema/dir",
         "Pull the staged schema for the database scoped to a secret.",
       ],
       [
-        "$0 schema pull --database us/example --dir /path/to/schema --active",
+        "$0 schema pull --database us/example --dir /path/to/schema/dir --active",
         "Pull the 'us/example' database's active schema.",
       ],
       [
-        "$0 schema pull --database us/example --dir /path/to/schema --delete",
-        "Delete `.fsl` files in the local directory that are not part of the pulled schema.",
+        "$0 schema pull --database us/example --dir /path/to/schema/dir --delete",
+        "Delete .fsl files in the local directory that are not part of the pulled schema.",
       ],
     ]);
 }

src/commands/schema/push.mjs

@@ -101,34 +101,33 @@ function buildPushCommand(yargs) {
   return yargsWithCommonQueryOptions(yargs)
     .options({
       input: {
-        description:
-          "Prompt for input, such as confirmation. To disable prompts, use `--no-input` or `--input=false`. Disabled prompts are useful for scripts, CI/CD, and automation workflows.",
+        description: "Prompt for input. Use --no-input to disable.",
         default: true,
         type: "boolean",
       },
       active: {
         description:
-          "Immediately apply the local schema to the database's active schema. Skips staging the schema. Can result in temporarily unavailable indexes.",
+          "Apply the local schema to the database's active schema. Can result in temporarily unavailable indexes.",
         type: "boolean",
         default: false,
       },
       ...localSchemaOptions,
     })
     .example([
       [
-        "$0 schema push --database us/example --dir /path/to/schema",
+        "$0 schema push --database us/example --dir /path/to/schema/dir",
         "Stage schema changes for the 'us/example' database. If schema is already staged, replace the staged schema.",
       ],
       [
-        "$0 schema push --secret my-secret --dir /path/to/schema",
+        "$0 schema push --secret my-secret --dir /path/to/schema/dir",
         "Stage schema changes for the database scoped to a secret. If schema is already staged, replace the staged schema.",
       ],
       [
-        "$0 schema push --database us/example --dir /path/to/schema --active",
+        "$0 schema push --database us/example --dir /path/to/schema/dir --active",
         "Immediately apply changes to the 'us/example' database's active schema.",
       ],
       [
-        "$0 schema push --database us/example --dir /path/to/schema --no-input",
+        "$0 schema push --database us/example --dir /path/to/schema/dir --no-input",
         "Run the command without input prompts.",
       ],
     ]);

src/commands/schema/schema.mjs

@@ -13,7 +13,7 @@ export const localSchemaOptions = {
     alias: ["directory", "dir"],
     type: "string",
     description:
-      "Path to a local directory containing `.fsl` files for the database.",
+      "Path to a local directory containing .fsl files for the database.",
     default: ".",
   },
 };