docs: Improve help text clarity and consistency across all commands

.changes/unreleased/docs-20260104-100757.yaml

@@ -0,0 +1,3 @@
+kind: docs
+body: Improve help text clarity and consistency across all commands with concise descriptions, consistent terminology, and user-focused language
+time: 2026-01-04T10:07:57.3138333Z

src/fabric_cli/core/fab_constant.py

@@ -130,23 +130,23 @@
 }
 
 # Command descriptions
-COMMAND_AUTH_DESCRIPTION = "Authenticate fab with Fabric."
+COMMAND_AUTH_DESCRIPTION = "Authenticate with Fabric."
 COMMAND_AUTH_STATUS_DESCRIPTION = "Display active account and authentication state."
 COMMAND_FS_DESCRIPTION = "Workspace, item and file system operations."
-COMMAND_JOBS_DESCRIPTION = "Manage tasks and jobs."
-COMMAND_TABLES_DESCRIPTION = "Manage tables."
+COMMAND_JOBS_DESCRIPTION = "Manage and schedule jobs."
+COMMAND_TABLES_DESCRIPTION = "Manage Delta tables."
 COMMAND_SHORTCUTS_DESCRIPTION = "Manage shorcuts."
-COMMAND_ACLS_DESCRIPTION = "Manage permissions [admin]."
+COMMAND_ACLS_DESCRIPTION = "Manage access control lists [admin]."
 COMMAND_ACLS_LS_DESCRIPTION = (
-    "List ACLs for a workspace, item, gateway, connection or OneLake."
+    "List ACLs for a workspace, item, gateway, connection, or OneLake resource."
 )
-COMMAND_ACLS_RM_DESCRIPTION = "Remove an ACL from a workspace, gateway or connection."
+COMMAND_ACLS_RM_DESCRIPTION = "Remove an ACL from a workspace, gateway, or connection."
 COMMAND_ACLS_GET_DESCRIPTION = (
-    "Get ACL details for a workspace, item, gateway, connection or OneLake."
+    "Get ACL details for a workspace, item, gateway, connection, or OneLake resource."
 )
-COMMAND_ACLS_SET_DESCRIPTION = "Set ACL on workspace, gateway or connection."
-COMMAND_CONFIG_DESCRIPTION = "Manage configuration settings."
-COMMAND_API_DESCRIPTION = "Make an authenticated API request."
+COMMAND_ACLS_SET_DESCRIPTION = "Set ACLs on a workspace, gateway, or connection."
+COMMAND_CONFIG_DESCRIPTION = "Manage CLI configuration."
+COMMAND_API_DESCRIPTION = "Make authenticated API requests."
 COMMAND_EXTENSIONS_DESCRIPTION = "Manage extensions."
 COMMAND_LABELS_DESCRIPTION = "Manage sensitivity labels [admin]."
 COMMAND_CAPACITIES_DESCRIPTION = "(tenant) Manage capacities [admin]."
@@ -172,23 +172,21 @@
 COMMAND_FS_PWD_DESCRIPTION = "Print the current working directory."
 COMMAND_FS_OPEN_DESCRIPTION = "Open a workspace or item in browser."
 COMMAND_FS_EXPORT_DESCRIPTION = "Export an item."
-COMMAND_FS_GET_DESCRIPTION = "Get a workspace or item property."
-COMMAND_FS_IMPORT_DESCRIPTION = "Import an item (create/modify)."
-COMMAND_FS_SET_DESCRIPTION = "Set a workspace or item property."
+COMMAND_FS_GET_DESCRIPTION = "Get workspace or item properties."
+COMMAND_FS_IMPORT_DESCRIPTION = "Import an item to create or update it."
+COMMAND_FS_SET_DESCRIPTION = "Set workspace or item properties."
 COMMAND_FS_CLEAR_DESCRIPTION = "Clear the terminal screen."
 COMMAND_FS_LN_DESCRIPTION = "Create a shortcut."
 COMMAND_FS_START_DESCRIPTION = "Start a resource."
 COMMAND_FS_STOP_DESCRIPTION = "Stop a resource."
-COMMAND_FS_ASSIGN_DESCRIPTION = "Assign a resource to a workspace."
+COMMAND_FS_ASSIGN_DESCRIPTION = "Assign a capacity or resource to a workspace."
 COMMAND_FS_UNASSIGN_DESCRIPTION = "Unassign a resource from a workspace."
 COMMAND_FS_LS_DESCRIPTION = "List workspaces, items, and files."
-COMMAND_FS_MKDIR_DESCRIPTION = "Create a new workspace, item, or directory."
+COMMAND_FS_MKDIR_DESCRIPTION = "Create a workspace, item, or directory."
 COMMAND_FS_RM_DESCRIPTION = "Delete a workspace, item, or file."
 
 # Label command descriptions
