diff --git a/.changes/unreleased/docs-20260104-100757.yaml b/.changes/unreleased/docs-20260104-100757.yaml new file mode 100644 index 00000000..cde1661b --- /dev/null +++ b/.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 diff --git a/src/fabric_cli/core/fab_constant.py b/src/fabric_cli/core/fab_constant.py index 2e21356b..66b3ede2 100644 --- a/src/fabric_cli/core/fab_constant.py +++ b/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." diff --git a/src/fabric_cli/parsers/fab_acls_parser.py b/src/fabric_cli/parsers/fab_acls_parser.py index db822693..590cd608 100644 --- a/src/fabric_cli/parsers/fab_acls_parser.py +++ b/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.", }, } diff --git a/src/fabric_cli/parsers/fab_auth_parser.py b/src/fabric_cli/parsers/fab_auth_parser.py index 56e2442b..da378eae 100644 --- a/src/fabric_cli/parsers/fab_auth_parser.py +++ b/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.", }, } diff --git a/src/fabric_cli/parsers/fab_config_parser.py b/src/fabric_cli/parsers/fab_config_parser.py index 6ad0b3b7..f63957c1 100644 --- a/src/fabric_cli/parsers/fab_config_parser.py +++ b/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.", } diff --git a/src/fabric_cli/parsers/fab_jobs_parser.py b/src/fabric_cli/parsers/fab_jobs_parser.py index 65194516..3bb79355 100644 --- a/src/fabric_cli/parsers/fab_jobs_parser.py +++ b/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.", diff --git a/src/fabric_cli/parsers/fab_labels_parser.py b/src/fabric_cli/parsers/fab_labels_parser.py index b5b4e4f4..5b3e442f 100644 --- a/src/fabric_cli/parsers/fab_labels_parser.py +++ b/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.", }, } diff --git a/src/fabric_cli/parsers/fab_tables_parser.py b/src/fabric_cli/parsers/fab_tables_parser.py index e4db5d2c..31a93abd 100644 --- a/src/fabric_cli/parsers/fab_tables_parser.py +++ b/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.", }, } diff --git a/src/fabric_cli/utils/fab_commands.py b/src/fabric_cli/utils/fab_commands.py index 46ec8b1f..f40cba3c 100644 --- a/src/fabric_cli/utils/fab_commands.py +++ b/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.",