refactor: enhance help text for CLI commands

.changeset/yellow-cherries-sin.md

@@ -0,0 +1,2 @@
+---
+---

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

@@ -11,7 +11,7 @@ export default new Command()
   .command("auth")
   .description("Authenticate with Lingo.dev API")
   .helpOption("-h, --help", "Show help")
-  .option("--logout", "Delete existing authentication")
+  .option("--logout", "Delete existing authentication and clear your saved API key")
   .option("--login", "Authenticate with Lingo.dev API")
   .action(async (options) => {
     try {

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

@@ -14,7 +14,9 @@ export default new Command()
   .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("--verbose", "Show verbose output")
+  .option("--verbose", "Show detailed output including:\n" +
+                       "  - List of keys that would be removed.\n" +
+                       "  - Processing steps.")
   .action(async function (options) {
     const ora = Ora();
     const results: any = [];

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

@@ -24,14 +24,14 @@ export default new Command()
   .helpOption("-h, --help", "Show help")
   .option("--locale <locale>", "Locale to process", (val: string, prev: string[]) => (prev ? [...prev, val] : [val]))
   .option("--bucket <bucket>", "Bucket to process", (val: string, prev: string[]) => (prev ? [...prev, val] : [val]))
-  .option("--key <key>", "Key to process")
-  .option("--frozen", `Don't update the translations and fail if an update is needed`)
-  .option("--force", "Ignore lockfile and process all keys")
-  .option("--verbose", "Show verbose output")
-  .option("--interactive", "Interactive mode")
-  .option("--api-key <api-key>", "Explicitly set the API key to use")
-  .option("--debug", "Debug mode")
-  .option("--strict", "Stop on first error")
+  .option("--key <key>", "Key to process. Process only a specific translation key, useful for debugging or updating a single entry")
+  .option("--frozen", `Run in read-only mode - fails if any translations need updating, useful for CI/CD pipelines to detect missing translations`)
+  .option("--force", "Ignore lockfile and process all keys, useful for full re-translation")
+  .option("--verbose", "Show detailed output including intermediate processing data and API communication details")
+  .option("--interactive", "Enable interactive mode for reviewing and editing translations before they are applied")
+  .option("--api-key <api-key>", "Explicitly set the API key to use, override the default API key from settings")
+  .option("--debug", "Pause execution at start for debugging purposes, waits for user confirmation before proceeding")
+  .option("--strict", "Stop processing on first error instead of continuing with other locales/buckets")
   .action(async function (options) {
     updateGitignore();
 

packages/cli/src/cli/cmd/show/files.ts

@@ -9,8 +9,8 @@ import { resolveOverriddenLocale } from "@lingo.dev/_spec";
 export default new Command()
   .command("files")
   .description("Print out the list of files managed by Lingo.dev")
-  .option("--source", "Only show source files")
-  .option("--target", "Only show target files")
+  .option("--source", "Only show source files, files containing the original translations")
+  .option("--target", "Only show target files, files containing translated content")
   .helpOption("-h, --help", "Show help")
   .action(async (type) => {
     const ora = Ora();