-COMMAND_LABELS_LIST_LOCAL_DESCRIPTION = (
-    "List labels from `local_definition_labels` setting."
-)
+COMMAND_LABELS_LIST_LOCAL_DESCRIPTION = "List configured sensitivity labels."
 COMMAND_LABELS_SET_DESCRIPTION = "Set a sensitivity label on an item."
 COMMAND_LABELS_RM_DESCRIPTION = "Remove a sensitivity label from an item."
 

src/fabric_cli/parsers/fab_acls_parser.py

@@ -11,12 +11,12 @@
 
 commands = {
     "Commands": {
-        get_os_specific_command("ls"): "List ACLs for a workspace, item, or OneLake.",
+        get_os_specific_command("ls"): "List ACLs for a workspace, item, or OneLake resource.",
         get_os_specific_command(
             "rm"
-        ): "Remove an ACL from a workspace, gateway or connection.",
-        "set": "Set access controls on a workspace.",
-        "get": "Get ACL details for a workspace, item or OneLake.",
+        ): "Remove an ACL from a workspace, gateway, or connection.",
+        "set": "Set ACLs on a workspace, gateway, or connection.",
+        "get": "Get ACL details for a workspace, item, or OneLake resource.",
     },
 }
 

src/fabric_cli/parsers/fab_auth_parser.py

@@ -11,7 +11,7 @@
 commands = {
     "Commands": {
         "login": "Log in to a Fabric account.",
-        "logout": "Log out of a Fabric account.",
+        "logout": "End the current authentication session.",
         "status": "Display active account and authentication state.",
     },
 }

src/fabric_cli/parsers/fab_config_parser.py

@@ -13,7 +13,7 @@
 commands = {
     "Commands": {
         "clear-cache": "Clear the CLI cache.",
-        "get": "Print the value of a given configuration key.",
+        "get": "Get the value of a configuration key.",
         get_os_specific_command("ls"): "List all configuration keys and their values.",
         "set": "Set a configuration key to a specified value.",
     }

src/fabric_cli/parsers/fab_jobs_parser.py

@@ -11,9 +11,9 @@
 
 commands = {
     "Commands": {
-        "start": "Start an item (async).",
-        "run": "Run an item (sync).",
-        "run-cancel": "Cancel an item or scheduled run.",
+        "start": "Start an item asynchronously.",
+        "run": "Run an item synchronously.",
+        "run-cancel": "Cancel a running or scheduled job.",
         "run-list": "Retrieve the status of an item or scheduled job run.",
         "run-update": "Update a scheduled job.",
         "run-rm": "Remove a scheduled job.",

src/fabric_cli/parsers/fab_labels_parser.py

@@ -11,9 +11,9 @@
 
 commands = {
     "Commands": {
-        "list-local": "List labels from 'local_definition_labels' setting.",
-        "set": "Set a sensitivity label.",
-        get_os_specific_command("rm"): "Remove a sensitivity label.",
+        "list-local": "List configured sensitivity labels.",
+        "set": "Set a sensitivity label on an item.",
+        get_os_specific_command("rm"): "Remove a sensitivity label from an item.",
     },
 }
 

src/fabric_cli/parsers/fab_tables_parser.py

@@ -10,9 +10,9 @@
 
 commands = {
     "Commands": {
-        "load": "Load data into a table in the lakehouse.",
+        "load": "Load data into a lakehouse table.",
         "optimize": "Optimize a Delta table.",
-        "schema": "Display the schema of a Delta table.",
+        "schema": "Show the schema of a Delta table.",
         "vacuum": "Vacuum a Delta table by removing old files.",
     },
 }

src/fabric_cli/utils/fab_commands.py

@@ -6,23 +6,23 @@
 
 COMMANDS = {
     "Core Commands": {
-        "assign": "Assign a resource to a workspace.",
-        "cd": "Change to the specified directory.",
+        "assign": "Assign a capacity or resource to a workspace.",
+        "cd": "Change to a workspace, item, or folder.",
         get_os_specific_command("cp"): "Copy an item or file to a destination.",
         "export": "Export an item.",
         "exists": "Check if a workspace, item, or file exists.",
-        "get": "Get a workspace or item property.",
-        "import": "Import an item to create or modify it.",
+        "get": "Get workspace or item properties.",
+        "import": "Import an item to create or update it.",
         get_os_specific_command("ls"): "List workspaces, items, and files.",
         get_os_specific_command("ln"): "Create a shortcut.",
-        "mkdir": "Create a new workspace, item, or directory.",
+        "mkdir": "Create a workspace, item, or directory.",
         get_os_specific_command("mv"): "Move an item or file.",
         "open": "Open a workspace or item in the browser.",
         "pwd": "Print the current working directory.",
         get_os_specific_command(
             "rm"
         ): "Delete a workspace, item, or file. Use with caution.",
-        "set": "Set a workspace or item property.",
+        "set": "Set workspace or item properties.",
         "start": "Start a resource.",
         "stop": "Stop a resource.",
         "unassign": "Unassign a resource from a workspace.",