fix: update command long descriptions

messages/cancel.json

@@ -1,9 +1,8 @@
 {
-  "description": "cancel a source deployment",
+  "description": "cancel a source deployment\n Use this command to cancel a specified asynchronous source deployment. You can also specify a wait time (in minutes) to check for updates to the canceled deploy status.\n\nTo run the command asynchronously, set --wait to 0, which immediately returns the job ID. This way, you can continue to use the CLI.\nTo check the status of the job, use force:source:deploy:report.",
   "examples": [
-    "$ sfdx force:source:deploy:cancel",
-    "$ sfdx force:source:deploy:cancel -w 2",
-    "$ sfdx force:source:deploy:cancel -i <jobid>"
+    "Deploy a directory of files to the org\n  $ sfdx force:source:deploy -d <directory>\nNow cancel this deployment and wait two minutes\n  $ sfdx force:source:deploy:cancel -w 2",
+    "If you have multiple deployments in progress and want to cancel a specific one, specify the job ID\n  $ sfdx force:source:deploy:cancel -i <jobid>\nCheck the status of the cancel job\n  $ sfdx force:source:deploy:report"
   ],
   "flags": {
     "wait": "wait time for command to finish in minutes",

messages/convert.json

@@ -1,5 +1,5 @@
 {
-  "description": "convert source into Metadata API format",
+  "description": "convert source into Metadata API format \n Converts source-formatted files into metadata that you can deploy using Metadata API. \nTo convert source-formatted files into the metadata format, so that you can deploy them using Metadata API,\nrun \"sfdx force:source:convert\". Then deploy the metadata using \"sfdx force:mdapi:deploy\".\n\nTo convert Metadata API–formatted files into the source format, run \"sfdx force:mdapi:convert\".\n\nTo specify a package name that includes spaces, enclose the name in single quotes.",
   "examples": [
     "$ sfdx force:source:convert -r path/to/source",
     "$ sfdx force:source:convert -r path/to/source -d path/to/outputdir -n 'My Package'"

messages/deploy.json

@@ -1,17 +1,17 @@
 {
-  "description": "deploy source to an org",
+  "description": "deploy source to an org Use this command to deploy source (metadata that’s in source format) to an org.\nTo take advantage of change tracking with scratch orgs, use \"sfdx force:source:push\".\nTo deploy metadata that’s in metadata format, use \"sfdx force:mdapi:deploy\".\n\nThe source you deploy overwrites the corresponding metadata in your org. This command does not attempt to merge your source with the versions in your org.\n\nTo run the command asynchronously, set --wait to 0, which immediately returns the job ID. This way, you can continue to use the CLI.\nTo check the status of the job, use force:source:deploy:report.\n\nIf the comma-separated list you’re supplying contains spaces, enclose the entire comma-separated list in one set of double quotes. On Windows, if the list contains commas, also enclose the entire list in one set of double quotes.\n",
   "examples": [
-    "$ sfdx force:source:deploy -p path/to/source",
-    "$ sfdx force:source:deploy -p \"path/to/apex/classes/MyClass.cls,path/to/source/objects\"",
-    "$ sfdx force:source:deploy -p \"path/to/objects/MyCustomObject/fields/MyField.field-meta.xml, path/to/apex/classes\"",
-    "$ sfdx force:source:deploy -m ApexClass",
-    "$ sfdx force:source:deploy -m ApexClass:MyApexClass",
-    "$ sfdx force:source:deploy -m \"CustomObject,ApexClass\"",
-    "$ sfdx force:source:deploy -m \"ApexClass, Profile:My Profile, Profile: AnotherProfile\"",
-    "$ sfdx force:source:deploy -x path/to/package.xml",
-    "$ sfdx force:source:deploy -m ApexClass -l RunLocalTests",
-    "$ sfdx force:source:deploy -m ApexClass -l RunAllTestsInOrg -c",
-    "$ sfdx force:source:deploy -q 0Af9A00000FTM6pSAH"
+    "To deploy the source files in a directory:\n\t $ sfdx force:source:deploy -p path/to/source",
+    "To deploy a specific Apex class and the objects whose source is in a directory: \n\t$ sfdx force:source:deploy -p \"path/to/apex/classes/MyClass.cls,path/to/source/objects\"",
+    "To deploy source files in a comma-separated list that contains spaces:\n   $ sfdx force:source:deploy -p \"path/to/objects/MyCustomObject/fields/MyField.field-meta.xml, path/to/apex/classes\"",
+    "To deploy all Apex classes:\n   $ sfdx force:source:deploy -m ApexClass",
+    "To deploy a specific Apex class:\n   $ sfdx force:source:deploy -m ApexClass:MyApexClass",
+    "To deploy all custom objects and Apex classes:\n   $ sfdx force:source:deploy -m \"CustomObject,ApexClass\"",
+    "To deploy all Apex classes and two specific profiles (one of which has a space in its name):\n   $ sfdx force:source:deploy -m \"ApexClass, Profile:My Profile, Profile: AnotherProfile\"",
+    "To deploy all components listed in a manifest:\n   $ sfdx force:source:deploy -x path/to/package.xml",
+    "To run the tests that aren’t in any managed packages as part of a deployment:\n   $ sfdx force:source:deploy -m ApexClass -l RunLocalTests",
+    "To check whether a deployment would succeed (to prepare for Quick Deploy):\n   $ sfdx force:source:deploy -m ApexClass -l RunAllTestsInOrg -c",
+    "To deploy an already validated deployment (Quick Deploy):\n    $ sfdx force:source:deploy -q 0Af9A00000FTM6pSAH`,"
   ],
   "flags": {
     "sourcePath": "comma-separated list of source file paths to deploy",

messages/open.json

@@ -1,5 +1,5 @@
 {
-  "description": "edit a Lightning Page with Lightning App Builder\nOpens the specified Lightning Page in Lightning App Builder. Lightning Page files have the suffix .flexipage-meta.xml, and are stored in the flexipages directory. If you specify a different type of file, this command opens your org’s home page.",
+  "description": "edit a Lightning Page with Lightning App Builder\nOpens the specified Lightning Page in Lightning App Builder. Lightning Page files have the suffix .flexipage-meta.xml, and are stored in the flexipages directory. If you specify a different type of file, this command opens your org’s home page.\n\nThe file opens in your default browser.\nIf no browser-based editor is available for the selected file, this command opens your org's home page.\nTo generate a URL for the browser-based editor but not open the editor, use --urlonly.",
   "examples": [
     "$ sfdx force:source:open -f path/to/source",
     "$ sfdx force:source:open -r -f path/to/source",

messages/report.json

@@ -1,5 +1,5 @@
 {
-  "description": "check the status of a metadata deployment",
+  "description": "check the status of a metadata deployment \nSpecify the job ID for the deploy you want to check. You can also specify a wait time (minutes) to check for updates to the deploy status.",
   "examples": [
     "Deploy a directory of files to the org",
     " $ sfdx force:source:deploy -d <directory>",

messages/retrieve.json

@@ -1,16 +1,16 @@
 {
-  "description": "retrieve source from an org",
+  "description": "retrieve source from an org \nUse this command to retrieve source (metadata that’s in source format) from an org.\nTo take advantage of change tracking with scratch orgs, use \"sfdx force:source:pull\".\nTo retrieve metadata that’s in metadata format, use \"sfdx force:mdapi:retrieve\".\n\nThe source you retrieve overwrites the corresponding source files in your local project. This command does not attempt to merge the source from your org with your local source files.\n\nIf the comma-separated list you’re supplying contains spaces, enclose the entire comma-separated list in one set of double quotes. On Windows, if the list contains commas, also enclose it in one set of double quotes.",
   "examples": [
-    "sfdx force:source:retrieve -p path/to/source",
-    "sfdx force:source:retrieve -p \"path/to/apex/classes/MyClass.cls,path/to/source/objects\"",
-    "sfdx force:source:retrieve -p \"path/to/objects/MyCustomObject/fields/MyField.field-meta.xml, path/to/apex/classes\"",
-    "sfdx force:source:retrieve -m ApexClass",
-    "sfdx force:source:retrieve -m ApexClass:MyApexClass",
-    "sfdx force:source:retrieve -m \"CustomObject,ApexClass\"",
-    "sfdx force:source:retrieve -x path/to/package.xml",
-    "sfdx force:source:retrieve -n \"Package1, PackageName With Spaces, Package3\"",
-    "sfdx force:source:retrieve -n MyPackageName -p path/to/apex/classes",
-    "sfdx force:source:retrieve -n MyPackageName -x path/to/package.xml"
+    "To retrieve the source files in a directory:\n   $ sfdx force:source:retrieve -p path/to/source",
+    "To retrieve a specific Apex class and the objects whose source is in a directory:\n   $ sfdx force:source:retrieve -p \"path/to/apex/classes/MyClass.cls,path/to/source/objects\"",
+    "To retrieve source files in a comma-separated list that contains spaces:\n   $ sfdx force:source:retrieve -p \"path/to/objects/MyCustomObject/fields/MyField.field-meta.xml, path/to/apex/classes",
+    "To retrieve all Apex classes:\n   $ sfdx force:source:retrieve -m ApexClass",
+    "To retrieve a specific Apex class:\n   $ sfdx force:source:retrieve -m ApexClass:MyApexClass",
+    "To retrieve all custom objects and Apex classes:\n   $ sfdx force:source:retrieve -m \"CustomObject,ApexClass",
+    "To retrieve all Apex classes and two specific profiles (one of which has a space in its name):\n   $ sfdx force:source:retrieve -m \"ApexClass, Profile:My Profile, Profile: AnotherProfile\"",
+    "To retrieve all metadata components listed in a manifest:\n   $ sfdx force:source:retrieve -x path/to/package.xml",
+    "To retrieve metadata from a package or multiple packages:\n   $ sfdx force:source:retrieve -n MyPackageName\n   $ sfdx force:source:retrieve -n \"Package1, PackageName With Spaces, Package3\"",
+    "To retrieve all metadata from a package and specific components that aren’t in the package, specify both -n | --packagenames and one other scoping parameter:\n   $ sfdx force:source:retrieve -n MyPackageName -p path/to/apex/classes\n   $ sfdx force:source:retrieve -n MyPackageName -m ApexClass:MyApexClass\n   $ sfdx force:source:retrieve -n MyPackageName -x path/to/package.xml"
   ],
   "flags": {
     "sourcePath": "comma-separated list of source file paths to retrieve",