docs: update --help text for Lingo.dev CLI (#1177)

Author: davidturnbull

.changeset/cli-command-docs.md

@@ -0,0 +1,5 @@
+---
+"lingo.dev": patch
+---
+
+Improve CLI command descriptions

packages/cli/src/cli/cmd/auth.ts

@@ -5,16 +5,16 @@ import { createAuthenticator } from "../utils/auth";
 
 export default new Command()
   .command("auth")
-  .description("Show current authentication status")
+  .description("Show current authentication status and user email")
   .helpOption("-h, --help", "Show help")
   // Deprecated options, safe to remove after September 2025
   .option(
     "--login",
-    "Login to your account (deprecated: use 'lingo.dev login' instead)",
+    "DEPRECATED: Shows deprecation warning and exits. Use `lingo.dev login` instead",
   )
   .option(
     "--logout",
-    "Logout from your account (deprecated: use 'lingo.dev logout' instead)",
+    "DEPRECATED: Shows deprecation warning and exits. Use `lingo.dev logout` instead",
   )
   .action(async (options) => {
     try {

packages/cli/src/cli/cmd/ci/index.ts

@@ -20,21 +20,37 @@ interface CIOptions {
 
 export default new Command()
   .command("ci")
-  .description("Run Lingo.dev CI/CD action")
+  .description("Run localization pipeline in CI/CD environment")
   .helpOption("-h, --help", "Show help")
-  .option("--parallel [boolean]", "Run in parallel mode", parseBooleanArg)
-  .option("--api-key <key>", "API key")
+  .option(
+    "--parallel [boolean]",
+    "Process translations concurrently for faster execution. Defaults to false",
+    parseBooleanArg,
+  )
+  .option(
+    "--api-key <key>",
+    "Override API key from settings or environment variables",
+  )
   .option(
     "--pull-request [boolean]",
-    "Create a pull request with the changes",
+    "Create or update translations on a dedicated branch and manage pull requests automatically. When false, commits directly to current branch. Defaults to false",
     parseBooleanArg,
   )
-  .option("--commit-message <message>", "Commit message")
-  .option("--pull-request-title <title>", "Pull request title")
-  .option("--working-directory <dir>", "Working directory")
+  .option(
+    "--commit-message <message>",
+    "Commit message for localization changes. Defaults to 'feat: update translations via @lingodotdev'",
+  )
+  .option(
+    "--pull-request-title <title>",
+    "Title for the pull request when using --pull-request mode. Defaults to 'feat: update translations via @lingodotdev'",
+  )
+  .option(
+    "--working-directory <dir>",
+    "Directory to run localization from (useful for monorepos where localization files are in a subdirectory)",
+  )
   .option(
     "--process-own-commits [boolean]",
-    "Process commits made by this action",
+    "Allow processing commits made by this CI user (bypasses infinite loop prevention)",
     parseBooleanArg,
   )
   .action(async (options: CIOptions) => {

packages/cli/src/cli/cmd/cleanup.ts

@@ -10,17 +10,24 @@ import { getBuckets } from "../utils/buckets";
 export default new Command()
   .command("cleanup")
   .description(
-    "Remove keys from target files that do not exist in the source file",
+    "Remove translation keys from target locales that no longer exist in the source locale",
   )
   .helpOption("-h, --help", "Show help")
-  .option("--locale <locale>", "Specific locale to cleanup")
-  .option("--bucket <bucket>", "Specific bucket to cleanup")
-  .option("--dry-run", "Show what would be removed without making changes")
+  .option(
+    "--locale <locale>",
+    "Limit cleanup to a specific target locale from i18n.json. Defaults to all configured target locales",
+  )
+  .option(
+    "--bucket <bucket>",
+    "Limit cleanup to a specific bucket type defined under `buckets` in i18n.json",
+  )
+  .option(
+    "--dry-run",
+    "Preview which keys would be deleted without making any changes",
+  )
   .option(
     "--verbose",
-    "Show detailed output including:\n" +
-      "  - List of keys that would be removed.\n" +
-      "  - Processing steps.",
+    "Print detailed output showing the specific keys to be removed for each locale",
   )
   .action(async function (options) {
     const ora = Ora();

packages/cli/src/cli/cmd/config/get.ts

@@ -6,9 +6,12 @@ import dedent from "dedent";
 
 export default new Command()
   .name("get")
-  .description("Get the value of a configuration key")
+  .description("Display the value of a CLI setting from ~/.lingodotdevrc")
   .addHelpText("afterAll", `\nAvailable keys:\n  ${SETTINGS_KEYS.join("\n  ")}`)
-  .argument("<key>", "Configuration key")
+  .argument(
+    "<key>",
+    "Configuration key to read (choose from the available keys listed below)",
+  )
   .helpOption("-h, --help", "Show help")
   .action(async (key: string) => {
     // Validate that the provided key is one of the recognised configuration keys.

packages/cli/src/cli/cmd/config/index.ts

@@ -6,7 +6,9 @@ import getCmd from "./get";
 
 export default new Command()
   .command("config")
-  .description("Manage Lingo.dev CLI configuration")
+  .description(
+    "Manage CLI settings (authentication, API keys) stored in ~/.lingodotdevrc",
+  )
   .helpOption("-h, --help", "Show help")
   .addCommand(setCmd)
   .addCommand(unsetCmd)

packages/cli/src/cli/cmd/config/set.ts

@@ -10,10 +10,13 @@ import {
 
 export default new Command()
   .name("set")
-  .description("Set a configuration key to a value")
+  .description("Set or update a CLI setting in ~/.lingodotdevrc")
   .addHelpText("afterAll", `\nAvailable keys:\n  ${SETTINGS_KEYS.join("\n  ")}`)
-  .argument("<key>", "Configuration key to set")
-  .argument("<value>", "New value")
+  .argument(
+    "<key>",
+    "Configuration key to set (dot notation, e.g., auth.apiKey)",
+  )
+  .argument("<value>", "The configuration value to set")
   .helpOption("-h, --help", "Show help")
   .action(async (key: string, value: string) => {
     if (!SETTINGS_KEYS.includes(key)) {

packages/cli/src/cli/cmd/config/unset.ts

@@ -10,9 +10,12 @@ import {
 
 export default new Command()
   .name("unset")
-  .description("Remove a configuration key")
+  .description("Remove a CLI setting from ~/.lingodotdevrc")
   .addHelpText("afterAll", `\nAvailable keys:\n  ${SETTINGS_KEYS.join("\n  ")}`)
-  .argument("<key>", "Configuration key to remove")
+  .argument(
+    "<key>",
+    "Configuration key to remove (must match one of the available keys listed below)",
+  )
   .helpOption("-h, --help", "Show help")
   .action(async (key: string) => {
     // Validate key first (defensive; choices() should already restrict but keep for safety).

packages/cli/src/cli/cmd/i18n.ts

@@ -39,53 +39,55 @@ import { createDeltaProcessor } from "../utils/delta";
 
 export default new Command()
   .command("i18n")
-  .description("Run Localization engine")
+  .description(
+    "DEPRECATED: Run localization pipeline (prefer `run` command instead)",
+  )
   .helpOption("-h, --help", "Show help")
   .option(
     "--locale <locale>",
-    "Locale to process",
+    "Limit processing to the listed target locale codes from i18n.json. Repeat the flag to include multiple locales. Defaults to all configured target locales",
     (val: string, prev: string[]) => (prev ? [...prev, val] : [val]),
   )
   .option(
     "--bucket <bucket>",
-    "Bucket to process",
+    "Limit processing to specific bucket types defined in i18n.json (e.g., json, yaml, android). Repeat the flag to include multiple bucket types. Defaults to all buckets",
     (val: string, prev: string[]) => (prev ? [...prev, val] : [val]),
   )
   .option(
     "--key <key>",
-    "Key to process. Process only a specific translation key, useful for debugging or updating a single entry",
+    "Limit processing to a single translation key by exact match. Filters all buckets and locales to process only this key, useful for testing or debugging specific translations. Example: auth.login.title",
   )
   .option(
     "--file [files...]",
-    "File to process. Process only a specific path, may contain asterisk * to match multiple files. Useful if you have a lot of files and want to focus on a specific one. Specify more files separated by commas or spaces.",
+    "Filter processing to only buckets whose file paths contain these substrings. Example: 'components' to process only files in components directories",
   )
   .option(
     "--frozen",
-    `Run in read-only mode - fails if any translations need updating, useful for CI/CD pipelines to detect missing translations`,
+    "Validate translations are up-to-date without making changes - fails if source files, target files, or lockfile are out of sync. Ideal for CI/CD to ensure translation consistency before deployment",
   )
   .option(
     "--force",
-    "Ignore lockfile and process all keys, useful for full re-translation",
+    "Force re-translation of all keys, bypassing change detection. Useful when you want to regenerate translations with updated AI models or translation settings",
   )
   .option(
     "--verbose",
-    "Show detailed output including intermediate processing data and API communication details",
+    "Print the translation data being processed as formatted JSON for each bucket and locale",
   )
   .option(
     "--interactive",
-    "Enable interactive mode for reviewing and editing translations before they are applied",
+    "Review and edit AI-generated translations interactively before applying changes to files",
   )
   .option(
     "--api-key <api-key>",
-    "Explicitly set the API key to use, override the default API key from settings",
+    "Override API key from settings or environment variables",
   )
   .option(
     "--debug",
-    "Pause execution at start for debugging purposes, waits for user confirmation before proceeding",
+    "Pause before processing localization so you can attach a debugger",
   )
   .option(
     "--strict",
-    "Stop processing on first error instead of continuing with other locales/buckets",
+    "Stop immediately on first error instead of continuing to process remaining buckets and locales (fail-fast mode)",
   )
   .action(async function (options) {
     updateGitignore();

packages/cli/src/cli/cmd/init.ts

@@ -36,15 +36,21 @@ const throwHelpError = (option: string, value: string) => {
 
 export default new InteractiveCommand()
   .command("init")
-  .description("Initialize Lingo.dev project")
+  .description("Create i18n.json configuration file for a new project")
   .helpOption("-h, --help", "Show help")
   .addOption(
-    new InteractiveOption("-f --force", "Overwrite existing config")
+    new InteractiveOption(
+      "-f --force",
+      "Overwrite existing Lingo.dev configuration instead of aborting initialization (destructive operation)",
+    )
       .prompt(undefined)
       .default(false),
   )
   .addOption(
-    new InteractiveOption("-s --source <locale>", "Source locale")
+    new InteractiveOption(
+      "-s --source <locale>",
+      "Primary language of your application that content will be translated from. Defaults to 'en'",
+    )
       .argParser((value) => {
         try {
           resolveLocaleCode(value as LocaleCode);
@@ -56,7 +62,10 @@ export default new InteractiveCommand()
       .default("en"),
   )
   .addOption(
-    new InteractiveOption("-t --targets <locale...>", "List of target locales")
+    new InteractiveOption(
+      "-t --targets <locale...>",
+      "Target languages to translate to. Accepts locale codes like 'es', 'fr', 'de-AT' separated by commas or spaces. Defaults to 'es'",
+    )
       .argParser((value) => {
         const values = (
           value.includes(",") ? value.split(",") : value.split(" ")
@@ -73,7 +82,10 @@ export default new InteractiveCommand()
       .default("es"),
   )
   .addOption(
-    new InteractiveOption("-b, --bucket <type>", "Type of bucket")
+    new InteractiveOption(
+      "-b, --bucket <type>",
+      "File format for your translation files. Must match a supported type such as json, yaml, or android",
+    )
       .argParser((value) => {
         if (!bucketTypes.includes(value as (typeof bucketTypes)[number])) {
           throwHelpError("bucket format", value);
@@ -85,7 +97,7 @@ export default new InteractiveCommand()
   .addOption(
     new InteractiveOption(
       "-p, --paths [path...]",
-      "List of paths for the bucket",
+      "File paths containing translations when using --no-interactive mode. Specify paths with [locale] placeholder, separated by commas or spaces",
     )
       .argParser((value) => {
         if (!value || value.length === 0) return [];